Accessing Database Information

WebvantaScript makes it easy to retrieve information from the database, and to combine the information with your HTML markup to present it exactly how you want.

Typically, you'll want to find all the database items that fit your particular purpose on a given page, put them in some order, and then display them with surrounding HTML markup of your design.

There's two parts to this process:

1. Choose which items you want to retrieve
2. Provide the HTML markup that surrounds each of the fields to be displayed

Choosing Items to Display

To select items from the database, use the following WebvantaScript:

  <w:kb:item:each [search criteria go here]>
    [HTML for each item goes here]
  </w:kb:item:each>

The HTML (or JS) code that you provide will be automatically repeated for every item that meets your search criteria.

Accessing Item Fields

We'll get to the search criteria in a moment, but for now assume you've found a set of items that you want to show.

Each of the item's fields is accessed with <w:fieldname />. You use this markup to access the information from the database, and surround it with whatever HTML you desire. For example:

  <h1><w:name /></h1>
  <h2>By <w:author /></h2>
  <p><w:body /></p>

If you are using a custom item type, note that the fieldnames are the set by the name in the create custom item type form; the label controls only the labels on the form.

Making "Edit Item" Available In-Place

When you have a region that is displaying content from the database, clicking the Edit button for the in-place editor (shown when editing is enabled and you are hovering over an editable region) enables you to easily edit the script that creates the HTML presentation. For a content editor, though, that's not what they're interested in—they want to edit the database contents.

Webvanta supports this "Edit Item" function, which greatly eases content maintenance by non-technical users (and is even handy for designers!). All you need to do is indicate which section of code should be the "hover region", using the WebvantaScript statement <w:kb:edit>. For example, this code makes the item from the previous example editable in this way:

  <w:kb:edit>
    <h1><w:name /></h1>
    <h2>By <w:author /></h2>
    <p><w:body /></p>
  </w:kb:edit>

In this example, we wrapped all of the fields in the w:edit statement; you could choose to wrap only the body field, for example if you wanted more distinct hover areas. Edit item always displays the full database edit form, so all fields can be modified once the button is clicked no matter what fields are set as the hover area.

Selecting Items

Usually, you don't want all the items in the database, which is what <w:kb:item:each> by itself will give you. By adding search conditions, you choose which items are selected.

Suppose, for example, that you want to display all the articles about Cats. You'd use:

<w:kb:items:each type="Articles" category="Cats" by="name">

You can leave out any of the parameters; for example, omit the type setting in the markup above to get all items related to cats, regardless of type.

The type field specifies the item type. Webvanta has a number of built-in item types (e.g., article, blog post, link, event, book), and you can easily create your own custom item types by simply filling in a form ( go to Database > Item Types and click Add Custom Item Type). For custom item types, the type is whatever you enter for the name of the custom item type when you create it.

You can include multiple types, separated by commas, and the search will match any of those types. Add a hyphen before a type name to exclude it from the results. For example:

  <w:kb:item:each type="Articles, Books"> (all articles, and all books)
  <w:kb:item:each type="-Articles"> (all items except articles)

The category is typically used to organize your information by topic. You can use either the exact name of the category, or the category ID (which continues to work even if you later edit the category name)

Choosing the Sort Order

The by field (which has an alias of sort, you can use either name) lets you choose the order of the items. Options are:

• name: alphabetical by name
• date (or created_at): by creation date
• modified_at: by last modified date
• published_at: by publication date
• rating: by editorial rating

If you have a field that has pure numeric values, you can choose numeric instead of alphabetic sorting by adding ";number" after the field name, such as:

<w:kb:item:each name="homes" sort="price;number asc">

You can specify the order as ascending or descending by adding ASC or DESC, respectively, following the field name (separated by a space, as in "rating ASC"). If you do not specify the order, it defaults to descending.

Currently we do not support sorting by multiple fields. There is, however, a built-in behavior that provides a fixed secondary sort:

• If you choose rating as the sort key, then the secondary sort will be by the published_at date, in descending order.
• If you choose any other field as the sort key, then the secondary sort will be by rating, in descending order.

Limiting the Results

If you don't specify a limit, you'll get all the results that match your search criteria. Optionally, just specify the maximum number of items:

    <w:kb:item:each type="Articles" category="Cats" by="Rating ASC" limit="5"> 
  

This example displays the 5 highest-rated articles about cats.

Conditional Code

Sometimes you need to change what is displayed based on what's in a particular field. WebvantaScript provides if and unless statements. Let's look at how to use them by example.

Putting it All Together

Here's our more refined code to show all the articles about cats:

  <w:kb:item:each type="Articles" category="Cats" by="name">
    <h1><w:name /></h1>
    <w:unless condition='author.blank?'>
      <h2>By <w:author /></h2>
    </w:unless>
    <p><w:body /></p>
  </w:kb:item:each>

The ".blank?" test is the most commonly used, but you can also test any field to determine whether it is equal to, or not equal to, a particular value:

  <w:unless condition='author=="Jack London"'>

  <w:unless condition='author!="Jack London"'>

Note the specific syntax, which is a double equal sign for comparison, and the use of single and double quotes.