Cookies

"It's still web development, it's just way easier!"

Manage Cookies

A cookie is a nugget of information that is stored on the client-side (a browser) instead of on the server. It will be available as a system variable as long as it exists and is valid for each page request. This allows for things like shopping carts and remembering user settings. Wrival will read, write, and delete cookies as instructed using special form field names, which system variable COOKIE_NAME and COOKIE_VALUE. The difference between the two are:

  • COOKIE_NAME uses the input field's name and its value for the cookie's list item.
  • COOKIE_VALUE adds an input field's value as a list item to the cookie.

Write a Simple Cookie

In the following example myCookie is the name of the cookie and its value will be value from its field. You can see how easy it would then be to use a cookie within HTML, JavaScript, and CSS.

<input type="hidden" name="COOKIE_NAME" value="myCookie">
<input type="hidden" name="myCookie" value="My Value">

Submit, then...

<#myCookie> My Value

The cookie, myCookie, is then saved in the browser until it expires. This means that it is available on all pages visited in the domain after that unlike a regular input field, which is only available on the page its submitted to. It also available to JavaScript and any other applications that use cookies.

Write Name and Value Pairs to a Cookie

In this example a cookie named cart will get the names and values from its matching fields as its value, which can then used as a list or by individual names and values within it.

<input type="hidden" name="COOKIE_NAME" value="cart">
<input type="hidden" name="cart_itemA" value="3">
<input type="hidden" name="cart_itemB" value="5">

Submit, then...

<#cart> itemA=3,itemB=5
<#cart["itemA"]> 3
<#cart["itemB"]> 5

Write Multiple Cookies

To write multiple cookies from the same form separate each of their names using commas in the value of the COOKIE_NAME field. Then for each cookie value (or name and value pair) start the name of the field with an underscore.

<input type="hidden" name="COOKIE_NAME" value="cart,sizes,colors">

<input type="hidden" name="cart_itemA" value="1">
<input type="hidden" name="sizes_itemA" value="Medium">
<input type="hidden" name="colors_itemA" value="Black">

<input type="hidden" name="cart_itemB" value="1">
<input type="hidden" name="sizes_itemB" value="Large">
<input type="hidden" name="colors_itemB" value="Red">

<input type="hidden" name="cart_itemC" value="5">
<input type="hidden" name="sizes_itemC" value="Small">
<input type="hidden" name="colors_itemC" value="Green">

Submit, then...

<#cart> itemA=1,itemB=1,itemC=5
<#sizes> itemA=Medium,itemB=Large,itemC=Small
<#colors> itemA=Black,itemB=Red,itemC=Green

Then of course you can reference the specific elements by using the list items syntax. <#colors["itemA"]> would return "Black" for example.

Write a Cookie Using Values Instead of Names

COOKIE_VALUE takes the pair name from the field and makes that the pair value for any of the field values. It's basically the opposite of how COOKIE_NAME works. If there's a naming conflict between a COOKIE_NAME and COOKIE_VALUE, COOKIE_NAME will overwrite a COOKIE_VALUE's pair.

<input type="hidden" name="COOKIE_VALUE" value="myList">
<input type="hidden" name="myList_100" value="blue,green,red">
<input type="submit" value="Add a list item to myCookie...">

Submit, then...

<#myList> blue=100,green=100,red=100

Delete a Pair Value from a Cookie

To remove an element from a cookie the pair's name needs to be passed and its value needs to be set as a dash (-). So to make a series of checkboxes that remove list items from a cookie you could set the checkboxes' values to a dash. Fields that have no values are not changed. Fields with values that are dashes are removed. And any new values are updated.

<input type="hidden" name="COOKIE_NAME" value="cart,sizes,colors">

<input type="hidden" name="cart_itemA" value="1">
<input type="hidden" name="sizes_itemA" value="Medium">
<input type="hidden" name="colors_itemA" value="Black">

<input type="hidden" name="cart_itemB" value="-">
<input type="hidden" name="sizes_itemB" value="-">
<input type="hidden" name="colors_itemB" value="-">

<input type="hidden" name="cart_itemC" value="5">
<input type="hidden" name="sizes_itemC" value="Small">
<input type="hidden" name="colors_itemC" value="Green">

Submit, then...

<#cart> itemA=1,itemC=5
<#sizes> itemA=Medium,itemC=Small
<#colors> itemA=Black,itemC=Green

Delete a Cookie

The COOKIE_DELETE field completely removes cookies at the time it is submitted. Separate each cookie to be deleted with a comma in the field's value. Otherwise a cookie will be deleted by the browser when it is set to expire. Cookies can have the same name with different domains attributes so those attributes need to be set as well if deleteing a cookie outside of what would be the default attributes.

<input type="hidden" name="COOKIE_DELETE" value="cart,sizes,colors">

Submit, then...

<#cart>
<#sizes>
<#colors>

Cookie Configurations

