How can we help you today?

How To Use Placeholders In ShortPoint Connections

In this article, we will show you how to use the placeholders in ShortPoint Connections. 


You will be able to retrieve information related to the currently logged-in user, show events for an upcoming period of time, modify the search query, and even get the value of any JavaScript global variable from the page.

These and many more options are possible when using dynamic data placeholders. 


TABLE OF CONTENTS


What is a Placeholder?


Placeholders, or data placeholders, are used to describe the mapping between the data retrieved from a data source and the layers composing the layout of a dynamically connected ShortPoint Design Element. Placeholders correspond to the fields in the data source. Using placeholders in ShortPoint Connections you can pre-fill certain parameters of the connection request to make it even more dynamic.


Placeholders have a special notation: a pair of square brackets and percentage symbols around the name of the field from where the data is taken - for instance [%Me('email')%], [%TODAY%], [%Now%], etc.


When the connection is running, each instance of a data placeholder is dynamically replaced by the content existing in the corresponding field retrieved from the data source. For example, you can retrieve the information related to the currently logged-in user like this:


https://graph.microsoft.com/v1.0/users/[%Me('email')%]/events


The [%Me('email')%] placeholder is used here to reference the current user's email in the connection URL.


ShortPoint Connections that Support Placeholders

Note: In the REST API and RSS Feeds connection types you may use placeholders in the URL configuration directly. For the News connections (Site News, Hub News and Organization News) you can also set them in the Use Case Parameters for the specific Use Cases.


Coming soon:


Supported Placeholders


TODAY


TODAY is a volatile function that returns the current date. 

You can use it to display the items (for example, events) for the specific time period only: current date, upcoming week, month etc., and modify the date format to your preferences. 


Here is the list of supported TODAY placeholders:

  • TODAY. This will return the current date.
  • TODAY + 7. You can change the number of days you would like to show using this placeholder by adding or subtracting the number of days from TODAY (e.g., TODAY + 10 will return 10 upcoming days, and TODAY - 30 will return 30 past days).
  • TODAY('FORMAT') + 7. You can change the date format using this placeholder. By default, TODAY will be translated into ISO format. Set the time format inside the parenthesis and wrap it in single quotes (e.g., here is how it will look like with the US locale date format: TODAY('MM-DD-YYYY') + 7).


Important: 
There is no need to add the Date and Time Format in the Use Cases for News and Graph API Connection Types. By doing that, you are only changing the request format. The returned values will not be affected, they are returned in ISO format. If you need to modify the format, you need to use the mapping function, enabling the Advanced Settings. Alternatively, if you are using Events Design Elements to display your Outlook events, you can change it using the Date/Time formatting option.


Please, continue to the How to Use Custom Date and Time Formats with ShortPoint Design Elements to know more about date formats in ShortPoint Connections.


Now


Now is a volatile function, that returns the current date and time. 


Similar to TODAY, you can use a Now placeholder to display the items for the specific time period. However, while TODAY is calculating the date (it always points to the midnight time - 00:00), Now is showing the current time. Therefore, it will be useful when you need to display time-specific results.


Here is the list of supported Now placeholders:

  • Now. This will return the current date and time. 
  • Now +7. You can change the number of days you would like to show using this placeholder by adding or subtracting the number of days from Now (e.g., Now + 10 will return 10 upcoming days, and Now - 30 will return 30 past days).
  • Now('FORMAT') + 7. You can change the date format using this placeholder. By default, TODAY will be translated into ISO format. Set the time format inside the parenthesis and wrap it in single quotes (e.g., here is how it will look like with the US locale format: Now('MM-DD-YYYY') + 7).


Important: 
There is no need to add the Date and Time Format in the Use Cases for News and Graph API Connection Types. By doing that, you are only changing the request format. The returned values will not be affected, they are returned in ISO format. If you need to modify the format, you need to use the mapping function, enabling the Advanced Settings. Alternatively, if you are using Events Design Elements to display your Outlook events, you can change it using the Date/Time formatting option.



Please, continue to the How to Use Custom Date and Time Formats with ShortPoint Design Elements to know more about date formats in ShortPoint Connections.


Me


Use Me to retrieve the properties and relationships of the user object. 

