Methods that set and unset cookies, session, client, profile, and client permissions.
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.
Set a cookie that expires in 20 minutes
{%- var expiresDate = "now" | add_minutes: 20 -%}
{%- set_cookie loginsection "lastsection=accounts" expires:expiresDate path:"/protected" domain:".parentdomain.com" -%}This example demonstrates the use of the expires, path, and domain parameters of the set_cookie method.
Set a cookie with a reference variable
{%- var sectioncookie = 'accountspage' -%}
{%- var sectioncount = cookies[sectioncookie] | to_int | plus: 1 -%}
{%- set_cookie §ioncookie sectioncount -%}This example demonstrates the use of a reference variable to set a cookie with a dynamic name.
Set a cookie with a custom statistics string
{%- if session.allowed and permissions.allow_public_statistics -%}
{%- capture statisticsString -%}
SessionStart: {{session.start_date | date: 'MMMM dd, yyyy, H:mm:ss'-}}
SessionRequests: {{session.num_requests-}}
LastRequest: {{request.date | date: 'MMMM dd, yyyy, H:mm:ss'-}}
<<Add other custom statistics here>>
{%- endcapture -%}
{%- set_cookie site_statistics statisticsString -%}
{%- endif -%}Checks if the "allow_public_statistics" custom permission has been set, and if it has gathers information about the current session statistics for storage in a "site_statistics" cookie - presumably for display using javascript on the site.
"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.
Unset Cookie
{%- if cookie.advertising_id -%}
{%- unless permissions.allow_advertising -%}
{%- unset_cookie advertising_id advertising_alt_id -%}
{%- endunless -%}
{%- endif -%}If the "advertising_id" cookie has been set and the "allow_advertising" permission has NOT been granted, use the unset_cookie method to clear both the "advertising_id" and "advertising_alt_id" cookies.
Unset multiple Cookies
{%- var unset_cookies = request.query_params.unsetcookies | split: ',' -%}
{%- for cookie in unset_cookies -%}
{%- var cookie_alt = cookie | append:'-alt' -%}
{%- unset_cookie &cookie &cookie_alt -%}
{%- endfor -%}Checks if the "unsetcookies" query parameter was included in the request, and for each comma-delimited cookie name to unset, unset both the specified cookie and the "-alt" version of the cookie if it exists by using the unset_cookie method with two reference variables.
Saves custom properties on the session. Note that this doesn't mean much unless the user (or the developer) has granted permission for sessions.
Simple Use Case
{%- if request.query_params.sortby -%}
{%- set_session sortby:request.query_params.sortby -%}
{%- endif -%}
{%- var sortby = session.sortby | default: 'post_date' -%}
{%- blog_post_collection posts sort_by:sortby -%}This example uses the set_session method to save the "sortby" query parameter, so that future visits to the same page will utilize the same sorting even if it does not include the sortby parameter.
Advanced Use Case
{%- if submission.is_valid and submission.object_type = 'form_submission' -%}
{%- var forms_submitted = session.submittedForms | to_int | plus: 1 -%}
{%- var session_formname = form.name.value | prepend:'submitted_' -%}
{%- set_session formSubmitted:"true" submittedForms:forms_submitted domain:submission.domain &session_formname:'true' -%}
{%- endif -%}If submission is a valid form submission object, this examples saves four session variables for later use: formSubmitted will be set to "true", submittedForms will be incremented by 1, domain will be set to the submission domain, and a dynamic session variable constructed from the name of the form prepended by "submitted" will also be set to "true".
Removes custom properties from the session.
Simple Use Case
{%- if client_permissions.do_not_track -%}
{%- unset_session -%}
{%- endif -%}If the browser sent the "Do Not Track" header, remove all session properties.
Unset Multiple Session Properties
{%- if request.query_params.ad_setting == "false" -%}
{%- set_client_permission deny ads -%}
{%- unset_session facebook_advertiser_id google_ads_id other_third_party_ids -%}
{%- endif -%}Checks if the "ad_setting=false" query parameter was sent with the request, and if it was, explicitly deny the "ads" client permission and unset the three specified session properties. Multiple properties can be unset at once by providing each property name as a separate argument to the unset_session method.
Unset Session Properties Dynamically
{%- var props = request.query_params.clearprops | split: ',' -%}
{%- for prop in props -%}
{%- unset_session &prop -%}
{%- endfor -%}Checks if the "clearprops" query parameter was included in the request, and if it was, unset the specified session properties using the reference variable syntax.
Unset Session Properties Dynamically (Alternate Syntax)
{%- var props = request.query_params.clearprops | split: ',' | join: ' ' -%}
{%- if props is_valid -%}
{%- unset_session *props -%}
{%- endif -%}Checks if the "clearprops" query parameter was included in the request, and if it was, converts the comma-delimited list of property names to a space-delimited list and unsets the session properties with those names using the expanded variable syntax.
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.
Simple Use Case
{%- if request.query_params.hide_popup_for_all_time -%}
{%- set_client show_popup:"false" -%}
{%- endif -%}This example uses the set_client method to save the "show_popup" query parameter, so that future visits to the same page will not show the popup.
Multiple Dynamic Values
{%- if submission.is_valid -%}
{%- var forms_submitted = client.submittedForms | to_int | plus: 1 -%}
{%- var client_formname = form.name.value | prepend: 'submitted' -%}
{%- set_client submittedForms:forms_submitted lastKnownEmail:submission.email &client_formname:'true' -%}
{%- endif -%}This example uses the set_client method to save multiple dynamic values on the client for later use. The submittedForms variable is incremented by 1, the lastKnownEmail variable is set to the submission email, and a dynamic variable constructed from the name of the form prepended by 'submitted' will also be set to 'true'.
Removes custom properties from the client.
Simple Use Case
{%- if request.query_params.reset_counters == "true" -%}
{%- unset_client login_counter error_counter home_counter work_counter kitchen_counter -%}
{%- endif -%}Unsets the specified client properties if the "reset_counters" query parameter is present.
Unset Client Properties Dynamically
{%- var props = request.query_params.clearprops | split: ',' -%}
{%- for prop in props -%}
{%- unset_client &prop -%}
{%- endfor -%}Checks if the "clearprops" query parameter was included in the request, and if it was, unset the specified client properties using the reference variable syntax.
Unset Client Properties Dynamically (Alternate Syntax)
{%- var props = request.query_params.clearprops | split: ',' | join: ' ' -%}
{%- if props is_valid -%}
{%- unset_client *props -%}
{%- endif -%}Checks if the "clearprops" query parameter was included in the request, and if it was, converts the comma-delimited list of property names to a space-delimited list and unsets the client properties with those names using the expanded variable syntax.
{%- if client_permissions.do_not_track -%}
{%- unset_client -%}
{%- endif -%}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.
{%- if submission.is_valid -%}
{%- var bestScoreName = form.name.value | classname | prepend:'bestscore-' -%}
{%- var bestScore = submission.score | to_int -%}
{%- var previousBestScore = profile.attributes[bestScoreName] | to_int -%}
{%- if previousBestScore > bestScore -%}
{%- set bestScore = previousBestScore -%}
{%- endif -%}
{%- set_profile last_score:submission.score &bestScoreName:bestScore -%}
{%- endif -%}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.
Simple Use Case
{%- if request.query_params.hide_the_money -%}
{%- unset_profile show_me_the_money -%}
{%- endif -%}Removes the "show_me_the_money" profile property if the "hide_the_money" query parameter is present.
Unset Profile Properties Dynamically
{%- var clearprops = request.query_params.clearprops | split: ',' | join:' ' -%}
{%- if clearprops is_valid -%}
{%- unset_profile *clearprops -%}
{%- endif -%}Checks if the "clearprops" query parameter was included in the request, and if it was, converts the comma-delimited list of property names to a space-delimited list and unsets the profile properties with those names using the expanded variable syntax.
Unset Multiple Profile Properties
{%- if submission.is_valid and submission.score.value < 80 -%}
{%- unset_profile passed_certification_exam user_is_certified_for_x -%}
{%- endif -%}Unset multiple profile properties at the same time. In this example, the template will unset the "passed_certification_exam" and "user_is_certified_for_x" properties if the submission is valid and the score is less than 80.
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.
Simple Use Case
{%- if submission.is_valid and submission.score > 70 -%}
{%- set_profile_setting passed_test:'true' -%}
{%- endif -%}Stores a value in the "passed_test" profile setting. Does not check if the user is currently logged in, verify that the "passed_test" setting is valid, or check for other errors. If the user is not logged in or the setting is not valid, it simply won't be saved.
Use Case with Validation
{%- var new_layout = request.post_params['layout'] -%}
{%- var new_companyname = request.post_params['companyname'] -%}
{%- var new_description = request.post_params['description'] -%}
{%- set_profile_setting var errors = profile_errors layout:new_layout companyname:new_companyname description:new_description -%}
{%- if profile_errors -%}
{%- for error in profile_errors -%}
<p class="error">Error saving <strong>{{error.Key}}</strong>: {{error.Value}}</p>
{%- endfor -%}
{%- endif -%}Stores the values of the "layout", "companyname", and "description" form fields in the profile settings. If any of the settings are invalid, the errors are saved to the "profile_errors" variable and displayed to the user.
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.
{%- if request.post_params.clear_description -%}
{%- unset_profile_setting description -%}
{%- endif -%}Simple Use Case
{%- if request.post_params.clear_description -%}
{%- unset_profile_setting description -%}
{%- endif -%}Unsets the "description" profile setting if the "clear_description" post parameter is present.
Unset Multiple Profile Settings at Once
{%- if submission.is_valid and submission.score.value < 80 -%}
{%- unset_profile_setting passed_certification_exam certification_category -%}
{%- endif -%}Unset multiple profile settings at the same time. In this example, the template will unset the "passed_certification_exam" and "certification_category" settings if the submission is valid and the score is less than 80.
Unset Profile Settings Dynamically with Validation
{%- var clearsettings = request.post_params.clearsettings | split: ',' | join:' ' -%}
{%- var profile_errors = null -%}
{%- if clearsettings is_valid -%}
{%- unset_profile_setting set errors = profile_errors *clearsettings -%}
{%- if profile_errors -%}
{%- for error in profile_errors -%}
<p class="error">Error clearing <strong>{{error.Key}}</strong>: {{error.Value}}</p>
{%- endfor -%}
{%- endif -%}
{%- endif -%}Checks if the "clearsettings" post parameter was included in the request, and if it was, converts the comma-delimited list of setting names to a space-delimited list and unsets the profile settings with those names using the expanded variable syntax. If any of the settings are invalid, the errors are saved to the "profile_errors" variable and displayed to the user.
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.
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.
{%- 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.
Simple Use Case
{%- if request.query_params.user_confirmation != permissions.external_user.value -%}
{%- unset_client_permission external_user -%}
<p>Some error message about failed confirmation and please try again</p>
{%- endif -%}If the "user_confirmation" query parameter is not equal to the value of the "external_user" permission, unset the "external_user" permission and display an error message.
Unset Permissions Dynamically
{%- var unset_parties = request.query_params.third_party_unknowns | split: ',' -%}
{%- for party in unset_parties -%}
{%- unset_client_permission party -%}
{%- endfor -%}Loop through a dynamic list of permissions and unset each one.
Unset Permissions Dynamically Using the Expanded Variable Syntax
{%- var unset_permissions = request.query_params.unset_permissions | split:',' | join: ' ' %}{% if unset_permissions is_valid -%}
{%- unset_client_permission *unset_permissions -%}
{%- endif -%}If the "unset_permissions" query parameter was included in the request, convert the comma-delimited list of permission names to a space-delimited list and unset the permissions with those names using the expanded variable syntax.
Safely Unset Client Permissions
{%- if unsafely_nuke_the_permissions -%}
{%- unset_client_permission -%}
{%- elsif safely_nuke_the_permissions -%}
{%- var oldSession = session.allowed -%}
{%- unset_client_permission -%}
{%- if oldSession -%}
{%- set_client_permission allow session -%}
{%- endif -%}
{%- endif -%}Check whether all permissions should be unset or only most by safely unsetting all but the specified values. If not all permission should be unset, then store the values of permissions that should be preserved in separate variables, unset all permissions, and restore the permissions that should be preserved.
Simple Use Case
{%- if client_permissions.do_not_track -%}
{%- unset_session -%}
{%- endif -%}If the browser sent the "Do Not Track" header, remove all session properties.
Unset Multiple Session Properties
{%- if request.query_params.ad_setting == "false" -%}
{%- set_client_permission deny ads -%}
{%- unset_session facebook_advertiser_id google_ads_id other_third_party_ids -%}
{%- endif -%}Checks if the "ad_setting=false" query parameter was sent with the request, and if it was, explicitly deny the "ads" client permission and unset the three specified session properties. Multiple properties can be unset at once by providing each property name as a separate argument to the unset_session method.
Unset Session Properties Dynamically
{%- var props = request.query_params.clearprops | split: ',' -%}
{%- for prop in props -%}
{%- unset_session &prop -%}
{%- endfor -%}Checks if the "clearprops" query parameter was included in the request, and if it was, unset the specified session properties using the reference variable syntax.
Unset Session Properties Dynamically (Alternate Syntax)
{%- var props = request.query_params.clearprops | split: ',' | join: ' ' -%}
{%- if props is_valid -%}
{%- unset_session *props -%}
{%- endif -%}Checks if the "clearprops" query parameter was included in the request, and if it was, converts the comma-delimited list of property names to a space-delimited list and unsets the session properties with those names using the expanded variable syntax.
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.
Simple Use Case
{%- if request.query_params.user_confirmation != permissions.external_user.value -%}
{%- unset_client_permission external_user -%}
<p>Some error message about failed confirmation and please try again</p>
{%- endif -%}If the "user_confirmation" query parameter is not equal to the value of the "external_user" permission, unset the "external_user" permission and display an error message.
Unset Permissions Dynamically
{%- var unset_parties = request.query_params.third_party_unknowns | split: ',' -%}
{%- for party in unset_parties -%}
{%- unset_client_permission party -%}
{%- endfor -%}Loop through a dynamic list of permissions and unset each one.
Unset Permissions Dynamically Using the Expanded Variable Syntax
{%- var unset_permissions = request.query_params.unset_permissions | split:',' | join: ' ' %}{% if unset_permissions is_valid -%}
{%- unset_client_permission *unset_permissions -%}
{%- endif -%}If the "unset_permissions" query parameter was included in the request, convert the comma-delimited list of permission names to a space-delimited list and unset the permissions with those names using the expanded variable syntax.
Safely Unset Client Permissions
{%- if unsafely_nuke_the_permissions -%}
{%- unset_client_permission -%}
{%- elsif safely_nuke_the_permissions -%}
{%- var oldSession = session.allowed -%}
{%- unset_client_permission -%}
{%- if oldSession -%}
{%- set_client_permission allow session -%}
{%- endif -%}
{%- endif -%}Check whether all permissions should be unset or only most by safely unsetting all but the specified values. If not all permission should be unset, then store the values of permissions that should be preserved in separate variables, unset all permissions, and restore the permissions that should be preserved.