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

  <sc:FieldRenderer ID="frArticleTitle" runat="server" FieldName="Article Title" />
  

  var articleItem = Sitecore.Context.Database.GetItem([ID|Path|String ID|String Guid]);
  frArticleTitle.Item = articleItem;
  

Example 2

  <asp:Repeater ID="rptrArticles" runat="server">
      <ItemTemplate>
          <sc:FieldRenderer runat="server" FieldName="Article Title" Item="<%# Container.DataItem %>" />
      </ItemTemplate>
  </asp:repeater>
  

  var articleParent = Sitecore.Context.Database.GetItem([ID|Path|String ID|String Guid]);
  var articleItems = articleParent.Children;

  rptrArticles.DataSource = articleItems;
  rptrArticles.DataBind();
  

Example 3

  <asp:Repeater ID="rptrArticles" runat="server">
      <ItemTemplate>
          <sc:FieldRenderer ID="frArticleTitle" runat="server" FieldName="Article Title" />
      </ItemTemplate>
  </asp:repeater>
  

  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" />