Entity Presentation Layouts

Article last updated on the 28^th of November, 2023.

1. Introduction

2. Requirements

3. Configuration

3.1. Standard Presentation Layout

3.2. Handlebars Presentation Layout

3.3. Adaptive Cards Presentation Layout

4. Code Samples

1. Introduction

Entities and information about them are being presented in multiple places in WorkPoint. Some examples could be as search results in the Express panel, in the Top Panel of entities, in webparts, and in Microsoft Teams. As WorkPoint is an ever evolving product, additional places are guaranteed to be introduced.

When presenting entities, you typically need not just the name of the entity itself but also relevant information about the entity such as metadata or various properties - and what defines "relevant" in each case typically depends on the entity type. For projects, you are interested in information such as the responsible project manager budget, and deadline. For customers, you might want to know their address and the key contact. And you might even have some considerations about exactly how this information should be displayed in terms of layout.

With Entity Presentation Layouts, it is possible to create different layouts using a standard setup which shows a selection of columns (metadata, properties etc.) from WorkPoint entities. These layouts can be created as either "handle bar layouts" or "adaptive cards" and be presented in various places in the WorkPoint 365 interface.

For now, entity presentation layouts can be presented in:

Entity Top Panels
Express panel
The WorkPoint Entity Details webpart

Creating either CSS and HTML based Handlebar layouts or JSON based Adaptive Cards requires some insight into CSS, HTML or JSON but in the end of this article a few examples has been provided which can be used as is or slightly modified to get started quickly.

Note that Entity Presentation Layout settings replace the "Entity Details" settings.

2. Requirements

Please refer to the following table to see the license requirements for Entity Presentation Layouts:

V3 - Standard	V3 - Business	V3 - Enterprise	V4 package(s)
Not included	Included	Included	WorkPoint 365 Core

3. Configuration

Entity Presentation settings are set per business module.

In the settings page, presentation layouts can be configured and set to be displayed in various locations.

Follow these steps to access the Entity Presentation Settings:

On the WorkPoint solution, click the "Home" button.
Click the cog icon to access the WorkPoint Administration.

WorkPoint365 Administration - Google Chrome

In the WorkPoint Administration, click the header of the business module for which you wish to configure entity presentations.
In the business module menu, click "Entity Presentation Settings".

This opens the Entity Presentation Settings page:

Note that the following images of the Entity Presentation Settings page are shown with Top Panel version 1 enabled. With Top Panel version 2 enabled, this page would show an additional section called "Entity detail tabs". See this article for more information about this section and Top Panel settings in general.

Entity Presentation Settings (Projects) - Google Chrome

By default, WorkPoint provides a "Default Presentation Layout" for entities, which is assigned to the Top Panel, the WorkPoint Express Panel, and in Microsoft Teams.
The type of each presentation layout is displayed in the "Type" column. This article discusses presentation types in a later step.
To edit an existing presentation layout, click the "Edit" link.
To delete an existing presentation layout, click "Delete" in the "Delete" column. Note that the default presentation layout cannot be deleted.
To add a new Presentation Layout, click "Add Presentation Layout".
The "Hide stage information" option can be used to display or hide the pill that displays the current stage of an entity in the top panel.
To save the Presentation Layout settings, click the "Save" button.

3.1. Standard Presentation Layout

Note that WorkPoint does not support adding more than 12 fields of complex types to a presentation layout. Consider configuring multiple tabs if you need to display more than 12 fields of complex types.

In this example, we will look at how to set up a Standard presentation layout for entities on a Projects business module. A standard presentation layout allows you to select which columns from entities to display and in which order. We want it to be called "Standard Presentation Layout" and display set of columns, including the entity title, the Company, the project manager, the start date, the project type and more.

We start by creating a new presentation layout:

In the Entity Presentation Settings page, click "Add Presentation Layout".

In the "Add Presentation Layout" page, we can provide a name for the layout. We call it "Standard Presentation Layout".
For "Type" we select "Standard".
With the standard type selected, we can select an deselect the columns we want to display or hide for entities on the business modules using this layout. We make a selection of the Title, Company, Project Manager, and the other fields previously mentioned.
If we want to re-order the columns, we can to so by clicking the move-icon for the column in question and dragging it into the correct position, then letting go of the mouse button.
To save the configuration, click the "Save" button.
To go back to the Entity Presentation Settings page without saving the configuration, click "Back".

We save these settings are returned to the Entity Presentation Settings page:

The new presentation layout now appears in the list of layouts.
In this example, we assign the presentation layout to the Top Panel so that we can view the result.
We then click the "Save" button.

In order for the changes to fully take place, we need to clear the WorkPoint 365 Browser Cache. Follow these steps:

Office 365 Implementation - Home - Google Chrome

