WebvantaScript Cheat Sheet

Page Info

Each page has its own metadata, which you set in the page edit screen and can recall as needed, typically in templates.

<w:meta:title />

Provides metadata title for the current page.

<title><w:meta:title /></title>

The only place this WebvantaScript statement is typically used is to render the title tag contents in the head section of the page. You'll generally want this line of code in every template.

<w:meta />

Produces meta description and keyword tags for current page. A shortcut that is equivalent to <w:meta:keywords /><w:meta:description />.

<w:meta />

Use in the head section of the page template to render the keyword and description meta tags.

<w:url />

Provides full slug for the current page (not really the full URL, since it does not include http:// or the domain name).

<script type="text/javascript">
digg_url = 'http://www.webvanta.com/<w:url />';
digg_title = '<w:meta:title />';
digg_bodytext = '<w:meta:description />';
digg_media = 'news';
digg_topic = 'tech news';
</script>
<script src="http://digg.com/tools/diggthis.js" type="text/javascript"></script> 

Creates a "Digg This" button with the information for the current page.

<w:default_label />

Provides the label for the page, as set in the page admin.

<w:content region="region_name" />

Inserts an editable page region; used in templates only.

<w:content region="Main" />

An editable region named "Main" will be inserted at this point in the HTML.

<w:content region="page-js" editable="false" />

A region named "page-js" will be inserted at this point in the HTML. This would typically be used in the head section of a template. The editable="false" option is necessary for regions used for code, rather than content, to keep them from getting wrapped in HTML markup. Such regions can be edited only from the page admin.

<w:meta:description />

Provides the description for the current page. By default, it also creates the description meta tag.

<w:meta:description />

Returns a full meta description tag, e.g., <meta name="description" content="Another silly page about cats" />

<w:meta:description tag="false" />

Displays the description as plain text (e.g., "Another silly page about cats")

<w:meta:keywords />

Provides the keywords for the current page. By default, it also creates the keywords meta tag.

<w:meta:keywords />

Returns a full meta keyword tag, e.g., <meta name="keywords" content="cats, kittens, pets" />

<w:meta:keywords tag="false" />

Displays the keywords as plain text (e.g. "cats, kittens, pets")

Page Hierarchy

Accessing page structure information.

<w:children:each >

Iterate through each of the child pages (subpages) of the current page.

<w:parent />

Access the page that is the parent of the current page.

<w:siblings:each>

Iterate through each of the siblings of the current page (other subpages of this page's parent).

<w:if_first>

Include following code if current page is the first in a set of subpages.

<w:if_ancestor_or_self>

Include the following code if the current contextual page is either the currently displayed page, or one of its parents.

<w:if_children>

Include the following code only if the current page has children.

<w:if_last>

Include following code only if current page is the last in a set of subpages.

Item Iterators

Iterators repeat a code block once for each selected item. They are the workhorse for choosing items to display from the database.

<w:kb:item:each condition="any condition">

Iterate through items that meet the specified condition.

<ul>
  <w:kb:item:each type="product" condition="featured == '1' ">
    <li><w:name /></li>
  </w:kb:item:each>
</ul>

Lists all products whose "Featured" checkbox is checked.

<ul>
  <w:kb:item:each category="cats" condition="coat == 'longhair' ">
    <li><w:name /></li>
  </w:kb:item:each>
</ul>

List all the cats with long hair (i.e., whose field with the name "coat" is set to "longhair").

<w:kb:item:each>

Iterate through a set of database items that has been previously set by the context.

<w:kb:category name="Cats">
  <w:kb:item:each>
     <h1><w:name /></h1>
  </w:kb:item:each>
</w:kb:category>

Display the name for each item in the Cats category.


            

<w:kb:item:each filter="current_item">

Iterate through a set of items, excluding the current item on the page. Used for showing related content.

<w:kb:item>
  <w:kb:category:each relative="item">
    <ul>
      <w:kb:item:each category='current' filter='current_item'>
        <li><a href="<w:path url='/item' />"><w:name /></a></li>
      </w:kb:item:each>
    </ul>
  </w:kb:category:each>
</w:kb:item>

This example is for use on an item page to show related items. It iterates through each of the categories to which the current item is assigned, and then lists all of the other items in each of those categories, filtering out the current item.

<w:kb:item:paginate limit="items-per-page">

The same as item:each, except that the results are paginated. See example for details.

<w:kb:item>
  <w:paginate by='name desc' limit='10' start='1' page='auto' type='article'>
    <p><w:pagination_widget /></p>
    <w:each>
      <h2><a href="<w:path url='article' />"><w:name /></a></h2>
      <p><w:description /></p>
    </w:each>
  </w:paginate>
</w:kb:item>

<w:kb:item:comments:each (options)>

Iterate through each of the comments on the current item. See examples for options and field names.

<w:kb:item:comments:each>
  <h2><w:subject /></h2>
  <p>Posted <w:created_at /> by <w:name /></p>
  <p><w:body /></p>
</w:kb:item:comments:each>

Display all the comments for current item, with default options (sorted by date, most recent first).

<w:kb:item:comments:each order="ASC" limit="10">

Display the first 10 comments in ascending date order.

<w:kb:item:comments:each order="DESC" limit="5">

Display the most recent 5 comments in descending date order.

<w:kb:item:iterator_size>

Returns the total size of the current iterator's items count, after any conditions are applied. Note that if you only need the size, and don't need to actually return all the items, iterator_preflight_size is much faster.

<w:if_each_index condition="operator number">

Tests the current loop index using the specified condition. "operator" is a standard conditional comparison, such as ==, >, <, !=

<ul>
  <w:kb:item:each type='article'>
      <li>Article #<w:each_index />: <w:name /></li>
      <w:if_each_index condition="== 5">
          <hr />
      </w:if_each_index>
  </w:kb:item:each>
</ul>

Adds a dividing line after the first five articles.

<w:each_index>

For use inside an "each" iterator, such as w:kb:item:each or w:taxonomy:each; returns the number of the current index, starting at 0 for the first iteration.

<ul>
  <w:kb:item:each type='article'>
      <li>Article #<w:each_index />: <w:name /></li>
  </w:kb:item:each>
</ul>

Lists all the items of type "article" and numbers them sequentially.

<w:kb:item:iterator_preflight_size />

Pass in the same attributes you would use in kb:item:each and this statement will return how many items would be returned if you did the actual iteration.

Assets (Images & other files)

<w:assets:each taxonomy="tax:term">

Iterate through all of the assets that are assigned to the specified taxonomy term. See examples for options.

<w:assets:each taxonomy="Animals:Cats">
  <img src="<w:path />">
</w:assets:each>

Displays all the images assigned to the "Cats" term in the "Animals" taxonomy.

<w:assets:each taxonomy="Animals:Cats" descend="true">
  <img src="<w:path />">
</w:assets:each>

Displays all the images assigned to the "Cats" term, or to any child term of Cats.

<w:kb:item:icon rendition='thumb' />

Access the icon associated with the current item. Returns the path to the image file, optionally in the specified rendition.

<w:asset name="/filename.jpg" rendition="rendition_name" />

Provides the path to the image file specified, in the size specified by the rendition option if there are multiple renditions.

<w:asset name="/house.jpg" rendition="medium" />

Displays the "medium" rendition of the image "house.jpg". Note that for this to work, the "Create Thumbnails" option must have been selected when the image was uploaded, and in the Config Setting image.thumbnail.settings there must be a rendition defined named "medium".

<w:assets:each tag="tagname">

Iterate through each of the asset files (typically images) that match the specified tag (if any).

<w:assets:each tag="cat">
  <img src="<w:path />" >
</w:assets:each>

Displays all of the assets to which the tag "cat" has been applied.

<w:assets:each tag="var[w:kb:item:tag]">

Iterate through all of the assets tagged with the same tag as the current item. The "var[w:kb:item:tag]" syntax is a workaround needed because WebvantaScript cannot be nested. (This statement only works predictably with items that have only one tag.)

<w:assets:each tag="var[w:kb:item:tag]">
  <img src="<w:path />">
</w:assets:each>

This must be used within a context in which an item has been selected (either on an item page or in an item:each block). It displays all the images with the same tag as the item.

Menu

The menu commands make it easy to automatically produce menus based on the setting in the Page admin screen.

<w:menu>

Iterate through each of the top-level menu items, as set by the Page admin. Typically used to generate main navigation.

<ul>
  <w:menu>
     <w:each>
       <li><a href='<w:url />'><w:label /></a></li>
     </w:each>
  </w:menu>
</ul>

Create an onordered list for a simple navigation menu. See "if_selected" and "if_submenu" examples for more full-featured menu examples.

<w:if_submenu>

If the current menu item has a submenu, include the following code.

<ul id='nav'>
  <w:menu>
        <w:each>
            <li><a href='<w:url />'><w:label /></a>
            <w:if_submenu>
              <ul>
                <w:submenu:each>
                  <li><a href='<w:url />'><w:label /></a></li>
                </w:submenu:each>
              </ul>     
           </w:if_submenu>
           </li>
       </w:each>
  </w:menu>
</ul>

Display a menu and submenu structure using an unordered list.


            

<w:submenu:each>

Iterate through each submenu of the current menu.

<ul id='nav'>
  <w:menu>
        <w:each>
            <li><a href='<w:url />'><w:label /></a>
            <w:if_submenu>
              <ul>
                <w:submenu:each>
                  <li><a href='<w:url />'><w:label /></a></li>
                </w:submenu:each>
              </ul>     
           </w:if_submenu>
           </li>
       </w:each>
  </w:menu>
</ul>

Display a menu and submenu structure using an unordered list.

<w:if_ancestor_or_self>

Use instead of if_selected to add a class to highlight the curent page, if you want the highlight to show for any second-level page that has the corresponding page as its parent.

<w:if_selected>

Used within menu-generation code to highlight the current page. Include the following code if the current page's URL matches that of a particular menu item.

<ul>
  <w:menu>
    <w:each>
      <li><a href='<w:url />' <w:if_selected>class='current'</w:if_selected>><w:label /></a></li>
    </w:each>
  </w:menu>
</ul>


Create the unordered list of the top-level menu items, applying the class "current" to the menu item whose URL matches the currently displayed page.

<w:unless_last_menu >

Use to wrap around divider between menu items, so you don't get a divider after the last one.

<w:label />

Provides the label for a menu item. Must be used in the context of a menu iterator.

Displaying Database Items

Once the desired database items are selected, retrieving information from the various fields is simple.

<w:fieldname format="options" />

Display the contents of a single field for the currently selected database item (as determined by the context).

<ul>
<w:kb:item:each category="Cats">
  <li><w:name /></li>
</w:kb:item:each>
</ul>

Lists the name of each cat.

<w:path url="/item_page" />

Provides the path to the item page for the current item, including item ID and name.

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

Lists all the cat breeds, with the name linked to the breed item page.

<w:escape_html>

Escapes all special characters in the following code, so HTML will be displayed rather than interpreted.

<w:escape_html><w:code_field /><w:escape_html>

If the field named code_field includes HTML or WebvantaScript markup, this will display the markup rather than executing it.

<w:kb:edit>

Marks the code section that is highlighted when hovering to edit a database item in-place.

<w:kb:item:each category='cats' type='breed'>
  <w:kb:edit>
    <p><a href="<w:path url='/breed' />"><w:name /></a></p>
  </w:kb:edit>
  <img src="<w:photo />" alt="<w:name />">
</w:kb:item:each>

Displays a list of cat breeds, linked to their item pages. The edit hover area includes the line of text, but not the photo.

<w:created_at format="format string" />

Displays the date and time at which a database item was created, formatted as you'd like. See article and examples for format string details.

<w:created_at format="%A %B %e, %Y %l:%M %P" />

Displays as: Saturday July 4, 2009 1:32 pm

<w:created_at format="%a %b %e '%y %k:%M" />

Displays as: Sat Jul 4 '09 13:32

<w:created_at format="%m/%e/%Y" />

Displays as: 07/4/2009

<w:seo_keywords />

Displays the meta keywords of the database item.

<w:seo_description />

Displays the meta description of the database item.

<w:seo_title />

Displays the meta page title of the database item.

<w:modified_at format="format string" />

Displays the date and time at which a database item was last modified.

<w:modified_at format="%A %B %e, %Y %l:%M %P" />

Displays as: Saturday July 4, 2009 1:32 pm. See <w:created_at /> for more examples.

<w:published_at format="format string" />

Displays date at which a database item was published.

<w:published_at format="%A %B %e, %Y %l:%M %P" />

Displays as: Saturday July 4, 2009 1:32 pm. See <w:created_at /> for more examples.

Fieldsets & Related Items

<w:get name="name" />

Display a field that is associated with the current item. Note that this is needed only for fields that are not part of the base item (such as fieldsets or related items).


            

<w:for_each in="item_name">

Iterates through each of the associated items in item_name. Use for fieldsets and related items.

<w:for_each in="example">        
  <pre><w:escape_html><w:get name="in.code" /></w:escape_html></pre>
  <p><w:get name="in.description" /></p>
</w:for_each>

This is the code used to display these examples. In the definition of the "cheat sheet" custom item type, we include a fieldset named "example". The "example" fieldset has fields "code" and "description". This code shows the code and the description for each example.

Conditionals

Conditional statements allow you to produce different code depending on the contents of a field.

<w:if_item type="item-type">

Include following code only if the currently selected item is of the indicated type.

<w:if_item type='article'>
  <h1>Article Title: <w:name /></h1>
</w:if_item>

If the current DB item is an article, display "Article Title: " followed by the article's title.

<w:unless_xxxxxxx>

For every "if_xxxxxx" statement, there is a corresponding "unless_xxxxxx" statement. (Note that this is not "else"; you must state the condition, just as in the if statement.)

<w:unless condition="name.blank?>
  <p><w:name /></p>
</w:unless>

Show the name unless it is blank.

<w:unless_comments>
  <p>There are no comments.</p>
</w:unless_comments>

Display this text if there are no comments.

<w:if condition='lunch=="yes" '>
  <p>Lunch is being served</p>
</w:if>
<w:unless condition='lunch=="yes" '>
  <p>Lunch is NOT being served</p>
</w:unless>

Show the first text if the lunch field contains "yes", otherwise show the second text.

<w:if_url matches="regex">

Include following code only if the URL (not including the domain name) matches the specified regular expression.

<w:if_url matches="^/$">
  This is the home page
</w:if_url>

Displays "This is the home page" on the home page only.

<w:if_url matches="about">
  This is an about page
</w:if_url>

Displays "This is an about page" on any page whose URL includes the string "about".

<w:if_comments>

Include following code only if there are comments on the current item.

<w:if condition="name.blank?">

Displays the markup following this statement if the specified field has no contents.

<w:if condition='name.blank?'>
  <p>No name specified</p>
</w:if>

Displays "No name specified" if the name field is blank.

<w:random>

Choose randomly from the supplied options (see example). Note that this is useful only un uncached pages.

<w:random>
  <w:option>First Choice</w:option>
  <w:option>Second Choice</w:option>
  <w:option>Third Choice</w:option>
</w:random>

Displays one of the three choices, at random.

<w:random>
  <w:kb:item:each type='article'>
    <w:option><w:name /></w:option>
  </w:kb:item:each>
</w:random>

Displays the name of a random article.

<w:if_first>

Include following code if current page is the first in a set of subpages.

<w:if condition='fieldname=="text" '>

Displays the markup following this statement only if the contents of the specified field equals the specified text.

<w:if condition="name=='George'">
  <p>His name is George</p>
</w:if>

Displays "His name is George" if the name field of the current item is "George". Note the item context must be set first, and the use of double equal signs for the equality test.

<w:if_self>

Include the following code if the current page context (typically within an iteration loop) matches the current displayed page.

<w:kb:item:if_iterator_preflight_size count="xx">

Includes the following code only if the number of items returned by the iterator would be greater than the count value.

<w:kb:item:if_iterator_preflight_size type='article' taxonomy='animals:dogs' count='10'>
    <p>There are more than 10 articles about dogs!</p>
</w:kb:item:if_iterator_preflight_size>

Assuming a taxonomy "animals" with a term "dogs", and a custom item type "article" that uses this taxonomy, this code displays the message if there are more than 10 articles about dogs.

<w:if condition="fieldname == 1">

Test whether a custom item's checkbox field is checked

<w:if condition="serves-lunch == 1">
  <p>This restaurant serves lunch</p>
</w:if>

Displays "This restaurant serves lunch" if the checkbox field of the current item that has the fieldname "serves-lunch" is checked.

<w:if_children>

Include the following code only if the current page has children.

<w:if_last>

Include following code only if current page is the last in a set of subpages.

<w:if_items category="category">

Include the following code only if there are items of the specified category and the current type. Must be used in an item type context.

Taxonomies

<w:taxonomy name="taxonomy_name:term_name">

Sets the current taxonomy term to the "term_name" term in the "taxonomy_name" taxonomy. Reference in an item iterator using taxonomy="current", or access the taxonomy's name and description with <w:name /> and <w:description />.

<w:taxonomy:each name="taxonomy-name">

Iterate through each of the terms in the taxonomy "taxonomy-name". See article for options.

Test if the current term for taxonomy context is the last one in the iteration.

<w:taxonomy:each:if_first>

Test if the current term for taxonomy context is the first one in the iteration.

<w:taxonomy:if_subterms>

Test to see if current term has any child terms associated with it. Add an attribute count="n" to test for at least n child terms.

<w:taxonomy:if_items type="type_name" count=n>

Test if the current term has more than n items assigned to it of the specified type.

<w:taxonomy:if_items type="type_name, type_name, type_name">

Test if the current term has any items assigned to it with any of the specified types. Add a minus sign in front of a type_name to exclude items of that type.

<w:taxonomy:if_items type="type_name">

Test if the current term has any items assigned to it of the specified type. If the type is not specified, checks for any type.

<w:taxonomy:if_current name='term_name'>

Tests if the current term matches the specified name.

<w:taxonomy:if_term name="term_name">

Tests if the current taxonomy term context matches the specified term name. Note: you can also provide the term ID instead of the name.

<w:taxonomy:if_term>

Tests if there is any taxonomy term context set.

<w:taxonomy:if_root>

Test if current term is a root term (i.e., it has no parent term)

<w:taxonomy:tree name='taxonomy_name' type='html'/>

Show a complete tree of all the terms in a taxonomy. Set type to "json" to get the tree in that format.

<w:description />

Displays the taxonomy term description (must be used in a taxonomy context)

<w:name />

Displays the name of the current taxonomy term (must be used in a taxonomy context)

<w:if_current>

Includes the following code only if the current taxonomy term matches the page's taxonomy term (for use only on category pages)

Snippets & Config Settings

<w:snippet name="snippet_name" />

Provides the contents of the specified snippet.

<w:snippet name="test" />

Snippet "test" contents:

<h1>This is only a test</h1>

Displays <h1>This is only a test</h1>

<w:snippet name="snippet_name">Variable</w:snippet>

With the two-part version of the snippet tag, you can pass any text as a variable to the snippet.

<w:snippet name="headline">Text for headline</w:snippet>

and the snippet "headline":

<h1><w:yield /></h1>

Displays "<h1>Text for headline</h1>". The text between the opening and closing tags can be used in the snippet using "<w:yield />".

<w:yield />

Inserts content in a snippet from the code that invokes the snippet.

Snippet invoked with:

<w:snippet name="headline">Headline Text</snippet>

Inside the snippet:

<h1><w:yield /></h1>

This example snippet returns <h1>Headline Text</h1>

<w:data name="setting_name" />

Provides the value of the specified configuration setting. Useful in CSS and JS files as well as in templates and editable regions.

<w:data name="company_name" />

Provides the value of the config setting "company_name".

<w:data name="company_name" default="No Name Supplied" />

By including a default setting, you can specify a string that is returned if the setting is missing or empty. In this case, if there is no setting for company_name, the statement returns "No Name Supplied".

Comments

<w:comment_count />

Display the number of comments on the current item.

<p><w:comment_count /> comments</p>

Display the number of comments on the current item. Use within an item context.

<w:kb:item:comments:each (options)>

Iterate through each of the comments on the current item. See examples for options and field names.

<w:kb:item:comments:each>
  <h2><w:subject /></h2>
  <p>Posted <w:created_at /> by <w:name /></p>
  <p><w:body /></p>
</w:kb:item:comments:each>

Display all the comments for current item, with default options (sorted by date, most recent first).

<w:kb:item:comments:each order="ASC" limit="10">

Display the first 10 comments in ascending date order.

<w:kb:item:comments:each order="DESC" limit="5">

Display the most recent 5 comments in descending date order.

<w:if_comments>

Include following code only if there are comments on the current item.

Users

<w:account key="domain" />

Provides the domain name for the current account.

Variables

<w:var name="variable-name">value</w:var>

Sets the variable to the specified value.

<w:var name="variable-name" />

Returns the value of the variable "variable-name". Note: in WebvantaScript, use {{variable-name}} to access variables.

Misc

<w:random>

Choose randomly from the supplied options (see example). Note that this is useful only un uncached pages.

<w:random>
  <w:option>First Choice</w:option>
  <w:option>Second Choice</w:option>
  <w:option>Third Choice</w:option>
</w:random>

Displays one of the three choices, at random.

<w:random>
  <w:kb:item:each type='article'>
    <w:option><w:name /></w:option>
  </w:kb:item:each>
</w:random>

Displays the name of a random article.

<w:resource:type />

Displays the cit name of the item. Use in a kb:item:each loop.

<w:comment>

Use to "comment out" WebvantaScript code. (note that commenting out with HTML comments does not work for WebvantaScript.

<w:comment>
  any WebvantaScript here will be ignored
</w:comment>