Tweaking Kentico (3): Macro rules

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