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 http://www.site.com to www.site.com |
| 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.