A cookie's lifespan and its realms that it should be available to are also configurable. The "Default" column explains the result if the configuration is ommited.

Field Name Expected Value Description Default
COOKIE_NAME Cookie Name(s) (letters, number, underscore only) Set a cookie's name and its value.
COOKIE_VALUE Cookie Name(s) (letters, number, underscore only) Set a cookie's name using a field's value and give it a value of 1.
COOKIE_DELETE Cookie Name(s) Remove a cookie. Same as from request.
EXPIRES_ + cookie name UTC (a specific time format). Wrival will also accept an integer which will be treated as seconds, added to now, then automatically converted to UTC. Set how long the to save the cookie. End of session.
DOMAIN_ + cookie name Domain Name (only) The current domain or a subdomain of it that the cookie is to be applicable. Same as from request.
PATH_ + cookie name An Absolute Path The path of where the cookie is to be applicable. / (root and recursively)
HTTPONLY 1 (but actually writes to it as "HttpOnly") This forces the cookie to only be used via the http protocol (no JavaScript). (off)
SECURE A secure cookie is only accessible in a secure (https) area. It's automatic based on where it's written.

Cookie Variables

When a form is submitted the cookie configurations are then available as as variables during that request. Pages visited afterward that fall under the cookie's configuration will still have the cookie's value available as a variable (by referencing the name of the cookie), but no longer with the rest of the form's fields including the configuration of the cookie.

Variable Description Example
<#cookies> A list of all the cookies available to the current request. If there are cookies that share the same name, they are only listed once in this variable. cart,sizes,colors
<#COOKIE_NAME> The form field COOKIE_NAME. cart,sizes,colors
<#COOKIE_VALUE> The form field COOKIE_VALUE. myList
<#COOKIE_DELETE> The list of cookies that were instructed to be deleted. cart,sizes,colors
<#EXPIRES_ + cookie name> A cookie's expiration in a UTC format. Tue, 18-Dec-2018 10:42:20 GMT
<#DOMAIN_ + cookie name> A cookie's domain that it is applicable within. wrival.com
<#PATH_ + cookie name> A cookie's path that it is applicable within. /
<#HTTPONLY_ + cookie name> A cookie's HTTPONLY property. 1
<#SECURE_ + cookie name> A cookie's SECURE property. 1

Cookie Expire

If a cookie doesn't have a set expiration time it will cease to exist once the browser is closed. To have a cookie to stay set the COOKIE_EXPIRES to a date format that the browser will accept. The format is "Wdy, DD-Mon-YYYY HH:MM:SS GMT". There is a built-in Wrival function for returning the format (utc) to make it easily be dynamic. Another alternative is to simply use just the number of seconds as the expiration value, which Wrival will automatically convert to the required UTC format. Setting the expiration to a specific amount of time is a breeze since all of Wrival's time conversions default to seconds.

This cookie expires 3 days from now. This was done by inserting <#gmttime + 3(days):utc> for the expires field's value.

<input type="hidden" name="COOKIE_NAME" value="myCookie">
<input type="hidden" name="myCookie" value="My Value">
<input type="hidden" name="myCookie_EXPIRES" value="Thu, 21-Dec-2017 04:53:34 GMT">

Or:

<input type="hidden" name="myCookie_EXPIRES" value="<#3(days)>">

Cookie Domain

By default, a cookie can only be written for the same domain and subdomain that it is being written. However, it can also be setup to be available to other subdomains by declaring the DOMAIN field (DOMAIN_ + cookie name) and giving it a value of just the domain name (minus the subdomain).

Cookie available only to a specific domain (only www.wrival.com can also read it). This is the default behavior so it is unneccesary to declare:

<input type="hidden" name="COOKIE_NAME" value="myCookie">
<input type="hidden" name="DOMAIN_myCookie" value="www.wrival.com">

Cookie available to any of its subdomains (start with a . as a wildcard) (www.wrival.com and preview.wrival.com (and any others) can read it):

<input type="hidden" name="COOKIE_NAME" value="myCookie">
<input type="hidden" name="DOMAIN_myCookie" value=".wrival.com">

Cookie Path

Another option for controlling where a cookie is available is by using the PATH field (PATH_ + cookie name). This allows control over specific paths to be valid.

Cookie available anywhere within its domain (/ and /else/ can read it). This is the default behavior so it is unneccesary to declare:

<input type="hidden" name="COOKIE_NAME" value="myCookie">
<input type="hidden" name="PATH_myCookie" value="/">

Cookie available to only a specific folder (only requests to /else/ can read it):

<input type="hidden" name="COOKIE_NAME" value="myCookie">
<input type="hidden" name="PATH_myCookie" value="/else/">

HttpOnly

Prevent any protocols other than HTTP from being used with the cookie.

<input type="hidden" name="COOKIE_NAME" value="myCookie">
<input type="hidden" name="HTTPONLY_myCookie" value="1">