On the WorkPoint solution, click the "Home" button.
In the bottom of the side panel, click "Need help?".
Click "Clear WorkPoint 365 Browser Cache".

We can now see the changes in the Top Panel of a project entity on the solution where the previously selected columns are now displayed:

3.2. Handlebars Presentation Layout

For in-depth documentation of Handlebars, please visit this article: https://handlebarsjs.com/guide/#what-is-handlebars

In this example we will use Handlebars to create a presentation layout for entities on a Projects module on a Project Management solution. We will use it to display a series of columns from WorkPoint as well as their values. We will call it "Handlebars Layout", and we want to display the project title in a large font, and the following columns and values in a table below the title:

Project ID
Company
Project Manager
Project Manager E-mail
Start date
Completion date
Team (including all team members)

Finally, we will display the entity presentation layout in a webpart on Project sites.

We start by creating a new Entity Presentation Layout:

In the Entity Presentation Settings page, we click "Add Presentation Layout".

Edit Presentation Layout - Google Chrome

For title, we type in "Handlebars Layout".
For Layout type we select "Handlebars".

When we select "Handlebars" as type, the page displays two text boxes; the "Template" and the "Sample data" boxes:

In the "Template" box, WorkPoint provides a default sample template for the Handlebars layout to use for displaying information about the entities on the business module. This includes what information to display as well as how to style it.
In the "Sample data" box, we can load in samples of data from actual entities on the business module, which we can then use to format the Handlebars layout in the Template box. We can type an entity ID into the Sample data input box and click the "Load from entity id" button. This will import all the information we have about the entity on the business module with an ID of 2 into the Sample data box, as exemplified here:

We type the ID of "2" into the input box.
We then click "Load from entity id".
Information such as the entity title, project ID, and many other columns are imported into the sample data box.

We can now click the "Test" button and see what the default Handlebars layout template looks with the sample data:

The columns displayed in the Sample data window can be used to pull data from the WorkPoint system into the presentation layout. This is done using the two sets of curly braces. As an example, if we wanted to display the name of the project manager of an entity, we can find the internal column name in the sample data window (wpProjectManager) and use that inside two sets of curly braces as such: {{wpProjectManager.[0].title}}. Note that the index of the wpProjectManager column is used, as the wpProjectManager is an array of elements.

We can now use the information from the sample data to create the template for our Handlebars Layout, keeping in mind which columns we wanted to show. For this, we use the following CSS and HTML code:

The code sample is provided in the "Code Samples" section of this article.

We start by defining some styling for various elements in our HTML. We use the .hbLayout prefix in order to only style the elements using this presentation layout. If we did not do this, this HTML would also affect other items displayed on the same page. Additionally, we also define some styling for columns used for displaying information fro WorkPoint.
Inside the <body> tag, we first display the title of the entity using the <h1>Project: {{Title}}</h1> line. Next, we define a table and populate it with information from the WorkPoint entities.

With this code pasted into the Template window in the "Add Permission Layout" page, we can click the Test button and view the results:

As we are satisfied with the results, we click the Save button and return to the Entity Presentation Settings page.

As previously mentioned, we wish to display this presentation on each entity site on the Projects business module. We therefore go to the Master Site of the business module and add the Entity Details webpart:

Editing the Master Site of the Projects module, we add a new webpart and search for "entity details".
We click the "WorkPoint 365 - Entity Details" webpart to add it to the site.

To configure the webpart we click the "Configure web part" button.

In the "Select layout" section, we select the Handlebars Layout we just created. We then republish the Master Site page with the following result:

We will now synchronize the webpart to all other entities on the business module:

In the WorkPoint Administration, we click the header of the Projects module and select "Master Site Synchronization".

Master Site Synchronization (Projects) - Google Chrome

We leave all settings off besides the "Replicate Web Parts" settings, which we turn on.
We then click the "Synchronize all" button.

Once the synchronization is complete, we can try and inspect an entity on the business module. Why not have a look at the entity from which we pulled the sample data:

The webpart is displayed on the entity page and displays the data from the entity as it is supposed to.

3.3. Adaptive Cards Presentation Layout

For in-depth documentation on Adaptive Cards with JSON, please visit this portal: https://adaptivecards.io/explorer/AdaptiveCard.html

Please be aware that Adaptive Cards currently do not support showing images.

In this example, we will create a presentation layout of the "Adaptive Cards" type. We will use this layout to display some information from project entities on a Project Management solution, and to display a couple of buttons for various actions, such as editing the project, changing stage, etc.

We will use this layout to display entity information in the Express panel.

We start by creating a new presentation layout:

In the Entity Presentation Settings page, we click "Add Presentation Layout".

We provide the title "Adaptive Cards Layout" to the layout.
For Layout type, we select "Adaptive Cards".

