Category Archives: Content Editor

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 require to create a custom rule condition that fits to the client business requirement.

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

create-custom-personalization-rule-create-tag2. Register a new rule element

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

create-custom-personalization-rule-create-element-folder3. Create a new personalization condition rule

create-custom-personalization-rule-create-personalization-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

create-custom-personalization-rule-assign-element-tag-definition-to-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

4. 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

create-custom-personalization-rule-assign-tag

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

create-custom-personalization-rule-verifying-the-custom-rule-appears

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 open more possibilities for the marketers of what they can do using the platform and lessen time to market.

 

custom-ribbon-endresult

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.

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:

custom-ribbon-endresult

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.

new-custom-chunk-small

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

large-buttonsmall-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.

alert-command

How do we do that?

First let’s check the fields value for that button

small-button-field-values

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

small-check-button

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

small-check-button-ticked

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

large-gallery-button-clicked

Let’s see how that can be achieved.

Here’s Large Gallery Button field values.

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

small-combo-button-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

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-dropdown-box-clicked

Small drop-down box field values

small-dropdown-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

large-menu-combo-buttonsmall-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

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

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

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.

small-input-box-triggered

The command class

 

Panel

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

panel

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

panel-field-values

The panel class

The source code can be found in github

And that concludes this little article.

Filter the media items in the media library dialog using facet and tags

If you have a lot of media items in your Sitecore instance (thousands, ten of thousands), your content author would have difficulty in finding the media items that they want, thus making them frustrated trying do a simple task.

As a good developer you are, you try to help the content author by making their life easier. You start to think about using tags, by using tags the content author could filter the media items to a specific tags and refine their search from there.

So you sat down and make some notes of what you had in your mind

  • thousands of media items in the media library and the content author is having difficulties in filtering them
  • how about we apply tag(s) to the media item itself so that we can filter the media items based on those tags
  • from the content author perspective they would see a new section in the media library dialog to filter media items based on those tags
  • if by default when the media library opens it’s going to say 30,000 items, when the content author click on one of the tags it’s going to narrow down the result to 500 items and then the content author can further narrow it down by searching the file name

So you start of by buildling a POC, you downloaded https://marketplace.sitecore.net/Modules/Sitecore_Instance_Manager.aspx?sc_lang=en to help you quickly install/uninstall sitecore instances.

 

sim-install-new-instance

After the new Sitecore instance has been created, you start checking what the current media library dialog window looks like

medialibrary-dialog-original

You noticed that there’s three filter already built out-of-the-box which is Dimensions, Media type and Date uploaded. You want to create a new column in there called Tags, and you want to know how it work so you start by finding out how the Dimensions column works.

— you did your research and now ready to build your own custom filter based on tags

You’ve defined the following steps required to build the functionality

  1. Create a new class (MediaItemTagsIndexField) that extends AbstractComputedIndexField to extract the value of the assigned tags of each media items
  2. Create a new field and call it mediaitemtags in the index config file so that it would store the value returned by the MediaItemTagsIndexField
  3. Create a new Media Item Tags folder and create new tags item underneath it
  4. Update the image template in the master db both versioned and unversioned, add new field called Tags with Treelist as the media type and point the datasource to the Media Item Tags folder
  5. For POC purposes modify the default /sitecore/content/home item and add a new field with type image in it’s template definition
  6. Create a new class which extends the IFacetProvider which responsible for querying to the search provider and filter the results for you
  7. in the core db under the facets folder, create a new facet item called Tags and set the value of the fieldTypeName to the class that extends the IFacetProvider
  8. Test the functionality

 

MediaItemTagsIndexField.cs

 

zzz.RR.lucene.index.config

This is a patch file used to update the sitecore_marketing_asset_index_master index, we’re adding a new mediaitemtags field to the document

