Formatting Information from the Database

When retrieving data from your database with WebvantaScript, you can often simply use <w:fieldname />. When you are simply displaying the value of a text string, for example, that's all you need.

Often, however, it is useful to format the information in various ways, rather than displaying it directly. The table below shows the numerous formatting options for dates, strings, HTML, URLs, and numbers.

To use any of these formatting options, simply add the format attribute with one of the values shown in the table. For example, <w:price format="number:1.2"> converts numbers to have a decimal two digits from the right.

If you want to apply formatting when you are substituting a variable into a WebvantaScript statement using the {{ name }} syntax, use format_on_sub, as in the following example:

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

The following table shows all of the available format attributes.

Data Type Value Description
Date and Time Date/time format string Allows a date or date/time to be formatted in nearly any way; see Formatting Dates
  time_ago Displays the time as a difference from the current time (e.g., "5 minutes ago")
Strings singularize, pluralize Converts a noun to singular or plural form; attempts to be smart about English usage
  humanize Capitalizes the first word and converts underscores to spaces
  titleize Capitalizes the first letter of each word
  downcase, upcase Convert to all lower-case or all lower-case
  br Convert new-line characters to <br/>
  gsub Replace string content using regular expression
HTML Text html_escape_once Convert all special characters to HTML entities, leaving unmodified any existing entities
  html_escape Convert all special characters, including those in existing entities, to HTML entities
  strip_tags Remove all HTML tags, leaving plain text.
URLs strip_protocol Remove the protocol part of a URL, converting to
  uri_encode Convert a string to a URL-safe encoding.
  pretty_url_encode Convert a string to a prettier URL-safe encoding, in which spaces are converted to dashes instead of %20.
  pretty_url_decode Convert a string from pretty URL encoding to the original string. (Note important limitations; see section below this table.)
Numbers to_i Convert a string to an integer value
  number Adds separator (comma by default) every three digits from right (e.g., 12,000); site.number.thousands.separator specifies comma or period
  number:1.x Adds decimal separator (period by default) x digits from right; site.number.decimal.separator specifies comma or period
  truthiness Returns "false" if value is 0 or blank, otherwise "true"

Pretty URL Encoding and Decoding

pretty_url_encode is a modification of the normal URI encoding. The standard version 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.

Limitations: It is important to be aware that while the pretty URL encoding is indeed prettier, it 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 (/).

Using Regular Expressions to Modify Text Content

You can use the gsub format option to modify string (text) content.

Here's an example that changes the abbreviation "Co." to "Company" in the database field "company_name":

<w:company_name format="gsub('Co\.', 'Company')" />

Note that you must put the entire format parameter in quotes, so you need to use single quotes to wrap each of gsub parameters (assuming you use double quotes to wrap the entire format string.

Also, note that the first parameter is a regular expression, so special characters (such as period) must be escaped with a backslash.

Related Articles