When we select "Adaptive Cards" as type, the page displays two text boxes; the "Template" and the "Sample data" boxes:

In the "Template" box, WorkPoint provides a default sample template for the Adaptive Cards to use for displaying information about the entities on the business module. This includes what information to display as well as how and where to display it.
In the "Sample data" box, we can load in samples of data from actual entities on the business module, which we can then use to format the Adaptive Card layout in the Template box. We can type an entity ID into the Sample data input box and click the "Load from entity id" button. This will import all the information we have about the entity on the business module with an ID of 2 into the Sample data box.

As an example, we can type in "2" in the input box and load in that entity's data:

We type the ID of "2" into the input box.
We then click "Load from entity id".
Information such as the entity title, project ID, and many other columns are imported into the sample data box.

We can now try and test how the default Adaptive Cards template will look with the sample data:

To test the Adaptive Card template, click the "Test" button.

In the "Adaptive Card preview" section, the Adaptive Card test is displayed:

We can now tweak the code in the Template box.

Note that Adaptive Cards are based on JSON code.

For an interactive Adaptive Card builder, you can try this website: https://adaptivecards.io/designer/

As previously mentioned, we want to display some columns of information about the entities, as well as some buttons for actions related to the entities. In this example, we will display the following columns:

Project Title
Project ID
Company
Project Manager
Project Manager's E-mail
The number of open tasks on the entity

Further, we will re-order the buttons to show them in the following order:

Edit entity
Change stage
Create document
Create document (advanced)

For these buttons, we also want to add some images to represent the actions.

To display this information, we use the following JSON code:

The code sample is provided in the "Code Samples" section of this article.

In the top of the JSON code (in the "body") we define the type as "TextBlock". We also provide the "${Title}" variable for the "Text" property. This makes the Adaptive Card display the title of the entity in question in the very top of the card. We can also set the size of the text here. In this example, the text size is set to "Extra Large". For more information about how all different types of elements of Adaptive Cards can be defined and configured, please visit the following Microsoft documentation: https://adaptivecards.io/explorer/AdaptiveCard.html
Next we define a Column Set. A column set divides a region into Columns, allowing elements to sit side-by-side. This is e.g. useful for displaying WorkPoint column titles in one column of the card, and column values in another - which is exactly what we will be doing next.
We now define a column which holds labels for the WorkPoint columns to show. These labels are created as elements inside the "items" element array of the column. Each label is created as a TextBlock type with the texts set to be the names of the columns we want to display.
We then define another column which is used for displaying the values of the columns created in pt. 33. The elements are essentially the same, but for the text properties, we here provide variables such as "${wpProjectID}", "${wpParent[0].lookupvalue}", and "${wpProjectManager[0].title}". All the columns found in the Sample Box can be used to pull data from WorkPoint and be displayed on the adaptive card.
Lastly, we define the buttons we want to display on the adaptive cards. These are defined as an array of "actions" elements in an array. The actions in this example all use the same type, the "Action.OpenUrl" type. This action, when invoked, shows the given Url either by launching it in an external web browser or showing within an embedded web browser. For in-depth documentation on the Action.OpenUrl action as well as other action types, please visit this article: https://adaptivecards.io/explorer/Action.OpenUrl.html (External link). We provide a title for the button, as well as the URLs for the WorkPoint actions to execute once pressed. For each action element we also use the "iconUrl" property to link to an icon for the buttons.

WorkPoint provides the following WorkPointCardActions which can be used on Adaptive Cards:

WorkPointCardActions.Edit
WorkPointCardActions.ChangeStage
WorkPointCardActions.CreateDocument
WorkPointCardActions.CreateDocumentAdvanced

If we test this JSON code for the template, we get the following result:

In this case, we are satisfied with the card, so we save the configuration and return to the Entity Presentation Settings page.

The new Adaptive Cards Layout now appears in the list of presentation layouts.
In this example, we assign the Adaptive Cards Layout to both the WorkPoint Express Panel and to Microsoft Teams.
To save the settings, we click the "Save" button.

For the changes to fully take place, we need to clear the WorkPoint 365 Browser Cache. See pt. 19-20 for instructions.

When we select a project entity in the Express Panel, we now see the results of the configuration:

If we e.g. send a project to another person in a chat message in Microsoft Teams, we get the following result:

4. Code Samples

Handlebars CSS and HTML example:

<style type="text/css">
   .hbLayout table, th, td {
   border: 1px solid black;
   text-align: left;
   padding-right: 10px;
   padding-left: 5px;
   font-size:16px;
   }    
   .hbLayout h1 {
   font-family: "Segoe UI";
   font-weight: regular;
   font-size: 30px;
   margin-left: 5px;
   color: #f7941e;
   }    
   #col-1 {
   padding-left: 20px;
   background-color: #ebebec;
   }    
   #col-2 {
   padding-left: 20px;
   }    
   #col-3 {
   padding-left: 0px;
   list-style-type: none;
   }    
