Tweaking Kentico (3): Macro rules

   —   

Today we’ll learn a bit about macro rules in Kentico.

Macro rules become very useful when it comes to defining further conditions for your discounts, marketing automation processes, workflows, reports, validation of forms and many others. They allow you to take advantage of macros with no actual knowledge of their syntax. Marco rules are simply predefined sets of macros in given macro syntax (K#) re-written in common language to make them easier to use.

When a macro is possible to add to one of the mentioned objects, Kentico offers you a macro editor with 2 default options:

  1. Rule designer
  2. Code

The Rule designer loads all possible macro rules that could be applied in given context and you just use predefined UI to configure them, while the Code tab loads just a simple editor that enables you to enter the pure K# macro code.

Macro rules can be defined in 6 categories and according to the category the macro rule belongs to, it appears in a different administration interface. The following table shows what context is available for particular rule category (the table doesn’t contain all properties – just those important ones):

Category

Available context

Available collections

Available properties

global

     

form validation

 

Fields

Value

workflow

ActionDefinition

ActionResource, Metafiles, Thumbnail

ActionAllowedObjects, ActionAssemblyName, ActionClass, ActionDescription, ActionDisplayName, ActionEnabled, ActionID, ActionName, ActionResourceID

 

CurrentStep

StepAction, StepWorkflow

StepActionID, StepAllowPublish, StepAllowReject, StepApporvedTemplateName, StepDisplayName, StepHasTimeout, StepIsAction, StepIsAllowed, StepIsArchived, StepIsDefault, StepIsDeleteable, StepIsEdit, StepIsFinished, StepIsPublished, StepIsStart, StepName, StepOrder, StepRolesSecurity, StepSendEmails, StepType, StepWorkflowID, StepActionID

 

CurrentUser

Memberships, Orders, Personalizations, PurchasedProducts

IsMale, IsFemale, Email, FirstName, LastName, FullName, LastLogon, PreferredCultureCode, PreferredUICultureCode, UserAvatarID, UserGender, UserIsDomain, USerISEditor, UserISHidden, UserName, UserPhone, UserPicture, UserPosition, UserSignature, UserVisibility

 

Document

Attachments, Categories, CultureVersions, DocumentAliases, DocumentContent, EventAttendees, NodeACLs, NodeClass, NodeTemplate, Personalization, RelatedDocuments

HasSKU, IsLink, IsLastVersion, SiteID, RelativeURL, AbsoluteURL, DocumentID, DocumentName, NodeAliasPath, NodeHasChildren, NodeLevel, NodeOrder, NodeSKUID

 

Workflow

WorkflowScopes, WorkflowSteps

WorkflowAllowedObjects, WorkflowEnabled, WorkflowDisplayName, WorkflowNotificationTemplateName, WorkflowSendApproveEmails, WorkflowSendEmails, WorkflowType

on-line marketing

Activity

ActivityOriginalContact, Board, Form, Newsletter, Issue, Poll,

ActivityId, ActivityComment, ActivityCampaign, ActivityCulture, ActivityIPAddress, ActivityNodeID, ActivityOriginalContactID, ActivityTitle, ActivityURL, ActivityValue

 

Contact

Accounts, Activities, ContactCountry, ContactPersona, ContactState, Contact, Status, IPs, Orders, Processes, PurchasedProducts, Roles, UserAgents

ContactAddress, ContactCity, ContactCountryID, ContactGender, ContactID, ContactIsAnonymous, ContactLastLogon, ContactNotes, ContactFirstName, ContactLastName

reporting

     

catalog rules

SKU

   

order rules

BillingAddress

AddressCountry, AddressState

AdressCity, AddressCountryID, AddressLine1, AddressLine2, AddressPersonalName, AddressPhone, AddressStateID, AddressZip

 

CompanyAddress

   
 

Currency

 

CurrencyCode, CurrencyDisplayName, CurrencyEnabled, CurrencyID, CurrencyIsMain, CurrencyNAme, CurrencyRoundTo

 

Customer

Addresses, AllOlders, CreditEvents, Customercountry, CustomerState, CustomerUser, Memberships, Orders, PurchasedProducts, Whishlist

CustomerCompany, CustomerFirstName, CustomerLastName, CustomerPhone, CustomerID, CustomerUserID, CustomerStateID, CustomerPrefferedCurencyID, CurrencyPrefferedShippingOptionID, CustomerPreferredPaymentOptionID

 

PaymentOption

   
 

ShippingAddress

   
 

ShippingOption

   
 

ShoppingCart

CartProducts, ShoppingCartItems, ShoppingCartDiscountCoupon, ShoppingCartUser

HasUsableCoupon, IsEmpty, IsDiscountApplied, IsShippingNeeded, ItemsDiscount, OrderDiscount,

 

Except for the table above, any macro rule can also be extended by any number of custom properties. You can do this while editing your macro rule in the Parameters section and the parameter is then available in the rule using {parameterCodeName} syntax. There are also automatic parameters available for all macro rules.

Now, let’s create some macro rules because working examples are the best way to learn how things work. Here are two macro rule examples:

1. Form validation

Let’s say we want to have a validation rule that checks if entered email address is from a particular top level domain (.com, .net or .org). We need to create a macro rule first:

  • Display name: Top level domain
  • User text: E-mail address ends with {topleveldomain}
  • Condition: Value.EndsWith("{topleveldomain}")

The most important part is the Condition that takes the value of the field you apply this condition to and checks whether it ends with selected parameter. Those 3 options would be a parameter for our validation rule and we make it as a dropdown list:

  • Field name: topleveldomain
  • Data type: Text
  • Size: 4
  • Required: true
  • Field caption: select top level domain
  • Form control: Drop-down list
  • Data source: List of options
    • .com
    • .net
    • .org

Now you can use this new validation rule for instance in your on-line form.

2. Catalog rules

As you probably know a product in Kentico is made out of two objects -> an SKU and a Page. The SKU object holds the information about the price, inventory, product image, etc., while the page has all the other details containing product specific custom properties.

Here is an example of applying a discount to a product based on a custom page property (e.g. discount for all laptops with LED display type).

First, we can create the macro rule:

  • Display name: Product field contains
  • User text: Product's field {field} of {classname} contains {value}
  • Condition: Documents.ClassNames("{classname}").WithAllData.Where("NodeSKUID="+SKU.SKUID).FirstItem.GetValue("{field}").Contains("{value}")

As we learned in previous macro rule, we need to specify parameters used in our condition:

  • Field name: classname
  • Data type: Text
  • Size: 200
  • Required: true
  • Field caption: select page type
  • Form control: Page types selector
  • Field name: field
  • Data type: Text
  • Size: 1000
  • Required: true
  • Field caption: enter field name
  • Form control: Text box
  • Field name: value
  • Data type: Text
  • Size: 1000
  • Required: true
  • Field caption: enter value
  • Form control: Text box

The Apply to condition for a catalog discount would look like this:

Product's field LaptopDisplayType of Laptop (CMS.Laptop) contains LED

Share this article on   LinkedIn