Using the Variable Page Type

For category pages and other sorts of pages that display a selection of items, the new Variable page type provides tremendous flexibility. It can do everything the legacy Category and List page types can do, and more.

A Big Leap Above the Usual URL Parameters

In the past, URL parameters, which are set off from the main part of the URL with a question mark (?), have been the primary solution. For example:

www.mycompany.com/product?category=furniture&channel=retail

Aside from the fact that they are ugly, URL parameters have a functional problem: pages using them are generally treated as uncached, since the parameters can have infinite variations. In the Webvanta system, if you want to pass parameters to a page using URL parameters, that page has to be set to page type of "Ajax", which really just means "uncached". So pages with URL parameters are slower, compared to other pages, because they aren't cached on the server.

The Variable page type eliminates most need for old-style URL parameters, in a way that provides very clean URLs and allows each page to be cached in the Webvanta system and throughout the Internet.

Related Articles

Passing Parameters to Variable pages

The basic mechanism is straightforward. You can have up to 10 parameters after the URL for the page, each separated by a slash.

If you have a page with the slug of "products", for example, you could use a URL like:

www.mycompany.com/products/retail/furniture

This URL passes two parameters to the products page: one whose value in this example is "retail", and another whose value is "furniture".

The meaning and number of these parameters is arbitrary, as far as the system is concerned. It is up to the WebvantaScript code on the page to use the parameter values to select the appropriate content.

Often, you'll want each parameter to correspond to a taxonomy. Continuing with the example above, we'd have two taxonomies:

  • channel (retail, wholesale)
  • product (furniture, soft goods, clothing, food)

Let's suppose then that we have taxonomies named "channel_categories" and "product_categories", and that there's an item type "product" that links to these two taxonomies.

Accessing the parameters

The magic of the Variable page is that each parameter in the URL is available to WebvantaScript on the page, as an ordinary WebvantaScript variable.

These variables have fixed names that represent their position in the URL. The first one is always "path-var-1", and then it continues from there: path-var-2, path-var-3, etc.

Let's return to our example:

www.mycompany.com/products/retail/furniture

On the products page, we can then include the code:

<h1>Product: <w:var name="path-var-2" /></h1>
<h2>Channel: <w:var name="path-var-1" /></h2>

This will display the two parameter values, which is a nice start, but not all that useful.

Using Variables in WebvantaScript

There is a special syntax for accessing WebvantaScript variables from within other WebvantaScript statements: put the variable name in double curly brackets, like {{this}}. (This syntax is needed because you can't use w:var as a parameter in a WebvantaScript statement, because WebvantaScript can't be nested.)

With the Item, Category, and List pages, the page type "magically" turns parameters into item and taxonomy contexts. This makes life simpler, but takes away flexibility.

The Variable page type, on the other hand, makes no assumptions about what any of the parameters means. As a result, it is up to the person coding the page to create WebvantaScript to use the parameters to select the desired content.

Continuing with the example we've been using, the follow code would display all the products in either retail or wholesale, as specified by the URL:

<w:kb:item:each type="product" taxonomy="channel_categories:{{path-var-1}}">

We need to take it one step further, since there's a second parameter:

<w:kb:item:each type="product" taxonomy="channel_categories:{{path-var-1}}&&product_categories:{{path-var-2}}">

Following this technique, you can use the URL parameters to select whatever database content you want.

Positional Parameters

Note that all parameters must be present, as this scheme depends on position to convey meaning. In addition, the item iterators won't work properly if one of the values is null, so you should ensure that even the last parameter is always present (or add code to deal with its absence).

You can use a placeholder value, such as "all", to fill the position for an unused variable.

Setting Page Metadata

When you use the more rigidly defined Item, Category, and List page types, the Webvanta system automatically uses the SEO fields (page metadata) from the database item or taxonomy term.

With a Variable page, the system makes no assumptions about what your parameters mean, so it can't set the metadata automatically. Instead, the page template must use WebvantaScript like that in the main part of the page to select the desired content, and then then create page metadata from that information.

Continuing with the example above, you would include something like this in the head section of the page template for the product category page:

<w:taxonomy name="product_categories:{{path-var-1}}" format_on_sub="pretty_url_decode">
  <title><w:name /></title>
  <meta name="description" content="<w:body truncate='170' />">
</w:kb:item:each>

There is one new bit of code we've introduced here: format_on_sub="pretty_url_decode". We'll describe the reason for that shortly.

This approach can be taken much further than the simple example above; you can use any WebvantaScript you want to create page metadata from any combination of database content, including taxonomy terms, item names, and so forth.

In a large site, you are likely to want different logic to create the metadata on different pages. To allow these pages to share a template, you can create a "page-metadata" region in the template, following the same approach as for page-css and page-js, so you can include the metadata code in the page instead of in the template.

Generating URLs

When generating a URL for a Variable page, simply construct the URL using a combination of static text and WebvantaScript.

Continuing with the example we began earlier in this article, we might use something like this to generate links to each of the retail product category pages:

<ul>
  <w:taxonomy:each name="product_categories">
    <li><a href="/products/retail/<w:name format='pretty_url_encode' />"><w:name /></a></li>
  </w:taxonomy:each>
</ul>

This code loops through each of the product categories, displaying the category name, and linking the name to the products page with the two parameters passed to it: "retail" as a fixed parameter, and the product category as a parameter that is filled in by the loop code.

Pretty URL Encoding and Decoding

The format attributes in the examples above, pretty_url_encode and pretty_url_decode, are required because you may have characters (such as spaces) in your taxonomy names that are not allowed in URLs. Those characters must be encoded before the name can be used as part of a URL. (Note that with items, generally you'd use the peram_link_name field to avoid this issue, but there is no perma_link_name field for taxonomy terms.)

pretty_url_encode is a modification of the normal URI encoding. The standard encoding uses numeric character values for all characters that can't be used in URLs. For example, the normal URI encoding replaces each space character with the string %20, so you'd get URLs like /products/retail/chairs%20and%20sofas. The "pretty" encoding replaces spaces with dashes, so you get the prettier URL of /products/retail/chairs-and-sofas.

When you are using a parameter encoded in this way, you must decode it when you use it. If you are simply displaying the variable's value, you can use the standard format syntax in the w:var statement, as follows:

<p>Channel: <w:var name="path-var-1" format="pretty_url_decode" /></p>

When you are inserting the parameter into another WebvantaScript statement using the {{name}} syntax, however, you need another way to specify the formatting. This is what "format_on_sub" (format on substitution) attribute does: when the paramater value is substituted into the WebvantaScript, the specified formatter is applied. That is the reason for this bit of code, which we presented earlier in this article:

<w:kb:item:each taxonomy="product_categories:{{path-var-1}}" format_on_sub="pretty_url_decode" type="product" limit="1">

Note: It is important to be aware that the pretty URL encoding is not quite as robust as the normal "ugly" encoding. In particular, any hyphens in the original string must be surrounded by non-space characters, and the original string may not include a slash (/).

See Formatting Information From the Database for more about formatting options.