Here is the list of the user object properties, supported as placeholders for the ShortPoint Connections:

  • Me('DisplayName')
  • Me('Email')
  • Me('LoginName')
  • Me('Id')

Current


Use Current to retrieve the properties of the current site collection, such as URL, language, user, etc.
It takes the data values from the _spPageContextInfo variable.

Here is the list of the properties that are supported as placeholders for the ShortPoint Connections:

  • Current('SiteUrl')
  • Current('SiteRelativeUrl')
  • Current('SiteId')
  • Current('SiteColor')
  • Current('Language')
  • Current('CultureName')
  • Current('UserDisplayName')
  • Current('UserEmail')
Note: 
Current('CultureName') placeholder includes information about the current regional settings on the system, and the display format of items such as numbers, dates and time. It returns the Locale setting name which is set in the Site Collection's Regional Settings.

QueryString


You can extract text from the URL query string parameters to show them in the personalization text.

  • QueryString('#AnyQueryStringProperty')

For example, if the current browser URL is: https://mycompany.sharepoint.com?Mode=Edit, the placeholder QueryString('Mode') will be replaced with 'Edit' value.


Script


With Script placeholder you can get the value of any JavaScript global variable from the page. The syntax is the following:

  • Script('#AnyJavascriptLine')

For example, you can use these placeholders:

  • Script('_spPageContextInfo.userDisplayName') - Will be replaced with the current user's Full Name;
  • Script('_spPageContextInfo.userDisplayName.split(" ")[0]') - Will be replaced with the first part of the current user's Full Name.


Important: 
Inside the Script parentheses, you need to use single quotes: Script('_spPageContextInfo.userDisplayName'). However, if you need to use JavaScript methods inside the Script placeholder, only double quotes are re-supported: Script('_spPageContextInfo.userDisplayName.split(" ")[0]'). 

How to Use Placeholders?


There are two options to use placeholders in ShortPoint Connections: you can set them directly in your connection URL, or set them as the Use Case parameters


Important: 
Please keep in mind that you always need to use a special notation for the placeholders - a pair of square brackets and percentage symbols around its name, e.g. [%TODAY%].


Option 1: Setting as the Use Case Parameters


We have introduced Use Cases in ShortPoint Connections to offer you the quickest way of presenting dynamic content on the site pages. 


Some use cases require filling in the Use Case Parameters - additional required parameters to display content. Here is where you can use the placeholders if you would like to always get dynamic values of the content data.


Note: 
To know more about the use cases, please check our solution article: Getting Started with Use Cases.


As an example, we will show you how to use placeholders for Hub News and Microsoft Graph API Connection types:


  • Hub News Connection Type - Recently Modified Use Case


For the purpose of this article, we will be using the Image Lists Design Element for displaying the Hub News


Switch to the Connect tab and choose Hub News from the connection types:



Fill in the required fields for the Hub News connection.


Note: 
To get more familiar with the Hub News connection type, check our solution article: Connection Type: Hub News.


Scroll down to the Use Cases section and select Recently Modified use case:



You will see that this use case requires an additional parameter - Latest Date:



You will need to enter the latest date to include. Here you can use a static value and enter the date (e.g., 01-03-2021), or use the placeholder to get the dynamic results.


By default, its value is set to [%TODAY - 100%]. It displays all hub news items, modified in the last 100 days from today's date. 


If you'd like to display the items modified in the last 7 days from today's date, all you need to do is simply change the number in the placeholder to 7, like this: [%TODAY - 7%]:



Important: 
Do not remove the placeholders' notation.


After that click Apply Parameters:



You may also set the caching settings in the Performance & Caching section.


After you are done, set up the connection by pressing the Connect button:



Do not forget to do the items mapping in the Items tab:



Note: 
Check our ShortPoint Connect: Basic Tutorial if you need more information about the items mapping.


That's it. You can now Insert/Update your connected Design Element and save your page:



Now the connection data will be pulled and updated automatically according to the chosen Use Case. In this given example, the hub news will be updated every day to display the news items modified in the last 7 days.


  • Microsoft Graph API Connection Type - My Events for the Next Week Use Case


Note: 
Microsoft Graph API Connection type is coming soon.


For the purpose of this article, we will be using the Events Design Element.


Switch to the Connect tab and choose Microsoft Graph API from the connection types:



In the Use Cases section select My Events for the Next Week use case:



You will see that the Microsoft Graph API URL has been updated:



The URL you will see there is as follows:


https://graph.microsoft.com/v1.0/users/[%Me('email')%]/calendarview?startdatetime=[%TODAY%]&enddatetime=[%TODAY + 7%]


This use case has three placeholders, used for defining:

  • the current logged-in user ([%Me('email')%]);
  • the start date and time of the user's events ([%TODAY%]);
  • the end date and time of the user's events ([%TODAY + 7%]).

You may scroll down to the Use Case Parameters section and change the Start and End Dates:



For example, you can change the End Date to [%TODAY + 30%] to display events for the upcoming month:



Important: 
Do not remove the placeholders' notation.


After you have modified the parameters, click Apply Parameters button:



You will notice that the URL in the Microsoft Graph API field has changed to:


https://graph.microsoft.com/v1.0/users/[%Me('email')%]/calendarview?startdatetime=[%TODAY%]&enddatetime=[%TODAY + 30%]



Use the Other Settings section to define additional parameters for your connection, such as Items Limit or Enable Advanced Settings (to add results mapping function, custom headers etc.). You may also set the caching settings in the Performance & Caching section.


After you are done, click Connect to set up the connection:



Do not forget to do the items mapping in the Items tab:



Note: 
Check our ShortPoint Connect: Basic Tutorial if you need more information about the items mapping.


That's it. You can now Preview and Insert/Update your connected Design Element, and save your page:



Now the connection data will be pulled and updated automatically according to the chosen Use Case. In this given example, the user's events will be updated every day to display the upcoming events for the next 30 days.


Option 2: Modifying the Connection URL


You can set the placeholders in the connection URL itself.


As an example, we will show you how to use placeholders for the REST API Connection type.


  • Display All Users of the Current Site Collection


We will use Simple Lists Design Element to display the users and their contact emails.


Switch to the Connect tab and choose REST API from the connection types:



To get the users of the current site collection, use the following URL and paste it to the REST API URL field:


[%_spPageContextInfo('webAbsoluteUrl')%]/_api/web/siteusers


Here we use placeholder _spPageContextInfo('webAbsoluteUrl') for defining the current site URL.

Click Connect to set up the connection:



Do not forget to do the items mapping in the Items tab.



Note: 
Check our ShortPoint Connect: Basic Tutorial if you need more information about the items mapping.


That's it. You can now Preview your results and Insert/Update your connected Design Element and save your page:



Now the connection data will be pulled and updated automatically according to set parameters.


  • Display Groups of the Current Site Collection


We will use Tiles Design Element to display the groups.


Switch to the Connect tab and choose REST API from the connection types:



To get the groups of the current site collection, use the following URL:


[%_spPageContextInfo('webAbsoluteUrl')%]/_api/web/roleassignments/groups


Here we use placeholder _spPageContextInfo('webAbsoluteUrl') for defining the current site URL.

Click Connect to set up the connection:



Do not forget to do the items mapping in the Items tab:



Note: 
Check our ShortPoint Connect: Basic Tutorial if you need more information about the items mapping.


That's it. You can now Preview your results and Insert/Update your connected Design Element and save your page:



Now the connection data will be pulled and updated automatically according to set parameters.


Bonus: Using Placeholders Outside ShortPoint Connections


Placeholders have been extended in the entire ShortPoint product. From now on, you can use them in any Design Elements in the text fields (Custom CSS, Items tabs, etc.)


For example, you can add a TODAY placeholder to the Subtitle field of the Panel Design Element:



Note: 
To know more about date and time formats, check our solution article on How to Use Custom Date and Time Formats.


You can add dynamically connected ShortPoint Design Elements as Panel content.

In our case we are using Simple Lists that are showing a list of tasks for the current date:



That's it! Stay tuned for more use cases and detailed tutorials.


Related articles:

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.

World's best intranet sites are designed using ShortPoint

Get started today! Learn more
See all 23 topics

Start a trial

Ignite your vision. Install ShortPoint directly on your site, or play in sandbox mode. No credit card required.

Get started today

World’s best intranet sites are designed using ShortPoint

Thousands of companies using ShortPoint everyday to design, brand and build award winning intranet sites.

Get started Learn more