Setup & Configuration

ElasticWCM Content Controls display editable content on ASP.NET web pages.

In the current version of the ElasticWCM.Client.dll there are six content controls: StringField, TextField, HtmlField, ImageField, DateTimeField, and ScheduledRedirectField.

• StringField - displays one line of plain text (HTML-encoded by default)
• TextField - displays multiple lines of plain text (HTML-encoded by default)
• HtmlField - displays rich HTML (without HTML-encoding, surrounded by a <div> tag)
• ImageField - displays image (clean <img> tag)
• DateTimeField - displays date, optional time, and time zone
• ScheduledRedirectField - manages scheduled redirect from current page, useful for scheduled publishing or removal of pages.

Properties common for all Content Controls

Below is the description of properties that are common for all ElasticWCM Content Controls.

Properties identifying the field

When you place an ElasticWCM content control on an ASP.NET page the system must have a way to figure out how to retrieve correct content to display it on the page.

The simplest way to identify a content field is to assign a FieldName. In this case the content will be displayed only on this page identified by the page's relative URL path, like "/folder/default.aspx (all Query String parameters will be ignored). If you use the same FieldName on another page (like /about.aspx) it will be completely different field having different content.

In more complicated scenarios, to select proper content value from the cloud-based database ElasticWCM considers five properties of the content control: FieldName, VaryByParams, GlobalScope, VaryByValue, SourcePageUrl. These properties together with the current page URL and Language ID uniquely identify a piece of content in the database.

Below is the diagram explaining the process of uniquely identifying a piece of content.

The only required property is the FieldName, all other are optional.

FieldName

FieldName must be provided for any ElasticWCM content control. FieldName works together with additional control properties like VaryByParams, GlobalScope, VaryByValue, SourcePageUrl to uniquely identify the field within a page. If none those additional properties is provided, the content control will use FieldName and current page's relative path to identify and retrieve content from the cloud-based database. The control will ignore Query String of current page URL.

For example, this field placed on the Default.aspx page

<ewcm:StringField runat="server" FieldName="Page Title" />

will display the same text for Default.aspx and Default.aspx?id=123 URL's, but if you use the same FieldName in the About.aspx page - that will be completely different field displaying different content.

You can use any string here (up to 50 characters long) - use one that would clearly describe the field to a person editing the page. For example, "Left Column Header" or "Marketing Message Picture".

VaryByParams

VaryByParams is another very important property of any ElasticWCM Content Control. It specifies the name of a Query String parameter to consider while identifying the content field. If you need to specify several parameters - separate names with comma.

Let's say we have a content field on the Article.aspx page specifying VaryByParams="topic":

<ewcm:StringField runat="server" FieldName="Page Title" VaryByParams="topic" />

This field will display different content for Article.aspx, Article.aspx?topic=localweather and Article.aspx?topic=worldweather URLs.

The VaryByParams parameter provides the ability to create unlimited number of content pages using a single page template (in this example Article.aspx). It also allows sharing of some content between multiple pages by using different combinations of QueryString parameters for different content fields.

For example, we could use these two fields in a catalog page Product.aspx:

<ewcm:StringField runat="server" FieldName="Category Title" VaryByParams="category" />

<ewcm:StringField runat="server" FieldName="Product Name" VaryByParams="category,product" />

The page will display the same Category Title for URLs Product.aspx?category=sport&product=100 and

Product.aspx?category=sport&product=321 because the category value is the same, but will display different Product Names because the field "Product Name" monitors both parameters - category and product - and the product value is different in these two URLs.

The total length of the Query String containing all specified VaryByParams and theirs values should not be greater than 100 characters.

GlobalScope

The GlobalScope parameter tells the system that content of this control should not depend on the current page URL. For example, on any page the value of this content control will be the same:

<ewcm:StringField runat="server" FieldName="Web Site Title" GlobalScope="Top Header" />

Most frequently the GlobalScope property is used on Master Pages, for example, to display editable site title that should be the same on all pages of the site.

If you navigate to a web page, click Edit Page button and modify the content of this field, the new value will be displayed on all site pages. You can modify it from another page, and again that modification would be a global one.

This is what you usually want from a content field placed on the Master page - you'd like it to stay the same for all site pages. Without GlobalScope specified this field would hold different values for different pages - if you modified it on the Default page the new content would be displayed only on the Default page, others would have the old content.

