Client Permissions

The client_permissions object is available on every page, and contains information about whether or not the user (or developer) has granted permission to use specific features. By default the only feature controlled by this is sessions, but the permission system may be "extended" arbitrarily by the developer to control additional features. The permissions feature requires cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) will always behave like an initial page-load without existing permission information.

Properties of {{ client_permissions }} objects
Name	Type	Description
is_valid	Boolean	Will always be true
cookiename	String	The name of the cookie used for storing permissions. Will always be "_mp_permissions"
has_cookie	Boolean	True if the permissions cookie was already set prior to this request. False on the first page load, after the client has cleared their cookies, or on all requests from browsers with cookies disabled
cookie_expires	time	The date and time that the permissions cookie is set to expire
min_permission_expiration_date	time	The next date and time that one of the permissions is set to expire. Note that this does not distinguish between "allow" and "deny" permissions and will ignore permissions with no expiration date set. If there are no permissions with expiration dates set this property will be empty
max_permission_expiration_date	time	The latest date and time that one of the permissions is set to expire. Note that this does not distinguish between "allow" and "deny" permissions and will ignore permissions with no expiration date set. If there are no permissions with expiration dates set this property will be empty
do_not_track	Boolean	Whether or not the browser sent the "DNT" header in the request
keys	list	The list of permissions (both allowed and denied) stored in the client_permissions object
*	permission	Specific permissions may be accessed using {{ client_permissions.permissionname }} or {{ client_permissions['permission-name'] }}
allow_*	Boolean	Shortcut to check if a specified permission is both defined AND allowed in the permission system.
output	String	JSON representation of the client_permissions object, similar to calling {{ client_permissions \| inspect: 3, false }}

The client_permissions object is copyable, and when copied using the {% copy_to_dictionary %} method the keys will be the permission names and the values will be the corresponding permission objects. The client_permissions object may also be enumerated using the {% for %} method, which will loop through all of the related permission objects when the for loop is started. Permissions that are added during enumeration will NOT be included, permissions that are removed during enumeration WILL be included, and permissions that are modified during enumeration will be included along with their updated properties.

Every page on the site is created by processing templates using specific pre-defined inputs. These reserved variables are present on the root scope of every pageload.

May be any object, including simple, complex and list objects. In some cases may even include symbols and null.

The client object is available on every page, and contains information about the history of the browser used to access the site. Note that most of these properties are only meaningful if the user has allowed permission for sessions. Additionally, client properties require cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) or without permission for session will always behave like an initial page-load without existing client information. The client object is one of a handful of simple mechanisms to enable personalization on your site. Used well, these can be powerful tools for developers and website owners.

A field containing a user-selected date

The request object is available on every page, and contains information regarding the HTTP request that may be useful for serving and rendering the page.

An object containing information about permission allowed or denied in the permissions system and accessed using the {{ client_permissions }} object.

Can be any text, from the empty string ("") to the full HTML output of the template. When used alone in a conditional, all strings evaluates as true - even if they are empty or a value such as "0" or "false".

Removes custom properties from the client.

The cookies object is available on every page, and contains information regarding the cookies sent with the request. Note that this will typically only include cookies for the current or top-level domain on multi-domain sites.

Removes the specified permissions from the permissions cookie. Note that this is not the same as denying permission since there will be no record that permission was either granted or denied after the permission has been unset.

Saves custom properties on the client that will survive across multiple sessions until they are changed, unset, or the "session" permission expires. Note that this doesn't mean much unless the user (or the developer) has granted permission for sessions.

Represents a specific instant in a specific timezone.

Defines whether the client has granted or deined permission for a particular feature (eg: sessions). The only permission defined by default is the session permission (configurable in the site properties). However, the template developer may use this mechanism for their own purposes as well. The permissions defined by this method will be stored in the permissions cookie, which may be read and/or modified by client-side javascript.

Represents the empty string (""). When used alone in a conditional, evaluates as true, but when used with the is_valid conditional, evaluates as false.

An enumerable list containing zero or more objects. Lists may contain many different object types, although most lists only contain a single object type. There are a large number of other complex object types that are also lists (ag: an articlelist is a complex object but is also a list of article objects).

True or False

{% set_client_permission %}

{% set_client_permission [allow|deny|1|0]? permission_name renew? [with:value]? [always|for duration|until date]? %}

