Working with the Request

How to read query parameters and POST data and branch template logic on the request.

The request object gives your template access to the current HTTP request: the URL path, query parameters, POST data, headers, and more. Using it, you can change what the template outputs or which data it loads based on how the page was requested.

Query parameters: use request.query_params to read URL query parameters (e.g. ?page=2&sort=date). Access a single parameter with request.query_params['name'] or the bracket syntax your reference documents. Parameters are strings unless you convert them (e.g. with to_number or to_boolean). Use the default filter when a parameter might be missing.

POST data: use request.post_params to read form data submitted via POST. As with query params, access by key and handle missing or invalid values so your template does not break.

Branching on the request: use {% if %} with request properties to show different content or load different data. For example, show a sidebar only when request.query_params['sidebar'] is present, or fetch a specific page of results when request.query_params['page'] is set. You can combine this with the query_param_link method to build links that preserve or add query parameters.

For object properties, see Request Context. {% set_header %} is under HTTP Response. Cookies are under Identity & Access.

Example Get request parameters and fetch blog_posts with pagination and tag filterRead page and tag from query params, then fetch blog_posts with limit and sort.

{%- assign var postsPerPage = 10 -%}
{%- assign pageParam = 1 -%} 
<!-- Did a page param get passed in the url? -->
{%- if request.query_params['page'] -%}
	{%- assign pageParam = request.query_params['page'] | to_int -%}
{%- endif -%}
<!-- Did a tag param get passed in the url? -->
{%- if request.query_params['tag'] and request.query_params['tag'] != "" -%}
	{%- assign tagFilter = request.query_params['tag'] | url_decode | downcase -%}
{%- endif -%}

{%- blog_posts assign posts = blog:"The Kitchen Essentials" tag:tagFilter limit:postsPerPage page:pageParam sort_by:"post_date" sort_direction:"desc" -%}

{%- for post in posts -%}
	{{-post.title-}}
{%- endfor -%}

Example Convert query parameters to booleans and numbersShows how to convert query string parameters into strongly-typed values using to_boolean, to_int, and to_number.

Convert a query parameter to boolean

{% var show_buttons = request.query_params['show_btns'] | to_boolean | default:true %}

Sets the show_buttons variable to true unless the show_btns query parameter is present and set to false.

Convert a query parameter to integer

{% var limit = request.query_params['limit'] | to_int | default: 20 %}

Sets the limit variable to 20 unless the limit query parameter is present and set to a valid integer.

Convert a query parameter to number

{% var average = request.query_params['average'] | to_number | default: 2.5 %}

Sets the average variable to 2.5 unless the average query parameter is present and set to a valid number.

Each sub-example demonstrates a common pattern for converting query parameter values while providing sensible defaults.

Example Get POST (form) parameters from the requestRead form or POST body parameters from request.post_params for use in the template.

{%- if request.post_params.is_valid -%}
  {%- assign var username = request.post_params['username'] -%}
  {%- assign var password = request.post_params['password'] -%}
  {%- if username is_valid and password is_valid -%}
	{%- auth login username password -%}
  {%- endif -%}
{%- endif -%}
{%- unless auth.logged_in -%}
  <p>Could not log in</p>
{%- endunless -%}

Example Read and iterate over request.query_paramsAccess URL query parameters via request.query_params: count, length, keys, by_index, and conditions like has_key or contains.

{{ request.query_params }}

alpha=abc&beta=b&&emptyvariable&animals=cat&animals=dog&animals=fish

{{ request.query_params.count }}

There are 4 distinct query parameters in the URL: alpha, beta, emptyvariable, and animals. Note that the empty query parameter is NOT included in the count.

{{ request.query_params.length }}

There are total of 7 query parameters in the URL, including one that does not have a value, one that does not have a key or a value, and one that is repeated three times

{{ request.query_params.alpha }}

abc

The value of the alpha query parameter is abc

{{ request.query_params.emptyvariable }}

The value of the emptyvariable query parameter is empty

{{ request.query_params['animals'] }}

cat,dog,fish

The value of the animals query parameter is a comma-separated list of the values: cat, dog, and fish

{{ request.query_params[1] }}

beta=b

The value of the second query parameter is beta=b

{% if request.query_params has_key 'alpha' %}has alpha{% else %}no alpha{% endif %}

has alpha

The alpha query parameter is present in the URL

{% if request.query_params contains 'animals=cat' %}cat{% else %}no cat{% endif %}

cat

The animals=cat query parameter is present in the URL. Note that the contains condition checks for both the key AND the value of the query parameter.

{%- for param in request.query_params %} {% comment %}same as {% for param in request.query_params.by_index %} {% endcomment -%}
	{%- unless forloop.first %}, {% endunless %}{{param-}}
{%- endfor -%}

alpha=abc, beta=b, , emptyvariable, animals=cat, animals=dog, animals=fish

The query parameters can be iterated using a {% for %} loop. Note that this includes empty query parameters that do not have keys or values.

{%- for param in request.query_params.keys -%}
	{%- unless forloop.first %}; {% endunless %}{{param}}: {{request.query_params[param]-}}
{%- endfor -%}

alpha: abc; beta: b; emptyvariable: ; animals: cat,dog,fish

The query parameter keys can be iterated using a {% for %} loop. Note that this includes keys that do not have values, but does NOT include query parameters that do not have keys.

Example Default Numeric Query ParameterProvide a default value for a numeric query parameter

{% var page = request.query_params['page'] | to_int | default: 1 %}

Example Search with query parameters and limit result lengthUse query parameters to drive search and limit the number of results returned.

{%- var page = request.query_params.p | default:1 -%}
{%- var limit = request.query_params.l | default:25 -%}
{%- search set results request.query_params.q page:page limit:limit -%}

Example Include sidebar template unless a query param is falseInclude a sidebar template only when a query parameter is not false, using unless.

{%- unless request.query_params contains "show_sidebar=false" -%}
	{%- if request.query_params has_key "show_sidebar" -%}
		{%- include "_custom_sidebar" type:request.query_params.show_sidebar -%}
	{%- else -%}
		{%- include "_default_sidebar" type:request.query_params.show_sidebar -%}
	{%- endif -%}
{%- endunless -%}

Working with the Request

Working with the Request

Related