tag:blogger.com,1999:blog-29518377290255511232024-03-13T08:30:23.007-07:00Pelle LagermannUnknownnoreply@blogger.comBlogger2125tag:blogger.com,1999:blog-2951837729025551123.post-63575008664360649882014-11-27T00:28:00.002-08:002014-11-27T00:51:15.138-08:00The Sitecore Source Property Explained - Part 2: Treelist Parameters<h2>
</h2>
The treelist is a widely used multi-select Sitecore template field type. It
enables the user to select any number of items from the Sitecore content
tree. If you don't define a root item for the treelist, it will simply
use the Sitecore-item as the root. The user can then navigate the
content tree and select any items they desire. In some cases this might
be fine. But more often than not, we can improve the user experience by
simply setting a more suited root item in the treelists source property:<br />
<span class="query-sample">/Sitecore/Content/Home</span><br />
<i>This would set the home-item as the root of the treelist, so that the content author would only be able to navigate to and select items that are </i><i>descendants of the home-item. </i><br />
<br />
We
can do a lot better than just setting a root item though. By defining a
<b>parameterized datasource</b>, we can control what items are visible in
the treelist, what items the user can select and more.<br />
<br />
<a name='more'></a><br /><br />
<h2>
Building a treelist datasource </h2>
A simple treelist datasource, setting the root item of the treelist could look like this:<br />
<span class="query-sample">DataSource=/Sitecore/Content/Home</span><br />
Notice that we have simply prefixed the normal root item path with "DataSource=". If we simply need to set a root item, we can do it either way, as the result for the content authors would be the same. However, by converting the normal path to a datasource, we can now append a number of parameters to the source property.<br />
Say we have a news section on our website, and all the news stories are organized in a folder structure in Sitecore. On our front page, we have a dedicated area for displaying important news stories. The news stories displayed on the front page are selected in a treelist.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg984mjRwdB5ec28dMg2r4gvpsSoJ0394H_FsNn8JGqKfX9xyQBIzK20_LobHSnTC6agrL-X2Y3KPHUbUyYhOnKaweSAtZuVzLI7FvHVnpLVPOp4pXBiIX0nRiVVIIR9STlqc0bgiIpQ5mB/s1600/News+structure.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg984mjRwdB5ec28dMg2r4gvpsSoJ0394H_FsNn8JGqKfX9xyQBIzK20_LobHSnTC6agrL-X2Y3KPHUbUyYhOnKaweSAtZuVzLI7FvHVnpLVPOp4pXBiIX0nRiVVIIR9STlqc0bgiIpQ5mB/s1600/News+structure.png" height="212" width="640" /></a></div>
<br />
<br />
All the folders are based on the <i>NewsFolder</i>-template, and the news items are based on the <i>NewsStory</i>-template. Now, if we simply set the root item to be the top folder in the news structure. One of our content authors could by mistake select one of the news folders in the treelist. This could cause some confusion for the content authors, as they could then have a treelist with e.g. 5 items selected, but only 4 news stories shown on the front page. Furthermore, if our code isn't written to be able to handle the selection of a news folder item, the front page might break. <br />
Luckily we can avoid this situation all together, by simply defining what templates can be selected in the treelist. To do this, we simply need to append a parameter to the datasource:<br />
<span class="query-sample">DataSource=/Sitecore/Content/Home/News&IncludeTemplatesForSelection=NewsStory</span><br />
<i>By setting the IncludeTemplatesForSelection-parameter, we have limited our content authors to only be able to select items based on the NewsStory-template.</i><br />
<br />
<h3>
The structure of a treelist datasource</h3>
The treelist datasource consists of a path and a number of parameters. The parameters are key=value pairs separated by ampersand "&". The value part of the key=value pairs, can both be a single value and a comma-separated list.<br />
If the news structure from before also has a number of other items, besides the ones based on the <i>NewsFolder</i>-template and the <i>NewsStory</i>-template, and these are irrelevant in our treelist.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjVrF7ISN8xQC_AmUPowXri-81UX8fYtxFv_gR_Gn9cPP4fHOv9Tj9Vg5XEzOUv4uHTfi9cUGVP7RPSFk1g2EUpMChr-sBDHmAwB135anJC1aI50T8afhHNQsSXDApcop3uyzuq-fpi3Voo/s1600/News_structure_-_irrelevant_items.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjVrF7ISN8xQC_AmUPowXri-81UX8fYtxFv_gR_Gn9cPP4fHOv9Tj9Vg5XEzOUv4uHTfi9cUGVP7RPSFk1g2EUpMChr-sBDHmAwB135anJC1aI50T8afhHNQsSXDApcop3uyzuq-fpi3Voo/s1600/News_structure_-_irrelevant_items.png" height="186" width="640" /></a></div>
<br />
We can then simply filter these out by either using a blacklist (ExcludeTemplatesForDisplay) or a whitelist (IncludeTemplatesForDisplay) for determining which templates should be visible in our treelist. <br />
<span class="query-sample">DataSource=/Sitecore/Content/Home/News&IncludeTemplatesForSelection=NewsStory&IncludeTemplatesForDisplay=NewsFolder,NewsStory</span><br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg984mjRwdB5ec28dMg2r4gvpsSoJ0394H_FsNn8JGqKfX9xyQBIzK20_LobHSnTC6agrL-X2Y3KPHUbUyYhOnKaweSAtZuVzLI7FvHVnpLVPOp4pXBiIX0nRiVVIIR9STlqc0bgiIpQ5mB/s1600/News+structure.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg984mjRwdB5ec28dMg2r4gvpsSoJ0394H_FsNn8JGqKfX9xyQBIzK20_LobHSnTC6agrL-X2Y3KPHUbUyYhOnKaweSAtZuVzLI7FvHVnpLVPOp4pXBiIX0nRiVVIIR9STlqc0bgiIpQ5mB/s1600/News+structure.png" height="212" width="640" /></a></div>
<br />
<h2>
Treelist parameters</h2>
<h3>
DataSource</h3>
Path to the root item of the treelist.<br />
The root of the subtree that the content author will be able to navigate in the treelist.<br />
<br />
<h3>
DatabaseName</h3>
The name of the database containing the path defined in DataSource.<br />
<br />
<h3>
IncludeTemplatesForSelection</h3>
A comma-separated list of template names or ID's. The content author will only be able to select items based on the templates defined in this parameter. <br />
<br />
<br />
<h3>
ExcludeTemplatesForSelection</h3>
A comma-separated list of template names or ID's. The content author will be able to select items based on all templates <i>except</i> the templates defined in this parameter. <br />
<br />
<h3>
IncludeTemplatesForDisplay</h3>
A comma-separated list of template names or ID's. Only items based on templates defined in this parameter will be shown in the treelist.<br />
<br />
<h3>
ExcludeTemplatesForDisplay</h3>
A comma-separated list of template names or ID's. All items based on the templates from this parameter, will be hidden from the treelist.<br />
<br />
<h3>
IncludeItemsForDisplay</h3>
A comma-separated list of item names and ID's. Only items from this parameter will be shown in the treelist.<br />
<br />
<h3>
ExcludeItemsForDisplay</h3>
A comma-separated list of item names and ID's. Items from this parameter will be hidden in the treelist.<br />
<br />
<h3>
AllowMultipleSelection</h3>
Determines if the content author can select the same item more than once. <br />
Notice, this is <b>not</b> a boolean value. To enable multiple selection, this parameter need to be set to "yes".<br />
Example:
<span class="query-sample">DataSource=/Sitecore/Content/Home/News&IncludeTemplatesForSelection=NewsStory&AllowMultipleSelection=yes</span>Unknownnoreply@blogger.comtag:blogger.com,1999:blog-2951837729025551123.post-87120302777127698122014-11-27T00:28:00.000-08:002014-11-27T00:49:57.886-08:00The Sitecore Source Property Explained - Part 1: Root ItemAll Sitecore template field types have a source property. While this property isn't always used, it is a really powerful tool for filtering the data shown in various field types and improving the general user experience.<br />
<br />
<a name='more'></a><br /><br />
Sitecore supports three techniques for utilizing the source property:<br />
<ul>
<li>Root Item</li>
<li>Treelist Parameters</li>
<li>Sitecore Query </li>
</ul>
Which of these techniques you should use, depends on the situation and the field type you are working with, as not all field types support the same techniques. <br />
In this blog post, setting a root item will be covered. The treelist parameters and Sitecore query will be covered in later blog posts.<br />
<h2>
Setting a root item</h2>
Defining a root item is supported for the following field types:<br />
<b>Simple Types</b>: File & Image<br />
<b>List Types</b>: Checklist, Droplist, Grouped Droplink, Grouped Droplist, Multilist, Name Lookup Value List, Treelist & TreelistEx<br />
<b>Link Types</b>: Droplink & Droptree<br />
<br />
Some of these field types require a root item to work. Others will by default let the user access the entire content tree or media library... or at least the parts, that the user is allowed to access. This might be fine for some cases, but setting a root item can be of great benefit to both the developer and the end user.<br />
By setting a root item you can limit the users access to a certain part of the content tree. In doing so, you can not only potentially save the user a lot of clicks, you can also help prevent the user from selecting content of the wrong type. Eg. if you have a treelist for selecting featured blog posts on your front page and all your blog posts are located under the same parent node (<i>Blogs)</i> in the content tree. Setting the root item of the treelist to the <i>Blogs-</i>element, would prevent your users from having to navigate to the <i>Blogs-</i>element every time they need to select a new featured blog post.<br />
<br />
<h3>
Root item as path or ID</h3>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi2JgwDp9EiktTe6ClNa6rWZZKVoZC-L7iki4ZYZLCbf3RYFvZnLhH7_Rj3IrXOnXh5OsNb3Mvdx1pA5nvQkgTD5yf4pusIx1KNvTunpeqsUa0NSRinHMFO8m6ekOyVo0N5DIZCNPtgj6EK/s1600/Item_path_and_ID.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi2JgwDp9EiktTe6ClNa6rWZZKVoZC-L7iki4ZYZLCbf3RYFvZnLhH7_Rj3IrXOnXh5OsNb3Mvdx1pA5nvQkgTD5yf4pusIx1KNvTunpeqsUa0NSRinHMFO8m6ekOyVo0N5DIZCNPtgj6EK/s1600/Item_path_and_ID.png" height="156" width="640" /></a></div>
<br />
You can set the root item either by entering the <i>item path</i> or the <i>item ID</i> as the source property of the template field. You can get both the path and the ID from the Quick Info section in the Content Editor.<br />
<br />
If the Quick Info section isn't visible in your Content Editor, you can enable it by following these simple steps:<br />
<ol>
<li>Click the Sitecore logo in the top left corner of the Content Editor</li>
<li>Chose <i>Application Options</i> from the drop down menu</li>
<li>Check the Quick Info Section-check box</li>
<li>Click Ok</li>
</ol>
To set the root item as the source property for a template field, simply copy either the path:<br />
<span class="query-sample">/Sitecore/Content/Home/Blogs</span><br />
or the ID:<br />
<span class="query-sample">{9FE94452-1CB3-4E45-B422-71D4F8CA9025}</span><br />
into the source property.<br />
There are pros and cons of doing this either way. The path is sensitive to the renaming and moving of content, as both of these actions would change the path. Using the ID would solve these issues, but if an item is deleted and replaced with a new item with the same name and location, the ID would no longer match, whereas the path would. <br />
<br />
<h2>
The effects of defining a root item for different Sitecore template field types</h2>
<br />
For the end user, the effect of setting a root item on a field, depends on the template field type.<br />
<br />
For treelist field types, such as Droptree, File, Image, Treelist, and TreelistEx, the user will be able to select a descendant item of the root item.<br />
<br />
For single-level list field types, such as Checklist, Droplink, Droplist, or Multilist, the user will be able to select only items that are direct children of the root item.<br />
<br />
For grouped list field types, such as Grouped Droplink and Grouped Droplist, the user will be able to select items that are grandchildren of the root item. The direct children will function as the groups in the list. Unknownnoreply@blogger.comCopenhagen, Denmark55.6760968 12.56833710000000855.532822800000005 12.245613600000008 55.8193708 12.891060600000008