</style>
<body>
   <div class="hbLayout">
      <h1>Project: {{Title}}</h1>
      <table>
         <col id="col-1">
         <tr>
            <td>Project ID</td>
            <td>{{wpProjectID}}</td>
         </tr>
         <col id="col-2">
         <tr>
            <td>Company</td>
            <td>{{wpParent.[0].lookupValue}}</td>
         </tr>
         <col id="col-2">
         <tr>
            <td>Project Manager</td>
            <td>{{wpProjectManager.[0].title}}</td>
         </tr>
         <col id="col-2">
         <tr>
            <td>Email</td>
            <td>{{wpProjectManager.[0].sip}}</td>
         </tr>
         <col id="col-2">
         <tr>
            <td>Start date</td>
            <td>{{wpStartDate}}</td>
         </tr>
         <col id="col-2">
         <tr>
            <td>Completion date</td>
            <td>{{wpCompletionDate}}</td>
         </tr>
         <col id="col-3">
         <tr>
            <td>Team</td>
            <td>
               <ul id=col-3>
                  {{#each wpTeam}}
                  <li>{{this.title}}</li>
                  {{/each}}
               </ul>
            </td>
         </tr>
      </table>
   </div>
</body>

Click to copy

Adaptive Cards JSON Example:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.3",
  "speak": "Entity presentation preview",
  "body": [
    {
      "type": "TextBlock",
      "text": "${Title}",
      "size": "ExtraLarge",
      "isSubtle": true,
      "wrap": true
    },
    {
      "type": "ColumnSet",
      "columns": [
        {
          "type": "Column",
          "width": "auto",
          "items": [
            {
              "type": "Image",
              "url": "https://workpoint365test.sharepoint.com/sites/anm0012/SiteAssets/Icons/project_32.png",
              "size": "Medium"
            }
          ]
        },
        {
          "type": "Column",
          "width": "auto",
          "items": [
            {
              "type": "TextBlock",
              "text": "Project ID: ",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            },
            {
              "type": "TextBlock",
              "text": "Company: ",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            },
            {
              "type": "TextBlock",
              "text": "Project Manager: ",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            },
            {
              "type": "TextBlock",
              "text": "E-mail: ",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            },
            {
              "type": "TextBlock",
              "text": "Open Tasks: ",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            }
          ]
        },
        {
          "type": "Column",
          "width": "auto",
          "items": [
            {
              "type": "TextBlock",
              "text": "${wpProjectID}",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            },
            {
              "type": "TextBlock",
              "text": "${wpParent[0].lookupValue}",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            },
            {
              "type": "TextBlock",
              "text": "${wpProjectManager[0].title}",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            },
            {
              "type": "TextBlock",
              "text": "${wpProjectManager[0].sip}",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            },
            {
              "type": "TextBlock",
              "text": "${wpAggregatedOpenTasks}",
              "size": "Small",
              "spacing": "Small",
              "wrap": true
            }
          ]
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.OpenUrl",
      "title": "Edit",
      "url": "${WorkPointCardActions.Edit}",
      "iconUrl": "https://workpoint365test.sharepoint.com/sites/anm0012/SiteAssets/Icons/edit_32.png"
    },
    {
      "type": "Action.OpenUrl",
      "title": "Change stage",
      "url": "${WorkPointCardActions.ChangeStage}",
      "iconUrl": "https://workpoint365test.sharepoint.com/sites/anm0012/SiteAssets/Icons/stage_32.png"
    },
    {
      "type": "Action.OpenUrl",
      "title": "Create document",
      "url": "${WorkPointCardActions.CreateDocument}",
      "iconUrl": "https://workpoint365test.sharepoint.com/sites/anm0012/SiteAssets/Icons/doc_32.png"
    },
    {
      "type": "Action.OpenUrl",
      "title": "Create document (advanced)",
      "url": "${WorkPointCardActions.CreateDocumentAdvanced}",
      "iconUrl": "https://workpoint365test.sharepoint.com/sites/anm0012/SiteAssets/Icons/doc_32.png"
    }
  ]
}

Click to copy

Contents

1. Introduction

2. Requirements

3. Configuration

3.1. Standard Presentation Layout

3.2. Handlebars Presentation Layout

3.3. Adaptive Cards Presentation Layout

4. Code Samples

Comments

Contents

1. Introduction

2. Requirements

3. Configuration

3.1. Standard Presentation Layout

3.2. Handlebars Presentation Layout

3.3. Adaptive Cards Presentation Layout

4. Code Samples

Related articles