Personalization
Almost all of the liquid personalization capability is controlled by the permissions system. If the session permission has been allowed then the personalization discussed here will be usable. If the session permission has been denied, however, then the effects of personalization will effectively be nothing. Except for cookies - those are not subject to the personalization system.
Note that the session permission may be set to allow by default in the site settings - which may be desirable for some sites and undesirable for others thanks to European GDPR regulations.
Cookies
There are several liquid methods and objects designed specifically for referencing, setting, and unsetting cookies, these are the {{ cookies }} object, {% set_cookie %} method, and {% unset_cookie %} method.
Note that, while it is technically possible to use cookies for personalization even without user permission, it is not advisable to do so in most circumstances for three reasons:
- There is much more overhead related to cookies than there is to other methods of communication.
- Cookies may be added, removed, modified, and copied using client-side scripts.
- The personalization system was created for a reason and bypassing it could lead to unanticipated legal, technical, or other problems.
There are valid uses for cookies, however. Some of those reasons are:
- Saving information that is queryable and updatable using both template code and client-side javascript.
- Saving or accessing information between sites or domains that share a base domain name.
- Saving information for an extended period of time (longer than the session permission) or in order to make it accessible before/during/after a migration to or from another system.
{{ cookies }}
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.
Properties of {{ cookies }} objects
| Name |
Type |
Description |
| is_valid |
Boolean |
Will always be true |
| keys |
list |
The list of cookie names on the current request, including cookies that may have been added or removed after the request started processing. |
| * |
String |
Individual cookies on this request may be accessed using {{ cookies.cookieName }} or {{ cookies['cookie-name'] }} syntax |
| output |
String |
JSON representation of the cookies object, similar to {{ cookies | inspect: 3, false }} |
The cookies object is copyable, and when copied using the {% copy_to_dictionary %} the keys will be the names of the cookies and the values will be the corresponding cookie objects. You may also treat this object as a list containing all of the cookie names which may be iterated using a {% for %} loop.
Related
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.
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.
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.
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".
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).
{% set_cookie %}
Sets a cookie in the HTTP response.
There are a small number of reserved and forbidden cookie names, the most prominent being "_mp_permissions" - the name of the cookie used by Marketpath for handling permissions. You must use the {% set_client_permission %} and {% unset_client_permission %} methods to manage permissions instead of manipulating the permissions cookie directly.
Related
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.
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.
Sets the robots meta directive.
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.
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.
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.
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.
"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.
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.
Saves custom properties on the profile that will be accessible whenever the current profile is logged in. The properties will be saved to the profile's attribute dictionary. Note that this is meaningless unless the user is logged in.
{% unset_cookie %}
"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.
Related
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.
Removes custom properties from the client.
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.
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.
Sets a cookie in the HTTP response.
Client
In liquid, the "client" object represents all of the interactions in a browser on a specific computer. Note that this may be conceptually identical to a user or it may encompass multiple users sharing a browser (as in the case of a public or a shared computer).
Data may be saved to and retrieved from the client, which lasts for as long as the session permission is allowed. This means that if the session permission expires or is denied, the system will forget all data associated with the client.
To save data to the client use {% set_client %}. To query data saved on the client use the {{ client }} object. To remove data from the client use {% unset_client %}.
Note that saving data to the client is different than saving data to the session in that the data saved to a client will be remembered between sessions - for as long as the session permission lasts.
For performance and other reasons, you may only save a limited amount of information on the client. The number of properties that can be saved to the client may vary by site, and can be queried using {{ client.max_properties }}. If more properties are added than are allowed, then the oldest properties will automatically be unset.
Additionally, there are other useful properties that are accessible on the client - including the date of the first request, the number of pages viewed, the number of sessions that this client has created, and more.
{{ 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.
Properties of {{ client }} objects
| Name |
Type |
Description |
| is_valid |
Boolean |
Whether or not the user (or developer) has granted permission for a session |
| allowed |
Boolean |
Whether or not the user (or developer) has granted permission for a session |
| id |
String |
The unique identifier for the client browser. If the user does not have permission for a session this will be empty |
| user_agent |
String |
The user-agent string sent with the request. This is an alias of request.user_agent |
| permissions |
client_permissions |
The permissions that are set for the current client. The shortcut for this is {{ client_permissions }} |
| session |
session |
The current session for the client. The shortcut for this is simply {{ session }} |
| cookies |
cookies |
The cookies for the current client. This is an alias of {{ request.cookies }} and the shortcut for this is {{ cookies }} |
| first_request_date |
time |
The date that we received the first request from this client. Note that this is dependent on a number of outside factors, including the client's use (and/or clearing) of cookies and their allowance of sessions |
| num_requests |
Integer |
The total number of requests made by this client since the first_request_date |
| num_pages |
Integer |
The total number of successful page requests made by this client since the first_request_date |
| num_sessions |
Integer |
The total number of sessions created for this client since the first_request_date |
| properties |
list |
The full list of custom properties that are set for the current client. Note that this list only includes the keys, the values will have to be retrieved using the keys |
| max_properties |
Integer |
The maximum number of properties that may be stored on the client object. Adding new properties beyond that limit will result in the oldest properties being replaced by the newer properties. The default limit to the number of properties is currently 100. If you need more than 100 client properties contact Marketpath about raising your limit |
| * |
String |
Individual custom properties for the client may be accessed using {{ client.propertyName }} or {{ client['property-name'] }} syntax |
| output |
String |
JSON representation of the client object, similar to {{ client | inspect: 4, false }} |
The client object is copyable, and when copied using the {% copy_to_dictionary %} method, the keys will be the custom property names and the values will be the corresponding custom property values. The client object may also be enumerated as a list of strings, which will be the names of the custom properties saved on the client. Note that this list will only include the property names when the enumeration started and adding or removing client properties during enumeration will not affect the property names for the current enumeration.
Related
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.
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".
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.
Can be any number, including integers, decimals, or the value 0. Any value - including 0 - evaluates as true when used alone in a conditional.
Represents a specific instant in a specific timezone.
A whole (non-fractional, non-decimal) number. May be 0. Any value - including 0 - evaluates as true when used alone in a conditional.
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.
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).
The session object is available on every page, and contains information about the user's current session. Note that most of these properties are only meaningful if the user has allowed permission for sessions. Additionally, sessions require cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) or without permission for sessions will always behave like an initial page-load without existing session information. The session 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_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.
Related
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.
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.
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.
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.
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.
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.
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.
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.
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.
Saves custom properties on the profile that will be accessible whenever the current profile is logged in. The properties will be saved to the profile's attribute dictionary. Note that this is meaningless unless the user is logged in.
{% unset_client %}
Removes custom properties from the client.
Related
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.
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.
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.
Removes custom properties from the attribute dictionary of the currently logged-in profile. Note that this is meaningless unless the user is logged in.
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.
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.
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.
"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.
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.
Session
In liquid, the "session" object represents all of the client interactions within a limited amount of time. By default the session length is 60 minutes but the session length may be customized for a site in the site settings. Note that the session length is the amount of time between interactions before a new session is created - not the amount of time from the first interaction (so if the session length is 60 minutes and the user requests a new page every 59 minutes then their session will last indefinitely).
Although not strictly true it is generally assumed that while a client may encompass multiple users each session is only related to a single user. This is one of the key differences between the session and the client.
Data saved to and retrieved from the session will only last as long as the session remains active. To save data to the session use {% set_session %}. To query data saved on the session use the {{ session }} object. To remove data from the session use {% unset_session %}.
One other difference between the session and the client is that while the client can only save a limited number of properties, the session is not limited in the number of properties that may be saved to it (although we do not guarantee optimal performance if you start adding thousands of properties to sessions).
The session object also has some useful properties that the developer may utilize - including the session start time, the session end time (if the user does not make any further requests before then) the number of pages viewed, the number of unique pages viewed (ignores refreshes or going back to previously-viewed pages), the number of error pages viewed (eg: 404, 500, etc... errors), and more.
One final useful property of the session object worth noting here is the session history - which is a list of pages that the user has viewed during their current session. Using this property, it is possible to (for example) display links to the last 10 pages the user visited. One limitation of the session history is that it only stores the last 100 request the user has made - if a user has made more than 100 requests then you will only be able to query the 100 most recent requests.
{{ session }}
The session object is available on every page, and contains information about the user's current session. Note that most of these properties are only meaningful if the user has allowed permission for sessions. Additionally, sessions require cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) or without permission for sessions will always behave like an initial page-load without existing session information. The session 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.
Properties of {{ session }} objects
| Name |
Type |
Description |
| is_valid |
Boolean |
Whether or not the user (or template developer) has granted permission for a session |
| allowed |
Boolean |
Whether or not the user (or template developer) has granted permission for a session |
| id |
String |
The unique identifier for the user's session. This will contain a value even if the user is not allowed to have a session, but the value will change on every page load |
| first_page |
Boolean |
True if this is the first page load in the user's current session. Note that this will always return true if the user does not have permission for a session since we will have no "memory" of prior page loads for the current session |
| start_date |
time |
The time that the current session started (equivalent to the time that the first request was made for this session) |
| end_date |
time |
The time that the current session will expire if no more requests are made. Note that sessions are extended by every request and so the end_date will also be different on every request |
| num_requests |
Integer |
The total number of requests for the current session, including requests resulting in errors |
| num_pages |
Integer |
The total number of successful page requests for the current session. This is different than num_requests in that it does not include any requests which resulted in an HTTP response code other than 200. This also assumes that the current request will return a 200 response code |
| unique_pages |
Integer |
The total number of unique pages requested in the current session. This number could be significantly lower than num_pages if the user requests several pages multiple times |
| num_errors |
Integer |
The total number of errors returned in the current session. This includes any request that returns something other than a 200 response code |
| properties |
list |
The full list of custom properties that have been set for the current session. Note that this list only includes the keys, the values will have to be retrieved using the keys |
| history |
list |
A list containing the last 100 page views as page_view objects for the current session |
| * |
String |
Individual custom properties for the session may be accessed using {{ session.propertyName }} or {{ session['property-name'] }} syntax |
| output |
String |
JSON representation of the session object, similar to calling {{ session | inspect: 3, false }} |
The session object is copyable, and when copied using the {% copy_to_dictionary %} method the keys will be the custom session property names and the values will be the corresponding custom property values. You may also treat this object as a list containing all of the property names which may be iterated using a {% for %} loop.
Related
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".
Can be any number, including integers, decimals, or the value 0. Any value - including 0 - evaluates as true when used alone in a conditional.
An object containing information about a previous request in the current session
Represents a specific instant in a specific timezone.
A whole (non-fractional, non-decimal) number. May be 0. Any value - including 0 - evaluates as true when used alone in a conditional.
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).
{% 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.
Related
Removes custom properties from the session.
Sets the meta description for the current page, which is output by default as part of an HTML page's {{ automatic_markup }}.
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.
Sets the robots meta directive.
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.
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.
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.
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.
The session object is available on every page, and contains information about the user's current session. Note that most of these properties are only meaningful if the user has allowed permission for sessions. Additionally, sessions require cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) or without permission for sessions will always behave like an initial page-load without existing session information. The session 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.
Saves custom properties on the profile that will be accessible whenever the current profile is logged in. The properties will be saved to the profile's attribute dictionary. Note that this is meaningless unless the user is logged in.
{% unset_session %}
Removes custom properties from the session.
Related
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.
Saves custom properties on the session. Note that this doesn't mean much unless the user (or the developer) has granted permission for sessions.
Removes custom properties from the client.
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.
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.
The session object is available on every page, and contains information about the user's current session. Note that most of these properties are only meaningful if the user has allowed permission for sessions. Additionally, sessions require cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) or without permission for sessions will always behave like an initial page-load without existing session information. The session 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.
{{entity.visited}}
One additional "trick" you can do with the personalization system is identify whether a user has visited a specific page during their current session using the {{entity.visited}} property. This could be useful, for example, to identify whether the user is returning the current page or viewing it for the first time. Or to identify whether or not the user has previously visited the pricing page, a conversion page, or any other page on the same domain as the page they are currently viewing.
Profile
While the "client" and "session" objects are both temporary and are both limited to the live site, the "profile" is a permanent object accessible both on the live site and in from the management interface.
At its most basic, a "profile" represents a set of credentials and other personalization information. The credentials are stored securely and are not accessible via liquid, but the other personalization information is.
Profiles may either be created in the management interface or registered from the live site. In any case, all changes to a profile are synced between the management interface and the live site so that both environments are always up-to-date.
Authentication and registration on live sites should be handled using the {% auth %} method. This method also handles numerous other profile-related functionality - such as locking or unlocking accounts, changing the id, etc...
Once a profile is logged in, it is available in liquid from the {% profile %} object.
Profiles have two types of unstructured data. Profile attributes are simple key-value pairs that may be set and unset using the {% set_profile %} and {% unset_profile %} methods. Custom profile settings are defined at the site level and may be set and unset using the {% set_profile_setting %} and {% unset_profile_setting %} methods.
While it is possible for the same profile to be logged in from different clients and sessions, it is not advisable to make a design decision which requires this due to the increated risk of data corruption caused by simultaneous updates.
To learn more about profiles, refer to the full profile course.
{{ profile }}
Properties of {{ profile }} objects
| Name |
Type |
Description |
| object_type |
String |
Will always be datastore_item |
| is_valid |
Boolean |
True if this references a published profile |
| guid |
String |
The unique identifier for this profile |
| value |
String |
Contains the same value as guid |
| id |
String |
The identifier for the profile. May or may not be the same as email, depending on the site settings |
| email |
String |
Email address for this profile |
| force_password_reset |
Boolean |
If true, the user must reset their password at next login |
| is_active |
Boolean |
If true, the profile is active and can be used. If false, the profile must be activated before it may be used |
| date_activated |
time |
The date that this profile was activated |
| date_activation_code_expires |
time |
The date when the activation code will expire and no longer be valid |
| date_first_activated |
time |
The date of the first successful activation for this profile |
| is_locked |
Boolean |
If true, this profile is temporarily locked and may not be used to sign in until it is unlocked |
| date_locked_through |
time |
If this profile is locked, this will be set to the date that the profile will be automatically unlocked |
| date_last_logged_in |
time |
The date that this profile was last used to sign in to the website |
| is_blocked |
Boolean |
If true, this profile has been permanently blocked and may not be used to sign in |
| date_blocked |
time |
If this profile is blocked, this will be set to the date when the profile was blocked |
| attributes |
dictionary |
The custom attributes for this profile. Attributes may either be manually set in the Marketpath CMS UI or programmatically set from template markup |
| logged_in |
Boolean |
True if this profile is presently logged in on the current request |
| can_login |
Boolean |
True if the profile exists, is active, and is not blocked or locked |
| settings |
object |
An object containing all of the custom profile settings for this profile |
| field_id |
String |
The identifier for this field |
| label |
String |
The label for this field |
| output |
String |
The default output that the profile produces when output directly to the template. Currently simply outputs the email, but the default output may change at any time. Template developers should avoid using this and should handle the output of profiles themselves |
Related
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.
Object containing a list of key-value pairs where the keys are unique.
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.
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".
Stores information about the current state of profile authorization, which is the result of calls to the {% auth %} methods.
Represents a specific instant in a specific timezone.
The site object is available on every page, and contains information about the current site. This information is the same on every page for the site.
Contains multiple profiles.
{% set_profile %}
Saves custom properties on the profile that will be accessible whenever the current profile is logged in. The properties will be saved to the profile's attribute dictionary. Note that this is meaningless unless the user is logged in.
Related
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.
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.
Sets the robots meta directive.
Removes custom properties from the attribute dictionary of the currently logged-in profile. Note that this is meaningless unless the user is logged in.
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.
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.
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.
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.
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.
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_profile %}
Removes custom properties from the attribute dictionary of the currently logged-in profile. Note that this is meaningless unless the user is logged in.
There is no option to unset all attributes from a profile - attributes must be removed by name.
Related
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.
Removes custom properties from the client.
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 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.
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.
Saves custom properties on the profile that will be accessible whenever the current profile is logged in. The properties will be saved to the profile's attribute dictionary. Note that this is meaningless unless the user is logged in.
{% 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.
Related
Sets the specified profile settings to their new values on the auth profile (which is not necessarily the same as the currently-logged in profile). If any of the specified settings has validation, the new settings will be validated before being set. An invalid value for any setting will prevent any of the new settings from being set. If the profile exists and the auth is not aborted before the end of the request the new values will be saved to the profile. If the auth is aborted then the new values will not be saved in between requests. If the profile does not exist but is registered in the same request then the new values will be saved on the new profile.
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.
Unsets the specified profile settings from the auth profile (which is not necessarily the same as the currently-logged in profile). For settings with default values this will set them back to their defaults. For settings without default values this will set them to empty/unselected/false. If any of the specified settings is required, it will result in an invalid_value error and will prevent any of the new settings from being unset. If the auth is aborted then the unset settings will not be saved in between requests.
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.
Sets the robots meta directive.
Removes custom properties from the attribute dictionary of the currently logged-in profile. Note that this is meaningless unless the user is logged in.
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.
Sets the URL to the favicon for the current page, which is output by default as part of an HTML page's {{ automatic_markup }}.
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.
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.
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.
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 }}.
{% unset_profile_setting %}
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.
There is no option to unset all settings on a profile - settings must be unset by name.
Related
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.
Sets the specified profile settings to their new values on the auth profile (which is not necessarily the same as the currently-logged in profile). If any of the specified settings has validation, the new settings will be validated before being set. An invalid value for any setting will prevent any of the new settings from being set. If the profile exists and the auth is not aborted before the end of the request the new values will be saved to the profile. If the auth is aborted then the new values will not be saved in between requests. If the profile does not exist but is registered in the same request then the new values will be saved on the new profile.
Unsets the specified profile settings from the auth profile (which is not necessarily the same as the currently-logged in profile). For settings with default values this will set them back to their defaults. For settings without default values this will set them to empty/unselected/false. If any of the specified settings is required, it will result in an invalid_value error and will prevent any of the new settings from being unset. If the auth is aborted then the unset settings will not be saved in between requests.
Removes custom properties from the client.
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.
Removes custom properties from the attribute dictionary of the currently logged-in profile. Note that this is meaningless unless the user is logged in.
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.
"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.
Saves custom properties on the profile that will be accessible whenever the current profile is logged in. The properties will be saved to the profile's attribute dictionary. Note that this is meaningless unless the user is logged in.