Set_client_permission

Set_client_permission

{% set_client_permission %}

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.

{% 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
 
How long until the permission should expire, specified as "num [minutes|hours|days|weeks|months|years]" where num is a positive integer. May either be specified directly in the method or read from a variable
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.

Related

{% set_title %}

Sets the page title.

{{ client }}

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.

{% set_description %}

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

{% set_session %}

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

{{ permission }}

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

{% set_timezone %}

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

{% set_content_type %}

Sets the Content-Type header for the HTTP response.

{% unset_client %}

Removes custom properties from the client.

{% unset_client_permission %}

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.

{% set_robots %}

Sets the robots meta directive.

{% set_client %}

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.

{% set_favicon %}

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

{% set_profile_setting %}

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.

{% set %}

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.

{% set_header %}

Sets one or more headers in the HTTP response.

{% set_dictionary %}

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.

{% set_cookie %}

Sets a cookie in the HTTP response.

{{ 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.

{% set_canonical_url %}

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

{% set_response_code %}

Sets the HTTP response status code.

Examples

Demonstrates how to set_client_permission deny.

set_client_permission deny

Copy
{% if request.query_params.allow_session == "true" %}
{% var allow_length = "1 year" %}
{% if request.query_params.allow_months %}
{% set allow_length = request.query_params.allow_months | append: " months" %}
{% endif %}
{% set_client_permission allow session renew for allow_length %}
{% elsif request.query_params.deny_session == "true" %}
{% set_client_permission deny renew %}
--equivalent to {% set_client_permission deny session renew for 1 year %}
{% endif %}

Allow Session Permission

{% if request.query_params.allow_session == "true" %}
{% set_client_permission allow renew %}
{% endif %}
Allow the session permission for the default timeframe (1 year). If the session has already been allowed, the renew argument will cause it to be updated with the new timeframe. Equivalent to {% set_client_permission allow session renew for 1 year %}

Simple Use Case

{% if request.query_params.allow_ads == "true" %}
{% set_client_permission allow 'ads' renew always %}
{% endif %}
If the "allow_ads" query parameter is set to true, update the client permission to allow the "ads" permission which will never expire.

Store A Permission Value

{% if request.query_params.allowed_ids is_valid %}
{% set_client_permission allow 'partner_ids' with:request.query_params.allowed_ids %}
{% endif %}
{% if request.query_params.denied_ids is_valid %}
{% set_client_permission deny 'denied_ids' with:request.query_params.denied_ids %}
{% endif %}
If the "allowed_ids" query parameter was passed in the request, store it's value in the allowed partner_ids permission. If the "denied_ids" query parameter was passed in the request, store it's value in the denied denied_ids permission. For both of these permissions, the expiration date will use the default timeframe (1 year) if the permission was not previously specified, and will remain unchanged if the permission was previously specified.

Dynamically Set the Length of a Permission

{% if request.query_params.allow_session == "true" -%}
{%- var allow_length = "1 year" -%}
{%- if request.query_params.allow_months is_int true and request.query_params.allow_months > 0 -%}
{%- set allow_length = request.query_params.allow_months | append: " months" -%}
{%- endif -%}
{%- set_client_permission allow session renew for allow_length -%}
{%- elsif request.query_params.deny_session == "true" -%}
{%- set_client_permission deny renew -%}
{%- endif -%}
If the "allow_session" query parameter is set to true, sets or renews the session permission. The session permission is allowed for a default of 1 year, but if the "allow_months" query parmeter is a positive number then it will be used to set the length of the session permission. If the "deny_session" query parameter is set to true, updates the session permission to be denied for the default timeframe (1 year).

Set a Permission to Expire at a Specific Time

{% if event.end_date is_valid %}
{% set_client_permission allow event.name.value until:event.end_date %}
{% endif %}
If event.end_date is a valid date, set a permission with the name of the event to allow until the specified date. The permission will expire at event.end_date.

Set Permissions Dynamically

{% if request.query_params.allow_networks %}
{% var networks = request.query_params.allow_networks | split: ',' %}
{% for network in networks %}
{% if network is_valid %}
{% set_client_permission allow network %}
{% endif %}
{% endfor %}
{% endif %}
If the "allow_networks" query parameter was passed in the request, set a permission for each network in the list. This works because "network" is a variable containin a string. If it were not a variable on the current scope, then the permission would be named "network" instead.

Prefer strings for static permission names

{% set_client_permission allow partner_ids with:request.query_params.allowed_ids %}
This code will sometimes work by setting a permission with the name "partner_ids", but if there is also a variable with that name then the value of the variable will be used instead, resulting in unexpected behavior. This can be easily avoided by placing the permission name in single or double quotes.