Tag Archives: sitecore how-to

Extend Sitecore Engagement Plan UI to assign contacts to an engagement plan state

The default Sitecore Engagement Plan currently supports the following option to assign users/contacts to an engagement plan state

  • Add from CSV File
  • Add a Sitecore user
  • Add all Members of a Sitecore Role
  • Add a Segment

Out off all those options only the segment option have the capability of assigning existing contacts to an engagement plan state.

However, what if we would like to import contacts from a CSV file there’s no option to do so, the Add from CSV file will import the data as Sitecore users instead of contacts.

We would need to modify the UI in order to achieve the functionality that we’re aiming for. To do so first we would need to figure which file to modify.

As the UI is using Silverlight it’s a bit difficult to figure which file we need to modify, however searching for the “Welcome to the Import Contacts Wizard” text under the /sitecore  folder reveals that this file seems to be the correct one

Further inspecting the code inside that file and tinkering with it a bit confirms that this is the correct file to modify.

We will not modify the existing Sitecore file, instead we will use the Override folder in order to apply our modification to the existing XML control. To do this copy and paste the existing ImportVisitors.xml file to the override folder

You can put the file directly inside the Override folder, but it’s good practice to replicate the original folder paths so you know which file you’re overriding. After we now know which file to modify we can start modifying the default behaviour of that XML control.

The modified ImportVisitors.xml


The code beside file


The end result

Source Code is available in GitHub



Sitecore Server Role Checker Tool

When configuring Sitecore in a distributed environment, you typically have more than 1 server in the production environment configured as a different roles (CM, CD, Processing, Reporting Service, etc).

More often than not I’ve noticed that issues are raised due to misconfiguration rather than implementation itself. You then go to Sitecore documentation site and check the configuration for each of the server that you’ve setup to see if there’s anything that you miss.

In the 8.0 documentation you would need to read a long list of tables containing information which config files that you need to enable/disable.

Since the 8.1 release, these steps are simplified with Sitecore providing us an excel spreadsheet file as a guide to enable/disable the config files depending on the role(s) that you want to setup. These steps are manual though and highly likely that we will miss one or two config files and could cause some issues down the line.

With the number of projects that you need to review, this task will start eating up your time and should really be automated. Some might have already done so and create a little tool tucked away somewhere.

I’ve decided to create my own version of the tool called Sitecore Server Role Checker, can’t be more obvious than that 🙂

How does it work?

This tool would basically uses a converted csv format from the Sitecore official spreadsheet guide and read the configuration based on your selected roles. It currently supports the following Sitecore version

  • 8.1 update 3
  • 8.2 initial release
  • 8.2 update 1
  • 8.2 update 2

Only those version is supported as those are only the spreadsheet available for now.

How do I use it?

Follow this simple steps

  1. Choose your Sitecore version
  2. Choose your search engine provider
  3. Browse to your website folder
  4. Tick your intended role(s) for this particular Sitecore instance
  5. Click the Analyze button

It would then go through each of your configuration files and report if there’s any config files that should be enabled/disabled.

Through the tool you can also quickly disable/enable those config files.

What it doesn’t do

  • Check if your config files is updated accordingly, e.q:
    • Changing robot detection handler in CM
    • Configuring remote reporting service url
    • etc
  • Check the configuration files for WFFM, EXM.. yet
  • Make you coffee

Where can I get it?

The code is available in Github

Note that this tool is not deeply tested, if you have any issues or suggestions with the tool then raise a ticket in Github or do a PR

update: 22 February 2017

The tool is now available at Sitecore Marketplace

Sitecore 8 – Create a custom personalization rule

Sitecore OOTB comes with tons of personalization rules that we can use, however there might be times where we need to create a custom rule condition that fits to the client business requirements.

Luckily with Sitecore framework that’s known easy to extend, we can easily achieve this.

Here’s the steps to create a custom personalization rule:

1.Register the tag

First of all we need to create a new tag item under /sitecore/system/Settings/Rules/Definitions/Tags


2. Register a new rule element

Create a new element folder in /sitecore/system/Settings/Rules/Definitions/Elements


3. Create a new personalization condition rule


