The Property web control is the foundational control used to render CRM entity properties in your ASP.NET applications. At it's core, it is used to render a named property of a CRM entity mapping class. It has a number of other features and options, however, and we'll explore those in this article.

Adding the Property Control to a Page Template

The most basic use of the Property control is to render a property of the CRM entity object to which it is data-bound. This CRM entity object can be either an instance of a class that inherits from Microsoft.Xrm.Sdk.Entity,or an instance of Microsoft.Xrm.Portal.Web.CrmSiteMapNode.  It is possible to set this entity object on the control directly, using the DataItem property:

<!-- This will Eval "name" against the current site map CRM entity -->
<adx:Property PropertyName="name" DataItem='<%$ CrmSiteMap: Current %>' runat="server" />

The Property control can also be bound to a conventional data source control, such as a LinqDataSource, or, as in the next example, Adxstudio.Xrm.Web.UI.WebControls.CrmEntityDataSource.

<!-- Declare our data source, the current site map context entity (e.g., a web page) -->
<crm:CrmEntityDataSource ID="CurrentEntity" DataItem="<%$ CrmSiteMap: Current %>" runat="server" />
<!-- Render the Title property, falling back to the Name property if Title is null -->
<h1>
  <adx:Property DataSourceID="CurrentEntity" PropertyName="adx_title,adx_name" runat="server" />
</h1>
<!-- Render the Copy property of the entity, with a custom CSS class -->
<adx:Property DataSourceID="CurrentEntity" PropertyName="adx_copy" CssClass="page-copy" runat="server" />

The above example demonstrates another feature of the Property control: property fallback. The PropertyName property can be assigned a comma-delimited list of property names. Each will be evaluated against the late bound entity object, in order, until a non-null value results. This first non-null value will be rendered.

Client-side Inline Editing Support

In addition to rendering an actual property value, in its default state, the Property control also renders DOM metadata to support front-side editing of the target property. In this mode, the property value will be contained in <span> elements having system-defined classes (you can also define your own CssClass value, which will be added to the outermost <span>). If the current authenticated user also has Change access permission to the target entity, a service reference URI will also be embedded in the DOM output (it will be invisible). For example:

<span class="xrm-attribute xrm-editable-text">
  <span class="xrm-attribute-value">This is the text value.</span>
  <!-- This is an invisible service reference, to enable client-side editing. It is rendered for users with permission to update this entity. -->
  <a class="xrm-attribute-ref" href="/Services/Cms.svc/ContentSnippets(guid'3616c9a7-5404-de11-bdf3-0003ff48c0db')/Value" title="My Snippet" ></a>
</span>

It is possible to disable this inline editing support if desired (it is enabled by default) by setting the Editable property on the control to false. This this value set, the system classes and service references show above will not be rendered.

There are also a number of configurations of the Property control that will implicitly disable this client-side editing support, due to incompatibility with the DOM structure shown above. These will be described in the following sections.

It is also possible to configure the type of client-side editing interface that the framework will provide, using the EditType property. The supported values for this property are:

  • text – The property value will be editable with a simple text input field. (This is the default EditType.)
  • html – The property value will be editable with a rich HTML editing interface, supporting complex formatting, links, inline images, etc.

(Other property edit interface types (dates/times, etc.) may be added in the future – please feel free to provide suggestions as to what would be most useful in our forums.)

Properties

The Property control has several properties that can be specified to modify the behavior.

NameDescription
PropertyName The attribute name to retrieve a value from. This can be a comma-delimited set of attribute names of which the first not null value will be retrieved.
DataSourceID ID of the control from which the data-bound control retrieves its list of data items.
DataItem The entity data item to which the control will bind. 
Format The custom format string through which the rendered value will be formatted.
Editable A boolean value that indicates whether or not this property value will be inline editable (provided the user has edit permission, and no other properties have been set on this control which disable inline editing support). Default is false.
EditType

String identifier of the type of editing interface to provide for this property. One of the following:

  • html
  • text
HtmlEncode A boolean value that indicates whether or not to perform an HtmlEncode on the output. Default is false. See HTMLEncode.
DefaultText The string to be rendered if the property value targeted by this control is null or empty.
Literal

A boolean value indicating whether or not this control should render as a literal value (only raw text with no surrounding DOM nodes)

Setting this value to true disables any inline editing support for the bound property.
PortalName The portal context configuration name that the control binds to.  Default value is unassigned.

DataBinding 

We have tuned the content map / sitemap rather heavily recently to ensure maximum portal performance. Part of that tuning is to only bring back the content attributes that we need. The OOB example uses a CrmEntityDataSource control that is bound to the current sitemap, which is only a partial entity and does not contain all of the fields including your custom fields. As such, the Property control will emit empty space.

The solution is to remove the DataItem="<%$ CrmSiteMap: Current %>" attribute from the CrmEntityDataSource control declaration and do the data binding in the code-behind of the containing page.

Here is an alternate code-behind for the Pages/Home.aspx.cs file that runs the home page for the customer portal site.

using System;
using Adxstudio.Xrm;
using System.Linq;
 
namespace Site.Pages
{
    public partial class Home : PortalPage
    {
	protected void Page_Load(object sender, EventArgs e)
	{
            if (!Page.IsPostBack)
            {
                var page = XrmContext.Adx_webpageSet.FirstOrDefault(p => p.Adx_webpageId == PortalContext.Current.Entity.Id);
		if (page != null)
		{
		    CurrentEntity.DataItem = page;
		}
            }
        }
    }
}