PIML Specification and Usage

The Basics

PIML has three main tags:

1. <$F> - Outputs the form label name for a SDK singular property. (see "Working with Singular Properties" below)
2. <$V> - Outputs the value for a SDK singular property. (see "Working with Singular Properties" below)
3. <$C> - Provides a way to access a SDK collection property. (see "Working with Collection Properties" below)

 

Working with Singular Properties

The <$F> and <$V> tags are used to retrieve property names and values. (Please note, the <$V> tag is not intended to be used with collection properties. For collection properties see "Working with Collection Properties" below) In it's simplest form it will look like this:

<$F>Name</$F>: <$V>Name</$V>

If, in the above example, the base SDK object is a User object with a user named Jane Smith and the default label has not been customized then the result would be:

Name: Jane Smith

If, however, the base SDK object is a project with a name of "My Super Important Program" and the default label for "Name" has been customized to "Program", then the same PIML would result in:

Program: My Super Important Program

PIML can also traverse the object structure to access nested properties like this:

<$V>User.Company.Name</$V>

 

Optional Attributes

The <$F> and <$V> tags also support the following optional attributes:

1. Prefix - Prepends the specified value to the front of the property label or value.
2. Suffix - Appends the specified value to the end of the property label or value.
3. FormatMask - Provides a way to format the property ($V) value. This is most useful for dates. NOTE: You must use standard C# format mask syntax.
4. Case - Specifies that the returned value should be upper or lower case. The case is determined by the following values:
   • 0 = No change (the same as omitting the Case attribute)
   • 1 = Uppercase (The following values are also accepted: upper, uppercase)
   • 2 = Lowercase (The following values are also accepted: lower, lowercase)
5. AnchorType - Specifies that the returned value should be an HTML anchor tag. The format of the anchor tag is determined by the following values:
   • 0 = No Anchor (the same as omitting the AnchorType attribute)
   • 1 = Relative Edit (returns an anchor tag with a relative URL to the edit form)
   • 2 = Relative Display (returns an anchor tag with a relative URL to the display form)
   • 3 = Fully-Qualified Edit (returns an anchor tag with a fully-qualified URL to the edit form)
   • 4 = Fully-Qualified Display (returns an anchor tag with a fully-qualified URL to the display form)
6. AnchorAttributes - Specifies a string of HTML attributes that should be added to the anchor tags.
7. DefaultValue - Specifies a value that should be used when the desired property has no value. 

 

Prefix

An example of using the Prefix attribute:

<$V prefix="My name is ">Name</$V>

Result:

My name is John Smith

 

Suffix

An example of using the Suffix attribute:

<$V suffix=" is my name.">Name</$V>

Result:

John Smith is my name.

 

Formatting Values

Sometimes it is desirable to format certain values. A common instance is DateTime values. In some cases you may only want to display the date portion and omit the time. You could accomplish this with the following PIML:

<$V formatmask="MM/dd/yyyy">CreatedDateTimeUTC</$V>

If the DateTime had a value of 2/28/2016 12:35:45.123, the result would be:

02/28/2016

 

Case

An example of using the Case attribute:

This action was performed by <$V case="upper">Name</$V>

Result:

This action was performed by JOHN SMITH

 

HTML Anchors

Sometimes a link to the object is desirable. You can do this by using the anchor attributes:

<$V AnchorType="3" AnchorAttributes="style='font-weight:bold;' class='myCssClass'">Name</$V>

Result:

<a href="/object/id" style='font-weight:bold;' class='myCssClass'>John Smith</a>

 

Working with Collection Properties

The <$C> tag is used to reference a SDK collection. Please note that it does not output any values on it's own. It must be used with the <$F> and <$V> tags to output values from items in the desired collection. Let's look at a simple example:

<$C:Users>
<$V>LastName</$V>, <$V>FirstName</$V><br/>
</$C:Users>

Notice that the <$C> tag includes a colon followed by the name of collection property, in this case ":Users". This would loop through a collection of SDK User objects found in a property named "Users" and might output the following list:

Smith, John
Smith, Jane
Public, Johnny
White, Mary
Black, Peter

 

Headers and Footers

You can add PIML header and footer sections to a collection with the use of <$CH> and <$CF> tags:

<$C:Users>
<$CH><table><tr><th>Last</th><th>First</th></tr></$CH>
<tr><td><$V>LastName</$V></td><td><$V>FirstName</$V></td></tr>
<$CF><tr><td>TOTAL USERS</td><td><$V>UserCount</$V></td></tr></table></$CF>
</$C:Users>

Example Result (assumes the target object has a property named "UserCount" and 5 items in a "Users" collection property):

<table><tr><th>Last</th><th>First</th></tr>
<tr><td>Smith</td><td>John</td></tr>
<tr><td>Smith</td><td>Jane</td></tr>
<tr><td>Public</td><td>Johnny</td></tr>
<tr><td>White</td><td>Mary</td></tr>
<tr><td>Black</td><td>Peter</td></tr>
<tr><td>TOTAL USERS</td><td>5</td></tr></table>

 