Here I’m creating a new rule and calling it “Specific Template Name” which will do what exactly that, checking if the current context item is based on a specific template name – not really useful in real world scenario but this post is about how to setup a custom personalization rule 🙂

In the newly created rule we need to set the Text and Type fields

Text field contains the text that we’re going to present to the content author, here’s the following text that I use

the [TemplateName, StringOperator,,compares to] represents the format of input that we want to get from the content author. It follows the following format

  • OperatorId, defines the public property of the class where we want to assign the value coming from the content author input
  • StringOperator, the built-in macro that we want to use to get the input from the user. In this case this will be a string comparation operation
  • blank, this parameter will depend on the type of macro that we use, this could be a default text value if we are using the default macro,  it could be a default start path if we’re using the Tree macro  – think of it like setting a field source when we’re building a template in Sitecore. A full list of macros can be found in /sitecore/system/Settings/Rules/Definitions/Macros
  • compares to, the last parameter is the text representation that we want to show to the content author, this value is clickable and when clicked Sitecore will display the appropriate input control based on the macro that we set on the second parameter

The Type field is the full assembly name of the custom class that we want to use to perform the logic behind this personalization rule

4. Assign our custom element default tag definition to our custom tag


Of course we  can assign our custom element tag definition to one of the existing tag under /sitecore/system/Settings/Rules/Definitions/Tags so that it will automatically appear on the content author personalization rule window however if you want to make it obvious which one is your custom ones then I recommend creating your own custom tag and assign it to that

5. Assign the tag to Conditional Rendering

The last step to make the rule visible for the content author to choose from is to assign our custom tag to one of default Rules Context folder


From the picture we’re setting the tag to the Conditional Rendering rules context which will appear when the user want to personalize a certain component, but you can also some other Rules Context folders such as FXM ones.

After we assign the tag, we can verify that the custom personalization rule is available for the content author to choose from


Here’s the class that’s responsible to evaluate the custom rule condition

The class logic is simple and not doing much for the purposes of the tutorial. In a real world scenario you can make a rule that reads from a custom database, read a configuration file, call an external API (be careful with this as it will increase page load time).

This may sound like a lot of work at first compared to just creating a custom code in the rendering or similar approach. But when we consider that we’re enabling the content author/marketers to do it by themselves and removing/minimizing the dependency towards IT, it would lessen time to market and open up more possibilities for the marketers of what they can do using the platform.



How to create a custom ribbon in Sitecore Content Editor

In this how to article we will learn how to create a new ribbon section in the toolbar of Sitecore Content Editor and how to use the various controls available to be used in the ribbon.

How the ribbon is structured

Let’s take for example the Home ribbon.


it consist of

  • One strip, as a container of multiple chunks such as Edit, Insert, Operations, Rename, and Sorting
  • Inside of those chunks there’s the actual buttons

In summary Toolbar -> Ribbon -> Strip -> Chunk -> Button

This is what we want to achieve in this article:


Here’s how we can do that

First step, create the new ribbon

  • switch to the core database
  • under /sitecore/content/Applications/Content Editor/Ribbons/Default create a new item with using the Reference template ({EF295CD8-19D4-4E02-9438-94C926EF5284}) and name it Custom Ribbon
  • notice that the reference template on has one field which is the Reference field, we need to pass in the item id of our next item
  • under /sitecore/content/Applications/Content Editor/Ribbons/Strips create a new item with using the Strip template ({EC6D62A5-5D00-4329-8958-8AC1AD100EBB}) and name it Custom Strip
    • in the Header field insert “Custom”
    • in the ID field insert “CustomStrip”
    • in the Access Key field insert “C”, this is useful for your content editor so that they can access the ribbon by using the ALT+C key combination
    • Copy the item id and assign it to the /sitecore/content/Applications/Content Editor/Ribbons/Default/Custom Ribbon Reference field
  • under /sitecore/content/Applications/Content Editor/Ribbons/Strips/Custom Strip create a new item with using the Reference template ({EF295CD8-19D4-4E02-9438-94C926EF5284}) and name it Small Buttons
  • under /sitecore/content/Applications/Content Editor/Ribbons/Chunks create a new item with using the Chunk template ({8F3D8F9B-2D76-4ACE-803F-35415D2B230A}) and name it Custom Chunk
    • in the Header field insert “Custom Chunk – Small”
    • in the ID field insert “CustomChunkSmall”
    • Copy the item id and assign it to the /sitecore/content/Applications/Content Editor/Ribbons/Strips/Custom Strip/Small Buttons Reference field
  • under /sitecore/content/Applications/Content Editor/Ribbons/Chunks/Custom Chunk create a new item with Small Button template ({9F62EBD5-2280-4A35-BE51-A210D831D687}) and name it Small Button
    • in the Header field insert “Small Button”
    • in the ID field insert “SmallButton”

