LibrarySites.Banner

Improving the Page Editor Experience Part 2: Sample Data and HTML

This is part 2 of a series on improving the Page Editor experience, mostly in the way you configure it. Part 1 can be found here.

As an author, I have added a component of type General Widget to a page using the Page Editor. The component accepts a datasource, but because I have not specified one yet, this is what I see:

Empty component without any data

I am not prompted in any way to specify a datasource - if I forget and publish the page regardless, visitors will see a blank white box on the homepage.

There are two things you can do to ensure that this does not happen - configure the Page Editor to force a selection, and/or provide sample data that appears when a component is empty.

Configuring datasource template and datasource location

The following set of steps takes you through setting up datasource template and datasource location restrictions.

  1. Select the component, click More in the floating toolbar, and select Edit Page Editor Options:

    Setting page editor options

  2. In the Editor Options field section, specify a Datasource Location (the root folder for datasource selection) and a Datasource Template (the types of items that can be selected):

    Datasource location and datasource template fields

  3. Note that any changes you make here affect all General Widget components, not just this particular instance.
  4. Click OK, and add a new General Widget component to the homepage. I am now prompted to choose a datasource - notice that my selection is restricted to the reusable content folder, and items I am not allowed to select (e.g. the reusable content folder itself) are greyed out; from here, I select the datasource I want to use and click OK:

    Associated content selection

  5. Alternatively, I am given the option to Create New Content with the type and location specified in step 2 (this creates a new item under reusable content):

    Restricting datasource location and template

  6. When I click OK, I see my component with its datasource set to my new new-bikes-promotion item - at this point, I can enter this item's the heading, text, image, and link and save; I can reuse this item as a datasource elsewhere on the site:

    Fields with no content

Authors are now prevented from adding a component of this type without specifying a datasource.

Using sample data

Even though I am prompted to add a datasource when adding a new component to a page, I could still clear the datasource (whether by accident or because I'm intending on changing the datasource).

This is where I might want to provide sample data - either to prompt the author to pick a datasource or generic text that, if the page is published, does not spoil the visitor's experience as much as an empty component.

One way to provide sample data is to hardcode content into an ASP.NET panel and show or hide that panel depending on whether or not the datasource has been set - see code sample below:

if (datasource == null)
{
    samplePanel.Visible = true;
}

<asp:Panel runat="server" ID="SamplePanel">
    <h2>Please choose a datasource!</h2>
</asp:Panel>

However, this means that a) the sample content is not translatable and b) if any changes are required, a developer would have to be summoned to do the work.

A better way, therefore, is to provide a sample data repository somewhere in your Sitecore tree:

Editing sample content

In your component's code-behind, if no datasource has been specified, force your controls to use the item from your samples repository (in the example, ItemReferences.SampleWidget is a centrally stored Item object):

if (source == null)
{
        source = ItemReferences.SampleWidget;
}
            
        WidgetHeading.Item = source;
        WidgetText.Item = source;
        WidgetLink.Item = source;
        WidgetImage.Item = source;
}

Edit (29/07/2013) - When setting the source to sample data (ItemReferences.SampleWidget in the above example), you may want to set each Sitecore control's DisableWebEditing property to true - this forces authors to pick a data source rather than simply editing the sample and assuming that it will automatically create a new data source.

There is a Datasource field on the sublayout definition item - can't I use that to specify my 'sample'?

If you do that, the component will always think it has a datasource - this is fine if you haven't set up any restrictions (location and type), but if you have, you will never be prompted to select a datasource when adding a new component because it assumes you want to use the default - therefore, it's better to do the fallback in code.

Now, when a component does not have a datasource set, your sample data - which is translatable and editable by authors - will display:

Using sample content

What if my component does not accept a datasource?

If your component does not accept a data source - e.g. a ‘Two Column Content' component that draws its content from the context item - Sitecore will tell you that the fields have no text:

Content coming from context item in Two Column Content component

If you want default or sample data in this instance, use that data template's Standard Values to specify default values - e.g. instead of [NO TEXT IN FIELD] you would see ‘Your page heading here - make sure it doesn't go onto two lines'.

Why can't I check for the absence of data (e.g. null datasource or empty fields) and hide the component if null or empty?

Surely the easiest way to make sure that a visitor never sees a blank component is to check whether the datasource has been set, and if not, hide the component:

if (source != null)
{
       /* .... */
}
else
{
      base.Visible = false;
}

That's fine for visitors, but if I then try to edit the component in the Page Editor, I can no longer see the component, and therefore can't select to edit - components must display at least some HTML in order to be selectable.

Even if they are not outputting data, components must output some HTML in order to be selectable in the Page Editor

Take the Banner component as an example - when I add a new banner component, because it relies on an image data source that has not yet been specified to give it shape, it's very hard to select it:

The banner has no height in the Page Editor

To solve this, you can:

  • Force data source selection when the component is added
  • Provide sample data - e.g. some text that says ‘please provide an image' or a sample image item
  • Give the surrounding HTML some shape - a General Widget component will look like this when empty because the CSS gives it a fixed height, background colour, and border:

    Two general widget components that are not displaying content

In Summary

  • To force data source selection, use component's Page Editor options to set datasource template and datasource location
  • If a datasource has not been selected for a component, display sample content that prompts an author to choose a datasource
  • In order to be selectable in Page Editor, a component must output something - either sample content or HTML that gives it shape, like a fixed height and a background colour. Do not set Visible to false; it may help visitors to the site, but the Page Editor experience will be affected

In part 3, we will refine this approach by detecting whether or not the site is being viewed using the Page Editor