{% set_client_permission

mode

Must be one of allow, deny, 1 (alias for allow), or 0 (alias for deny). Defaults to allow

permission_name

The name of the permission to allow or deny. Defaults to the session permission

renew

If this permission has already been allowed or denied, the original permission expiration date will only be updated if "renew" is specified

with:

value

The value to store along with the specified permission

always

Specifies that the permission should not expire, which is a shortcut for a 50-year expiration date

for

Specify in combination with the duration. If specified, the always and until clauses are not allowed

duration

until

Specify in combination with the date. If specified, the always and for clauses are not allowed

date

The date that the permission will expire. If it is in the past, the permission will automatically be denied as expired

If none of the expiration clauses are specified, the permission expiration date will default to 1 year in the future. Remember that the expiration date specified here is for the permission, not for the effects of the permission. In the case of sessions, the expiration date defines how long the user has granted permission to have a session, regardless of the number or duration of sessions during that timeframe. If the permission has a value, the value will be stored along with the permission regardless of whether the permission has been allowed or denied. Permissions will never expire in the middle of a session - if a permission would be set to expire in the middle of a session, it will automatically be extended until the end of the session to prevent odd mid-session permission change bugs.

Sets the page title.

Sets the meta description for the current page, which is output by default as part of an HTML page's {{ automatic_markup }}.

Saves custom properties on the session. Note that this doesn't mean much unless the user (or the developer) has granted permission for sessions.

An object containing information about permission allowed or denied in the permissions system and accessed using the {{ client_permissions }} object.

Sets the default timezone to use when rendering dates and times on the page that do not already have a separate timezone configured.

Sets the Content-Type header for the HTTP response.

Removes custom properties from the client.

Sets the robots meta directive.

Sets the URL to the favicon for the current page, which is output by default as part of an HTML page's {{ automatic_markup }}.

Saves custom values to predefined profile settings that will be accessible whenever the current profile is logged in. Note that this is meaningless unless the user is logged in. Profile settings may include validation, in which case all settings will be validated before being set and any validation error will prevent the setting(s) from being set. Validation errors may optionally be output to a variable.

Replaces a value on the nearest scope where it has already been defined. If it has not been defined yet, it is stored on the root scope.

Sets one or more headers in the HTTP response.

Sets properties on an editable dictionary object. If the dictionary does not exist it will be created and stored on the current scope. If the dictionary exists but is not editable this will throw an error.

Sets a cookie in the HTTP response.

Sets the canonical URL for the current page, which is output by default as part of an HTML page's {{ automatic_markup }}.

Sets the HTTP response status code.

{% unset_client_permission %}

{% unset_client_permission properties? %}

{% unset_client_permission

properties

One or more values. May use the variable arguments syntax. The names of the permissions to remove. If not included, all permissions will be removed

Removes properties from an editable dictionary object. If the dictionary does not exist an empty one will be created and stored on the current scope. If the dictionary exists but is not editable this will throw an error.

Removes custom properties from the session.

An object containing information about permission allowed or denied in the permissions system and accessed using the {{ client_permissions }} object.

Removes custom properties from the client.

Removes custom properties from the attribute dictionary of the currently logged-in profile. Note that this is meaningless unless the user is logged in.

Removes custom values from the profile settings for the currently logged-in profile. Note that this is meaningless unless the user is logged in. For settings with a default value this will reset them to the default, and for all other settings this will set them to empty/unselected/false. Profile settings may be required and include validation, in which case all settings will be validated before being removed and any validation error will prevent any settings from being set. Validation errors may optionally be output to a variable.

"Unsets" one or more cookies. Because of how cookies work, this will actually ADD the cookie to the response with an expiration date in the past.

Examples

Shows how a developer can use different client permission flags control messaging and how to check for expiring permissions.

{%- if client_permissions.do_not_track -%}
You have requested that we do not track your information. Consequently we will return a simple generic response even though it may not provide the best experience.
{%- else -%}
{%- if client_permissions.allow_all -%}
{%- comment %}In this example "all" refers to a custom permission defined by the developer{% endcomment -%}
You have granted us unlimited power! You should have the best possible experience.
{%- if client_permissions.all.expires < request.date | add_weeks: 2 -%}
Your permissions will expire on {{ client_permissions.all.expires | date: 'MMM dd' }}. If you want to continue receiving the best possible experience, <a href="#">follow these instructions</a>.
{%- endif -%}
{%- else -%}
{%- if client_permissions.allow_generous -%}
You have allowed "generous" permissions. While not the best, this still allows for a good experience.
{%- elsif client_permissions.allow_limited -%}
You have allowed "limited" permissions. This is only slightly better than a completely anonymous experience.
{%- else -%}
You have not allowed any permissions. Your experience will be fully generic.
{%- endif -%}
To customize your options and improve your experience, <a href="#">click here</a>.
{%- endif -%}
{%- endif -%}

Performs a series of simple checks to determine the client's permission level and adjust the messaging accordingly. Starts with checking for the "do_not_track" flag, which is set by browsers that have enabled "Do Not Track" functionality, then checks for a series of custom permissions defined by the developer in order from most to least permissive. If the client has enabled the custom "all" permission, it also checks to see when it will expire. This example displays a simple message describing the client's permission level, but it could easily be adapted to set a variable, include a child template, or perform another action instead.

Demonstrates how the client_permissions object could be used to control the display of ads on a page.

{%- if client_permissions.allow_advertisements -%}
{%- assign allowed_ads = client_permissions.advertisements.value | default: "all" | split: "&" -%}
<ul>
{%- for ad in allowed_ads -%}
<li>{{ad | replace: '-' " " | replace: '_' " " | capitalize }} advertisements are allowed until {{client_permissions.advertisements.expires | date: 'MMMM dd, yyyy, H:mm'}}.</li>
{%- endfor -%}
</ul>
{%- endif -%}

Use a custom "advertisements" permission to control the display of ads on a page. In this example, the value of the advertisements permission is expected to be a delimited list of keys separated by ampersands. For each key, output a human-readable version of the key and the expiration date of the permission. Alternatively, the keys could be used to dynamically display a random advertistement from the specific category or for some other purpose.

Client Permissions