Setting the Context with WebvantaScript

WebvantaScript is somewhere between a markup language, like HTML, and a programming language, like JavaScript. We've tried to make it as simple as possible, while still giving you the power to achieve the results you want.

How WebvantaScript is Processed

All WebvantaScript statements are interpreted by the Webvanta server; they never reach the browser, which wouldn't know what to do with them. The "w:" prefix tells our server that it should read the statement and take the appropriate action, which in many cases includes inserting some text or HTML content into the data that is sent to the browser.

Snippets provide a simple example. The WebvantaScript statement

<w:snippet name="snippet_name" />

tells our server to go find the contents of the snippet named "snippet_name" and substitute its contents for the WebvantaScript statement when sending the page to the browser.

Setting Context

The snippet statement does the same thing, no matter where you place it in your code. Most other WebvantaScript statements, however, act differently depending on the context in which they are used.

For example, consider the statement <w:meta:title />. This returns the metadata title for the current page. The same statement returns different data, depending on what page it is on. In this case, the context is set automatically by the page. There's nothing you need to do to make this happen; the page context is set automatically.

For all contexts other than the page, you need to explicitly set the context. Here's a simple example:

<w:kb:item id="1234">
  <h1><w:name /></h1>
</w:kb:item>

The first statement sets the context to the item with the ID of 1234. The last statement ends the context; you must always end the context when you set it. In between, the w:name statement provides the name of this item. Note that the name field does not specify the item whose name we want; that comes from the context.

The power of this approach is two-fold. First, we need only set the context once, and then we can access any number of fields. For example:

<w:kb:item id="1234">
  <h1><w:name /></h1>
  <p>By <w:author /></p>
  <p>Published on <w:published_at /></p>
  <p><w:description /></p>
</w:kb:item>

Using Each to Iterate

Second, we can use the "each" statement to set the context and, at the same time, set up a loop that repeats for each item that meets our criteria. For example:

<w:kb:item:each category="Cats" type="Books" by="name">
  <h1><w:name /></h1>
  <p>By <w:author /></p>
  <p>Published on <w:published_at /></p>
  <p><w:description /></p>
</w:kb:item>

This code will repeat the lines between w:kb:item:each and /w:kb:item:each, once for each item of type Book and in the category Cats, ordered by name. The context is automatically set for each iteration to the appropriate item.

Nested Contexts and the Magic of "Current"

You can nest contexts, and the keyword "current" lets you access information from the outer context. For example, consider the following code:

<w:kb:category:each>
  <h1><w:name></h1>
  <w:kb:item:each category="current" type="Books" by="name">
    <h2><w:name /></h2>
    <p>By <w:author /></p>
    <p>Published on <w:published_at /></p>
    <p><w:description /></p>
  </w:kb:item>
</w:kb:category:each>

This example iterates through each of the categories, and for each it shows the name of the category, and then lists all of the books in that category. Note that the first w:name gives us the name of the category, because that's the current context at that point; inside the item context, w:name gives us the name of the item. (If you needed the name of the category when inside the item context, you could use w:kb:category:name.)

To restrict the item iterator to those books in the current category, we use the keyword "current", which takes the category from the outer context.

Special Page Contexts

On any page, there is a page context set, which enables you to access information from the page's information stored in the CMS (such as the meta title, meta description, etc.). In addition, there are three special page types that provide additional context: the Category, List, and Item page types. You set the page type using the pop-up list at the bottom of the page edit screen.

These special pages extract information from the page's URL, and use that information to set the context. For example, an item page my have a URL such as:

www.domainname.com/item/1234-this-is-the-title-of-the-item

The number 1234 is the ID of the item that is being displayed. The text after the number is ignored by the server but is provided to enhance the SEO value of the link.

Using the Special Page Context

On the item page, you can then simply begin the page with:

<w:kb:item>

and end it with

</w:kb:item>

and now the context is set to that item throughout the page. You don't need to specify the ID, because Webvanta knows that if this is an item page, it can get the ID from the URL.

List and Category pages extract the ID from the URL in a similar way, you can can set the category context with:

<w:kb:category>

and the item type context with:

<w:kb:resourcetype>

Note that often only one of these variables (item, category, and item type) is known. For example, a category page has no item or item type context; it is a mix of items and types with a certain category.

A List page can have an item type, a category, or both.

An Item page has an item context, of course, and it may also have a category and/or an item type context, depending on the source of the link to the page. For example, if you're viewing a category page and click on an item link, the category is conveyed automatically, so the item page can know what category page the user came from.

Using "Current"

The keyword "current" is also set by the page context, and it delivers different information depending on how it is used. For example, suppose you're on a list page, for which both the category and the item type are set by the URL. The following code will iterate through all of the items in the specified category and of the specified item type:

<w:kb:item:each category="current" type="current">
   [display the info for one item]
</w:kb:item:each>

Generating URLs

The above code iterates through all the items of a given type and category. For each item, you want to create a link to the item page. The path statement takes care of this for you:

<w:kb:item:each category="current" type="current">
  <a href='<w:path category="current" type="current" url="/item">'><w:name /></a>
</w:kb:item:each>

By setting the category and type to "current", the values for both are encoded into the URL, so the item page will have this context information (for creating breadcrumbs, for example, and determining which related items to display).