LibrarySites.Banner

Improving the Page Editor Experience Part 1: Uses for Parameters

A typical day-to-day task for a Sitecore content editor involves using the Page Editor to add a new component to a page and set that component's data source. In the example below, a General Widget component has been added to the homepage, and is outputting content from Content Block item called 'Which bike?':

Homepage with four widgets

The Content Block data template has four fields – Heading, Image, Text, and Link:

Content Block data template

In the above example, the ‘Which bike?’ widget is one of 4 – the same sublayout has been reused four times; each has exactly the same styling treatment and mark-up, but varying data sources.

I want to highlight the 'Which bike?' component

The 'Which bike?' component is more important than the others, and I want to highlight it in some way. My designers have come up with a solution, and the resident front-end developer has implemented it – by adding an additional CSS class to the widget to make it red:

Amended design 

As a developer, how do I implement that?


You could add an additional field to the Content Block data template called CSS Class. This could be a Single-Line text field, or a Droplink with CSS class options that content editors choose from.

When a particular Content Block is chosen as a data source, retrieve the contents of the CSS Class field and use the value in the sublayout.


But I want to change the appearance of the ‘Which bike?’ widget per instance

Another content editor has come in and wants to re-use ‘Which bike?’ on another page. In the context of her page, ‘Which bike?’ is not as important and therefore does not require a colour treatment.

However, because I defined a CSS Class field on the data template, changing it to suit a new page will change it everywhere else – the widget's style is tightly bound to its content.


Using parameters to set properties per instance of a component


The solution is to use parameters to determine your per-instance styling of components.

Content and presentation are separate concerns. Technically, the colour of a component has nothing to do with the data it is displaying – I should be able to change the data source of General Widget to another Content Block and retain all styling:

  1. Define a data template called General Widget Parameters and inherit from Standard Parameter Template
  2. Add a new field called Widget Style of type Droplist
  3. Create a CSS Class data template without any fields and set up a global repository of items based on it somewhere in the content tree – the names should match the CSS classes available to you (e.g. 'red')
  4. Set the source to the Widget Style droplist field to this repository of simple items
  5. Navigate to your General Widget component, and set the Parameter Template to the parameter template you just created
  6. Switch to the Page Editor, and open the Page Editor options for an existing widget – not the presence of a droplist field called Widget Style. Choose an item – e.g. 'red':

    Choosing CSS class

  7. Switch to Visual Studio. In the code-behind for the General Widget, extract the parameter by name – code sample below:

    public string Class
    {
        get
        {
            var sublayout = this.Parent as Sublayout;
     
            var parameters = sublayout.Parameters;
     
            var collection = WebUtil.ParseUrlParameters(parameters);
     
            string css = collection["Widget Style"];
     
            return css;
        }
    }
  8. In the .ascx, output the contents of your parameter where required – in this example, as an additional CSS class: 


  9. <div class="chunk widget <%= Class %>">


  10. Switch to the Page Editor. The component with 'red' selected now has that style applied – if you change the data source, the style does not change.

Tip! If your parameter is an item, and you are rendering field content using FieldRenderer.Render(), remember to pass in disable-editing – otherwise your HTML might break in Page Editor mode.

HTML prerequisites


In this example, we used 'red' as a sample class. If all styling related to your widget is defined on a single class – .generalWidget, for example – you do not have the flexibility to mix and match. If you are taking this approach, HTML developers need to split styling into categories, allowing you to mix properties – e.g. 'red roundedCorners' or 'white blackBorder'.

Sitecore prerequisites


If you have not componentized your page into sublayouts (for example), you will not be able to take advantage of parameters – they are set per instance of a component.

Other uses of parameters


In this example, we looked at colour treatments – other ways to take advantage of parameters include:

  • Heading level – ‘Which bike?’ might need an ‘H2’ or ‘H5’ depending on how important it is on a particular page.
  • Component width – ‘Which Bike?’ might need to take up half or a third of the page depending on where it is being used; you can allow the content editor to pick.
  • Hiding an image – On the ‘Terms and Conditions’ page, I might not want to use an image; add a checkbox to hide or show the image.

Parameters or compatible renderings?


Compatible renderings allow you to specify a number of controls that are interchangeable – you might have the following suite of components:

  • General Widget Without Image
  • General Widget With Red Background

… and so on. The advantage of using parameters is that you do not duplicate the same functionality across variations of the same component.

Notes about parameters, languages, and standard values


  • Parameters are shared – this means they are the same across all versions and languages.
  • Like any other data template, a parameter template can have standard values – when you add a component to a page, you can set a default for the Widget Style field you created.
  • In page editor, I think the sequence is:  1. Insert Page.  These are created as children of the context item. 2. Add a component to a placeholder. 3. "Select the associated content", meaning select the data source item.  I select one of the content items that were created in step 1.  But the dialog for step 3 starts at the very top of the Sitecore content tree, and has "Create New Content" grayed out.  So I'm wondering:  a) if there is a way to have the dialog start at the current context item b) how do I enable "Create New Content" and what does it do?  thanks,  Robert

  • Hi Robert -  If you set the Datasource location and Datasource template on the component you are adding, the 'create new content' button will become available.  (for full details, scroll down to 'datasource location' section - www.sitecore.net/.../Improving-the-Page-Editor-Experience-Part-2-Sample-Data-and-HTML.aspx)  You do have to set both. Because you are telling Sitecore where you want your items to come from, and what data template to use, it has enough information to create a new datasource item for the component you are adding without you having to go to the Content Editor.  Out of the box, datasource location only accepts a path - e.g. /sitecore/content/Global/my-folder, but I'm sure you can modify it to accept a Sitecore query (which would allow you to set the datasource location as the currently selected item).

  • Found the answer.  You need to set the Datasource Location field and Datasource Template field on the rendering or sublayout (in my case a view rendering).  The Datasource Template should point to the template that the rendering will use, and that enables the Create New Content button.  The Datasource Location should point to where you want the Set Associated Content tree to begin, like a source field on a Droplink or Droptree.  If you want to have it start with the children of the current item like I did, use manually enter ./ in the Datasource Location field, rather than using link.