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
ExampleList all custom properties on client, session, or userIterate over the client, session, or profile to list all custom properties. The same patterns works for each object type.
Enumerate Client properties
Liquid
<h4>Client Properties:</h4>
<ul>
{%- for property in client -%}
<li><strong>{{property}}</strong> = {{ client[property] }}</li>
{%- endfor -%}
</ul>
This example outputs a list of all of the client properties for the current client. Using {% for property in client.properties %} would produce the same result.
Enumerate Session properties
Liquid
<h4>Session Properties:</h4>
<ul>
{%- for property in session -%}
<li><strong>{{property}}</strong> = {{ session[property] }}</li>
{%- endfor -%}
</ul>
This example outputs a list of all of the session properties for the current session. Using {% for property in session.properties %} would produce the same result.
Enumerate Profile attributes (mostly safe)
Liquid
<h4>Profile Attributes:</h4>
<ul>
{%- for property in profile -%}
<li><strong>{{property}}</strong> = {{ profile[property] }}</li>
{%- endfor -%}
</ul>
This example will work as long as there are no profile settings with the same names as the profile attributes. In that case, the profile setting would be output instead of the profile attribute. To avoid this, you can use profile.attributes[property] instead.
Enumerate Profile attributes (safe)
Liquid
<h4>Profile Attributes:</h4>
<ul>
{%- for property in profile -%}
<li><strong>{{property}}</strong> = {{ profile.attributes[property] }}</li>
{%- endfor -%}
</ul>
Outputs a list of all of the profile settings for the current profile, and does not risk outputting profile settings instead of profile attributes.
ExampleSet the current user's profileAssociate the current user with a profile using set_profile so profile-specific content and settings apply.
Liquid
{%- 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 -%}
ExampleLoad one profile and show id, email, and active state{% profile %} loads a single profile by id or GUID; id, email, and is_active are core profile fields.
Liquid
{%- profile var member = "member-42" -%}
{%- if member.is_valid -%}
<p>{{ member.id }} <{{ member.email }}> — {% if member.is_active %}active{% else %}inactive{% endif %}</p>
{%- endif -%}
ExampleFetch active profiles and list their ids and emails{% profiles %} returns a profiles list; is_active and other profile list options narrow results.
Liquid
{%- profiles var members = is_active:true limit:50 sort_by:"email" -%}
<ul>
{%- for member in members -%}
<li>{{ member.id }} <{{ member.email }}></li>
{%- endfor -%}
</ul>
The default output that the profiles will produce when it is output directly to the template - using the "output_in_list" property of each profile in the items list
List containing all of the combined profiles from the prepended, fetched, and appended lists. If unique is true, this list will not contain any duplicates. If max_size is set, this list will not contain more than the number of profiles specified.
If set, this is the maximum number of items that will be returned in the items list and the maximum number of items that will be included when this profiles object is enumerated as a list. When not set, this value will be 0.
The maximum number of items that were allowed to be in the list of fetched profiles. May be 0 in some cases (such as when when there are no fetched profiles.
The 1-based index of the paginated results returned in the list of fetched profiles, which is calculated from the start and limit parameters. Useful for paginated results.
If any items were fetched from the database, total_pages will contain the number of paginated result pages in the database for the provided arguments. This may also be calculated using the total_count and limit properties.
ExampleFetch active profiles and list their ids and emails{% profiles %} returns a profiles list; is_active and other profile list options narrow results.
Liquid
{%- profiles var members = is_active:true limit:50 sort_by:"email" -%}
<ul>
{%- for member in members -%}
<li>{{ member.id }} <{{ member.email }}></li>
{%- endfor -%}
</ul>
{% profile %}
Identifies the profile by its profile ID rather than a name. IDs are matched without regard to case.
{% profile output_to_template? [[var, set, or assign]? variable_name]? output_to_template? = value %}Parameters
output_to_templateoptionalflag
Include this flag to write the profile's output into the page at this point. What that output is differs by type, and for most types it is a built-in default that may change at any time, so see the output property of the profile object before relying on it. The flag may come before or after the variable name. When the call names no variable, the output is written whether or not the flag is present, which makes {% profile = value %} the smallest valid use of this method. When the call names a variable, the flag saves the profile to the variable and writes its output as well.
var, set, or assignoptionalkeyword
Chooses the scope that holds the variable. var, the default, stores it in the current scope. set and assign can store it in outer scopes; Variable Scopes compares the three and when each fits.
variable_nameoptionalvariable
The variable that receives the profile. It may also be written as a reference, &name, which reads the variable's name from another variable (see Methods Overview). Leave it out to write the profile to the template instead.
valuerequiredexpression
Required; without a value the method call is not valid. Identifies which profile to fetch. It can evaluate to the profile itself, to its GUID, or to other text that identifies it, which for most types is its name; a type identified some other way, or only by GUID, says so in its summary. Names are matched without regard to case, but accented letters must match. A GUID identifies exactly one record, whereas when several records share a name, which of them is returned is not specified, so giving the records you fetch by name unique names avoids the question. A name reads better in a template and a GUID is exact; neither suits every site. When nothing matches, no error is raised: the variable holds an invalid profile, whose is_valid is false, so check is_valid before using it. When the expression itself has no value, for example an undefined variable, the method does nothing and the variable keeps any earlier value. May use liquid filters.
ExampleLoad one profile and show id, email, and active state{% profile %} loads a single profile by id or GUID; id, email, and is_active are core profile fields.
Liquid
{%- profile var member = "member-42" -%}
{%- if member.is_valid -%}
<p>{{ member.id }} <{{ member.email }}> — {% if member.is_active %}active{% else %}inactive{% endif %}</p>
{%- endif -%}
{% profiles %}
The prepend, append and exclude arguments identify a profile the way {% profile %} does, by its profile ID or by its GUID.
Include this flag to write the profiles list's output into the page here. That output is a built-in default for most types and may change at any time, so see the output property of the profiles object before relying on it. The flag may come before or after the variable name. With no variable named, the output is written whether or not the flag is present; with one, the flag saves the list and writes its output too.
var, set, or assignoptionalkeyword
Chooses the scope that holds the variable. var, the default, stores it in the current scope. set and assign can store it in outer scopes; Variable Scopes compares the three and when each fits.
variable_nameoptionalvariable
The variable that receives the profiles list. It may also be written as a reference, &name, which reads the variable's name from another variable (see Methods Overview). Leave it out to write the list to the template instead.
argumentsrequiredcollection
Key:value pairs. May use the variable arguments syntax. Written after a required =. The name:value pairs choose which profiles to fetch and how to narrow, order and page them. Nothing is fetched unless the call gives an argument other than prepend, append, unique, exclude_prepended, exclude_appended, max_size and cache_random; without one, the list holds only the prepended and appended profiles.
Options
prependoptionallist
May be a single profile, a list of profiles, or the name or guid of one profile, to be included at the beginning of the profiles list.
appendoptionallist
May be a single profile, a list of profiles, or the name or guid of one profile, to be included at the end of the profiles list.
excludeoptionallist
May be a single profile, a list of profiles, or the name or guid of one profile that should NOT be included in the fetched results. Has no effect on prepended or appended profiles.
exclude_prependedoptionalboolean
True to specifically exclude all prepended profiles from the fetched results. If "unique:true" is specified this is the default behavior, although you may also specify "exclude_prepended:false" to allow any prepended items to be fetched along with other results anyway.
exclude_appendedoptionalboolean
True to specifically exclude all appended profiles from the fetched results. This is false by default - even if "unique:true" is specified - so that results are returned in the proper order.
uniqueoptionalboolean
True to remove duplicates from each of the resulting lists (prepended, fetched, appended, and items), although there may be duplicates between the prepended, fetched, and appended lists. The "items" list will include objects in the order in which they appear - with prepended items first, then fetched items, then appended items.
max_sizeoptionalinteger
The maximum number of items to be included in the "items" list. If there are any prepended or appended items, this will automatically lower the "limit" to only fetch as many profiles as needed. Note that this may also impact both the "page" and "total_pages" values in the resulting profiles. In order to use pagination with a list loaded using "max_size" use "start" instead of "page" and "limit".
filteroptionalvalue
Only include profiles that match the given string filter
is_activeoptionalvalue
only include profiles that either are or are not active
is_blockedoptionalvalue
Only include profiles that either are or are not blocked
queryoptionalvalue
Only include profiles whose custom settings match the given query. As with datastore item queries, only custom (configurable) profile settings are queryable this way, not built-in/reserved profile properties. Profile queries share the same advanced syntax as datastore item queries, which may be reviewed at https://help.marketpath.com/liquid/advanced-datastore-queries
attributesoptionalvalue
Only include profiles whose custom attributes match the given query. As with datastore item queries, only custom (configurable) profile attributes are queryable this way, not built-in/reserved profile properties. Profile queries share the same advanced syntax as datastore item queries, which may be reviewed at https://help.marketpath.com/liquid/advanced-datastore-queries
date_logged_in_startoptionalvalue
Only include profiles with date_last_logged_in greater than or equal to date_logged_in_start
date_logged_in_endoptionalvalue
Only include profiles with date_last_logged_in less than or equal to date_logged_in_end
date_created_startoptionalvalue
Only include profiles with date_created greater than or equal to date_created_start. Remember that date_created will typically be the date that the profile was first published.
date_created_endoptionalvalue
Only include profiles with date_created less than or equal to date_created_end. Remember that date_created will typically be the date that the profile was first published.
numeric_sortoptionalvalue
In addition to the shared sort_by values, sort_by accepts id, email, date_last_logged_in, or the key of a custom profile setting or attribute (settings are matched first). Custom values compare as text, so 10 sorts before 9, unless numeric_sort is set to true to compare them as numbers. A date setting sorts chronologically; an attribute is free-form text and sorts as stored.
startoptionalinteger
Set the 1-based index of the first profile to fetch.
pageoptionalinteger
Used to automatically calculate the first profile to fetch based on both the "limit" and the 1-based "page" value. Defaults to 1, but is ignored if "start" is set.
limitoptionalinteger
The maximum number of profiles to fetch. Defaults to 10; a value that is not a number also gives 10. The largest limit is 1000, and a limit of 0 or less, or above 1000, returns up to 1000 profiles. Note that if "max_size" is defined, then "limit" may be automatically lowered even if specified separately.
sort_byoptionalstring
Specify which property to sort the results by. Has no effect on prepended or appended profiles. An unrecognized value is ignored without an error and the default order is used. Some methods accept more values than the built-ins listed here; see each method. By default, results will be sorted by relevance if there is a filter string and date_created desc (newest first) if not. Options include:
relevance: only applies when there is a filter string. sort_direction applies: descending, the default, puts the best match first.
date_created: the date each profile was first published. Unpublishing and republishing one resets date_created to the current date.
random: results will be returned in a random order, which prevents the page from being fast-cached. Setting cache_random:true overrides this behavior and allows the page to be fast-cached anyway.
name
title
url
browser_title
sort_directionoptionalstring
asc or desc. Defaults to desc; any value other than asc sorts descending.
cache_randomoptionalboolean
True to allow the results to be cached when sort_by is "random".
ExampleFetch active profiles and list their ids and emails{% profiles %} returns a profiles list; is_active and other profile list options narrow results.
Liquid
{%- profiles var members = is_active:true limit:50 sort_by:"email" -%}
<ul>
{%- for member in members -%}
<li>{{ member.id }} <{{ member.email }}></li>
{%- endfor -%}
</ul>
{% 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.
{% set_profile attributes %}Parameters
attributesrequireddictionary
Key:value pairs with unique keys. May use the variable arguments syntax.
ExampleSet the current user's profileAssociate the current user with a profile using set_profile so profile-specific content and settings apply.
Liquid
{%- 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 -%}
{% 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.
{% unset_profile attributes %}Parameters
attributesrequiredlist
One or more values. May use the variable arguments syntax.
There is no option to unset all attributes from a profile - attributes must be removed by name.
ExampleClear the current profile with unset_profileClear the current profile with unset_profile so the user is no longer associated with that profile.
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
Liquid
{%- 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.
{% 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_profile_setting [[var, set, or assign]? errors=variable]? properties %}Parameters
var, set, or assignoptionalkeyword
Which scope to save the errors on. Only applicable if an errors variable is specified
variableoptionalvariable
The variable to save validation errors to. Validation errors will be specified as a list of Key:Value pairs, or null if there are no validation errors.
propertiesrequireddictionary
Key:value pairs with unique keys. May use the variable arguments syntax. The settings to set on the profile. Each property key should match a setting id, and the property value will be used for the setting value
ExampleHow to use the set_profile_setting methodSaves custom values to predefined profile settings that will be accessible whenever the current profile 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
Liquid
{%- 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
Liquid
{%- 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.
{% 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.
{% unset_profile_setting [[var, set, or assign]? errors=variable]? properties %}Parameters
var, set, or assignoptionalkeyword
Which scope to save the errors on. Only applicable if an errors variable is specified
variableoptionalvariable
The variable to save validation errors to. Validation errors will be specified as a list of Key:Value pairs, or null if there are no validation errors.
propertiesrequiredlist
One or more values. May use the variable arguments syntax. The ids of the settings to remove from the profile
There is no option to unset all settings on a profile - settings must be unset by name.
ExampleUnset a profile settingRemove a profile setting value with unset_profile_setting so it is no longer stored for the current profile.
Unsets the "description" profile setting if the "clear_description" post parameter is present.
Unset Multiple Profile Settings at Once
Liquid
{%- 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
Liquid
{%- 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.