In today's Sitecore Tip of the Day we will go over the Item
property of Sitecore web controls, including what it is, how to use it, and how it works by default. This post is intended for more novice Sitecore developers who have not been working with the system for a long period of time.
What is the Item
property, and what is it for?
The Item
property (often incorrectly referred to as the Item
attribute) of Sitecore web controls (like <sc:FieldRenderer>
, <sc:Text>
, <sc:Image>
, etc.) is used to define the Item from which to grab the field and, subsequently, said field's value. The Sitecore web controls are used to render a the value of the field with the name specified in either the Field
or FieldName
property (dependent on which control you are using; some use Field
while others use FieldName
). The Item
property is used to tell the control on which Sitecore item it should look for that field. Note that the Item
property is not a string, but rather an Sitecore.Data.Items.Item
.
How do I use it?
Have a look at the examples, below, all of which are valid:
Example 1
On the front-end:
<sc:FieldRenderer ID="frArticleTitle" runat="server" FieldName="Article Title" />
And then on the back-end:
var articleItem = Sitecore.Context.Database.GetItem([ID|Path|String ID|String Guid]);
frArticleTitle.Item = articleItem;
Example 2
On the front-end:
<asp:Repeater ID="rptrArticles" runat="server">
<ItemTemplate>
<sc:FieldRenderer runat="server" FieldName="Article Title" Item="<%# Container.DataItem %>" />
</ItemTemplate>
</asp:repeater>
And then on the back-end:
var articleParent = Sitecore.Context.Database.GetItem([ID|Path|String ID|String Guid]);
var articleItems = articleParent.Children;
rptrArticles.DataSource = articleItems;
rptrArticles.DataBind();
Example 3
On the front-end:
<asp:Repeater ID="rptrArticles" runat="server">
<ItemTemplate>
<sc:FieldRenderer ID="frArticleTitle" runat="server" FieldName="Article Title" />
</ItemTemplate>
</asp:repeater>
And then on the back-end:
var articleParent = Sitecore.Context.Database.GetItem([ID|Path|String ID|String Guid]);
var articleItems = articleParent.Children;
rptrArticles.DataSource = articleItems;
rptrArticles.ItemDataBound += rptrArticles_ItemDataBound;
rptrArticles.DataBind();
...
protected void rptrArticles_ItemDataBound(object sender, EventArgs e)
{
if (e.Item.ItemType == ListItemType.Item || e.Item.ItemType == ListItemType.AlternatingItem)
{
var articleItem = e.Item.DataItem as Item;
var frArticleItem = (FieldRenderer)e.Item.FindControl("frArticleItem");
frArticleItem.Item = articleItem;
}
}
What happens if I do not set the Item
property?
The default value of the Item
property is the Context Item, i.e. Sitecore.Context.Item
. In other words, if you are on a page and would like to use the item for that page as the Item
you do not need to explicitly set the property. As such, the following is redundant:
<sc:FieldRenderer runat="server" FieldName="Article Title" Item="<%# Sitecore.Context.Item %>" />
Instead, you can just use the following, which is equivalent:
<sc:FieldRenderer runat="server" FieldName="Article Title" />
When would I want to use the Item
property?
Whenever you want to render some data from an item other than the Context Item onto a page using a Sitecore web control, you should use the Item
property. Looking back at the repeater examples above, you may want to use something like this on a blog or news landing page, where you want to list out the titles and short summaries of all of the articles contained within said blog or news landing page. The sky is the limit, and this is a great tool for you to know and use when working with Sitecore.
Are there any alternatives to the Item
property?
If necessary, the DataSource
property is an alternative to using the Item
property to set the item on which the control should look for the field. The DataSource
property is a string path to the item that you would like the control to use, but can be overridden by setting the Item
property, as the Item
property takes precedence over the DataSource
property. The following is the syntax for the DataSource
property:
<sc:FieldRenderer ID="frArticleTitle" runat="server" FieldName="Article Title" DataSource="/sitecore/content/home/news/article 1" />
However, image that some property, Article2Item
, was set on the back-end:
protected Item Article2Item { get; set; }
...
Article2Item = Sitecore.Context.Database.GetItem("/sitecore/content/home/news/article 2");
Now, if we were to write the following, "Article 2" would be used instead of "Article 1":
<sc:FieldRenderer ID="frArticleTitle" runat="server" FieldName="Article Title" Item="<%# Article2Item %>" DataSource="/sitecore/content/home/news/article 1" />