Optional Attributes

Like the <$F> and <$V> tags, the <$C> tag also supports the following optional attributes:

1. Prefix - Prepends the specified value BEFORE the first item in the collection.
2. Suffix - Appends the specified value AFTER the last item in the collection.
3. ListDelimiter - Specifies a string that will be inserted in between every result within the collection.
4. MaxResults - Specifies the maximum numbers of objects allowed in the collection.
5. SortProperty - Specify a property name on which to sort the collection.
6. SortDirection - Specify a sort direction. (0 = ascending, 1 = descending)
7. GetAllByPropertyName - Specifies the name of a property which contains a value (see GetAllByPropertyValue below) by which the collection should be filtered.
8. GetAllByPropertyValue - Specifies a value by which the collection should be filtered using the GetAllByPropertyName attribute to determine which property holds the value.
9. ItemIndex - Specify a zero-based index value that limits the collection to that one object.
10. CollectionFilterDateTimePropertyName - Specify a date/time property name by which to filter the collection.
11. CollectionFilterDateRangeStart - Specify the earliest date/time for the desired range
12. CollectionFilterDateRangeEnd - Specify the latest date/time for the desired range
13. DateRangeType - Specify a dynamic date range 

 

Prefix and Suffix

The prefix and suffix attributes are useful for situations where you want to add formatting to the beginning and end of the collection. For instance, if you want to show the list as a numbered HTML list you can use the Prefix and Suffix attributes like this:

<$C:Users SortProperty="LastName" Prefix="<ol>" Suffix="</ol>">
<li><$V>LastName</$V>, <$V>FirstName</$V></li>
</$C:Users>

Result:

<ol>
<li>Smith, John</li>
<li>Smith, Jane</li>
<li>Public, Johnny</li>
<li>White, Mary</li>
<li>Black, Peter</li>
</ol>

 

Creating Lists

Sometimes it is desirable to output a delimited list of values. To do that use the ListDelimiter attribute to specify the text to be used as a separator:

<$C:Users ListDelimiter=", ">
<$V>Name</$V>
</$C:Users>

Result:

John Smith, Jane Smith, Johnny Public, Mary White, Peter Black

 

Limiting Results

To limit a collection to a maximum number of objects use the MaxResults attribute like this:

<$C:Users MaxResults="4">
<$V>LastName</$V>, <$V>FirstName</$V><br/>
</$C:Users>

Then the result would only output the first 4 objects:

Smith, John
Smith, Jane
Public, Johnny
White, Mary

 

Sorting

What if you want to display the list in alphabetical order? The PIML might look like this:

<$C:Users SortProperty="LastName">
<$V>LastName</$V>, <$V>FirstName</$V><br/>
</$C:Users>

Then the list would output like this:

Black, Peter
Public, Johnny
Smith, Jane
Smith, John
White, Mary

If reverse alphabetical is desired:

<$C:Users SortProperty="LastName" SortDirection="1">
<$V>LastName</$V>, <$V>FirstName</$V><br/>
</$C:Users>

Then the list would output like this:

White, Mary
Smith, John
Smith, Jane
Public, Johnny
Black, Peter

 

Filtering

What if you want to limit the list to only users whose last name is Smith? The PIML might look like this:

<$C:Users GetAllByPropertyName="LastName" GetAllByPropertyValue="Smith">
<$V>LastName</$V>, <$V>FirstName</$V><br/>
</$C:Users>

Then the list would output like this:

Smith, Jane
Smith, John

 

If you want to limit the list to a specific date range then you can use the date range filters like this:

<$C:Users CollectionFilterDateTimePropertyName="CreatedDateTimeUTC" CollectionFilterDateRangeStart="1/1/2021" CollectionFilterDateRangeEnd="12/31/2021">
<$V>LastName</$V>, <$V>FirstName</$V><br/>
</$C:Users>

Instead of specific dates you can also specify a dynamic date range:

<$C:Users CollectionFilterDateTimePropertyName="CreatedDateTimeUTC" DateRangeType="LastYear">
<$V>LastName</$V>, <$V>FirstName</$V><br/>
</$C:Users>

 

 

ItemIndex - Target a Single Object in a Collection

If you want to output only a single object from a collection the PIML might look like this:

<$C:Users ItemIndex="0">
<$V>LastName</$V>, <$V>FirstName</$V>
</$C:Users>

With an ItemIndex value of 0, the collection is limited to the first item in the list and the result might look like this:

Smith, John

Then reason the result might look like the above is that a collection is not guaranteed to be in any particular order. In order to target a specific object it would be better to sort the collection:

<$C:Users SortProperty="LastName" SortDirection="0" ItemInddex="0">
<$V>LastName</$V>, <$V>FirstName</$V>
</$C:Users>

Then you can be sure that the same object is output every time:

Black, Peter

 

PIML In Action

PIML can be used in a variety of situations. For example, PIML provides the power to customize Word documents with data from Project Insight within the Microsoft Word Report Templates add-on in Project Insight. Go try it for yourself!