Together the FieldName and the GlobalScope parameters uniquely identify the field - a field with FieldName="Logo Image" GlobalScope="Top Header" and a field with FieldName="Logo Image" GlobalScope="Footer" are different fields.

SourcePageUrl

If the SourcePageUrl property is defined, it replaces current page URL - the field will display data from another page. If GlobalScope is defined then only query string parameters from that URL will be considered.

Here is an example of a content control defining the SourcePageUrl property.

<ewcm:StringField runat="server" FieldName="Page Title" VaryByParams="topic" SourcePageUrl="~/Article.aspx?topic=news" />

The SourcePageUrl parameter tells the control that it should display content provided for a specific URL, in this case ~/Article.aspx?topic=news. This means that no matter what URL current page has, the content will be taken from the ~/Article.aspx?topic=news. This enables consistent reference to target page. For example, if you navigate to the ~/Article.aspx?topic=news page and edit content in its "Page Title" field, the text in corresponding navigation link will be changed accordingly.

This property is useful for navigation menus which should display actual page title in the link's text. Here is an example of such menu:

<ul>
  <li><a href="Article.aspx">
    <ewcm:StringField runat="server" FieldName="Page Title" VaryByParams="topic" SourcePageUrl="~/Article.aspx" EditableHere="false">Introduction</ewcm:StringField>
    </a></li>
  <li><a href="Article.aspx?topic=news">
    <ewcm:StringField runat="server" FieldName="Page Title" VaryByParams="topic" SourcePageUrl="~/Article.aspx?topic=news" EditableHere="false">News</ewcm:StringField>
    </a></li>
  <li><a href="Article.aspx?topic=events">
    <ewcm:StringField runat="server" FieldName="Page Title" VaryByParams="topic" SourcePageUrl="~/Article.aspx?topic=events" EditableHere="false">Events</ewcm:StringField>
    </a></li>
</ul>

In this example we use EditableHere="false" because we don't want all these fields to appear in Page Editor for every page where the menu is placed. We want to edit a page's Page Title only on that particular page - we'll have the "Page Title" field in the page's header area:

<ewcm:StringField runat="server" FieldName="Page Title" VaryByParams="topic" />

VaryByValue and VaryByValueTitle

VaryByValue property provides an additional value helping uniquely identify field content. It requires VaryByValueTitle property to be provided.

To better understand purpose of this property, compare it with the VaryByParams property. When VaryByParams is provided the control grabs corresponding value from Query String - but the VaryByValue provides such value directly, without referring to the Query String.

This is useful when you want to programmatically change the selection of content.

VaryByValueTitle property provides a name for the VaryByValue parameter in Page Editor. If VaryByValueTitle is not present then VaryByValue will be ignored.

PermissionContext

PermissionContext property provides a non-default set of permissions for the field. Before you can use this property you need to define available PermissionContexts in the web.config file. (See Permissions Configuration in the documentation.)

Usually, you use PermissionContext when you want to define different set of permissions for different company departments.

Let's say in web.config you defined a Permission Context with the name "Marketing" for which you specified that users having Role "MarketingContentEditor" will have permissions ViewDrafts and EditPageFields.

Then in your FBA Membership database you created the role MarketingContentEditor and assigned some people from Marketing department to that role.

The PermissionContext property gives you the ability to designate particular content fields to be Marketing department's responsibility:

<ewcm:StringField runat="server" FieldName="Marketing Message" PermissionContext="Marketing" />

This creates an exception from the default permission schema - only marketing people will have permissions to edit this filed (and, of course, people with SuperAdmin permissions).

Hidden

The Hidden property indicates whether field content will be displayed on the page. Default is "false". Set it to "true" when you want to edit field on this page but not display it.

EditableHere

The EditableHere property indicates whether this instance of the field can be edited in Page Editor when editing this page. Default is "true". Set it to "false" when you want to display the content but want to edit it on a different page, not this one. This is useful when building navigation menus.

EditorSortOrder

The EditorSortOrder is a float number defining the sort order when displaying fields in Page Editor. Default value is 0. Fields having the same value of the EditorSortOrder will be displayed in the order they first appeared on the page.