In the config file we’re targeting for the marketing_asset_index_master index however if some reason you did not use this file you could target the sitecore_master_index instead as Sitecore will fallback to use that index instead if marketing_asset_index_master is not available; or define it in the Sitecore.ContentSearch.Lucene.DefaultIndexConfiguration.config file instead to apply it to all index files that refers to the default index configuration.

Create media item tags folder and tags item beneath it

content-tree

Update the image template to include the custom field to assign tags

add-tags-field-in-the-image-template

Do this for for this two Image templates and set the datasource to the media item tags folder

  • /sitecore/templates/System/Media/Unversioned/Image
  • /sitecore/templates/System/Media/Versioned/Image

Add a new field for the home item for the content author to be able to select an image

image-field-in-home

Now the content author can select an image for the home item, however we haven’t provide them with a way to filter the search results in the media library dialog yet. To do this first we need to create a new class that extends IFacetProvider that’s responsible to apply filtering on the search result.

MediaItemsTagFacetProvider.cs

Next we need to add a new column in the media library dialog UI so that the content author can use that to filter the media library search result. To do this switch to the core db and create a new item with facet template under /sitecore/client/Applications/Dialogs/SelectMediaDialog/PageSettings/Facets

tags-facet-item

Now switch back to the master db and click on the home item and click on the browse link

medialibrary-dialog-result

And now the content author has a new way to filter those media items based on the assigned tags!.

Here’s the files used in this post:

Hope this helps.

 

Sitecore – JqueryModalDialogs error when opening popup modal

I got an issue when trying to open a modal popup when logged in to Sitecore

Error when trying to show popup modal dialog
Error when trying to show popup modal dialog

The site has just been setup in IIS, the server is running Windows Server 2008 R2 and it’s using Sitecore 7.2. The strange thing is that there’s another site that’s running under the same Sitecore version and the issue does not happen over there.

I got a clue after opening the ApplicationHost.config file on system32inetsrvconfig and it turns out that on the other site the UrlScan 3.1 was removed from the ISAPI Filters. After i do that the new site runs smoothly as well.

Sitecore Content Tree Structure

I’m sure there are a lot of variation implementing content tree structure out there, here I’m sharing the content tree structure that i have grown liking to.

The idea is to keep things simple and organized for the content editor so they can work their way around the site and feels natural about how the content is structured.

 

image

We start simple, a website node has two child node, a home page node and a libraries node.

A home page node serve as the landing page when the site URL is accessed,  a libraries serve as a place to put the data sources of components that’s being used through out the site.

imageimage

And there’s pretty much how content tree is structured, as a convention i usually use lowercase and no whitespace for the pages node item name because that translate directly into a URL, so you want a friendly URL to be generated. You can enforce this by using a custom pipeline that change the item name after creation and update but convention is good enough for me.

For the pages under supplementary  pages, these are the pages that do not belong to the site’s pages hierarchy/sitemap and usually i give them alias so we can achieve URL such as /404 instead of /supplementary-pages/404. It’s just a matter of taste but think about it.

Hey, what about multisite ?

image

What about it ?, we replicate the same structure for the other sites and if you notice we have a global node over there. The global node serve as a place to put shared content across the sites, maybe the sites shared the same banner data source or carousel put it in the libraries of the global node. And that also goes for the shared pages, you can put it in the supplementary-pages of the global node.

The same structure can be found on other places as well

imageimageimage

 

also keep in mind these following things:

  • if you have a need of referencing items avoid referencing by item path and use item id instead because item path can change, for example when the content editor move the item around or rename them.
  • remember that it’s a bad practice to have hundreds of child nodes under a single node, use categorization to manage them – see news page above.
  • if there’s a need to store a huge amount of data that results in hundreds of child nodes don’t try to store it Sitecore as is, give it a thought and see if storing in a custom table suit your requirement better or take a look at the Sitecore Item Bucket.
  • use branch template to specify a content structure.
  • use insert options to specify child node type that can be inserted under a node.
  • use icon to give visual information to your content editor, this way they can easily distinguish which is which, but be wise in the implementation don’t just give any random icon.