now you can see the ribbon with your newly created button.


Seems like a long step just to get our custom ribbon showing, that’s because there need to be at least one item in the ribbon before Sitecore can display your custom ribbon

Now you get the general idea of how to create a custom ribbon on the Content Editor. After we have our custom ribbon ready we could start adding various controls to it, the available controls that we can use are

  • Small Button/Large Button
  • Small Check Button
  • Small Gallery Button/Large Gallery Button
  • Small Combo Button/Large Combo Button
  • Small Dropdown Box
  • Small Menu Combo Button/Large Menu Combo Button
  • Small Input Box
  • Panel

Let’s go through them one by one.

Small Button/Large Button


The small button or large button support an action to be triggered when the user clicks on the button. For example displaying an alert window.


How do we do that?

First let’s check the fields value for that button


In the Click field we put customribbons:alert command, Sitecore will trigger this command every time the button is clicked.

The command is registered through a separate config file

The actual command class

Nothing fancy happening in the command class, this is just to give you an idea on how to wire the whole thing.

Small Check Button/Large Check Button


The small check button support a checkbox control for the user to represent toggled/untoggled state.


The small check button fields are basically the same as the small button except that it doesn’t have the option to set an icon.

The command class for this example

Don’t forget to register the command class in the config file.

Small Gallery Button/Large Gallery Button

large-gallery-button small-gallery-button

The gallery button is a special type of button that execute a XAML application when the button is clicked, for example this demo app below


Let’s see how that can be achieved.

Here’s Large Gallery Button field values.


We have a command class which registered as customribbons:gallery

The command class is not doing anything, however we still need this command class in order for it to work.

And then we have Gallery.Demo in the Gallery field, when set Sitecore will seek any XAML application under Sitecore/Sitecore Modules folder that has the matching tag.

The XAML file has a backing class that handles the functionality of the XAML page


Small Combo Button/Large Combo Button

large-combo-button small-combo-button

The combo button support two type of event

  1. When you click on the button itself
  2. When you click on the arrow

Let’s take a look at the field values


Here’s what it will do:

  1. It will trigger the customribbons:alert when the button is clicked
  2. It will run the Gallery.Demo xaml application when the arrow is clicked

Small Dropdown Box


The small drop-down box control will basically take a string separated by a pipeline in the Items field and render it as the drop-down items


Small drop-down box field values


In the example I’ve put a pipeline character in front as the default item in the dropdown control. This control will trigger the customribbons:dropdown command.


Small Menu Combo Button/Large Menu Combo Button


Like the combo button control, the menu combo button control also support two types of event. Clicking on the button and clicking on the arrow.

The Large Menu Combo Button field values


In the Menu field it refers to the menu items created under /sitecore/content/Applications/Content Editor/Menues/Custom Menus


The control will list the items referred when the arrow is clicked

large-menu-combo-button-arrow-clickedThe menu item also support the command class to be entered in the Message field.

Small Input Box


The small input box as it’s name represent has an input text field available. When the cursor is out of focus from the control or when the enter key is pressed it will trigger the command.


The command class



Panel is a way provided for the developer if the out of the box control does not meet their need, they can create their own control then register it as a panel to be used in the ribbon.

An example of this would be the Insert chunk in the Home ribbon

insert-chunk-home-ribbonWhich we can re purpose for something else, for example


In the field values, there’s only one field which is Type where we register our custom Panel


The panel class

The source code can be found in github

And that concludes this little article.