Formatting Database Output

When accessing data from the Webvanta Database, using either the built-in item types like Articles or Blogs, or using your own Custom Item Types, it is sometimes useful to apply special formatting on the output. For instance, you might want to strip html tags out of an excerpt field so you can use the plain text for part of your design or you might want a date field to look a certain way.

WebvantaScript tags that access data directly (those that begin with w:kb and are named after the fields in built-in item types) or tags that are used in the context of database iterators, can have the format and truncate attributes added to them. Format transforms the field data into another form and truncate changes the length of the output.

Format Attribute

The format attribute has different options depending on the data type of the field.

Dates

If the data is a Date type such as the built-in created_at, updated_at, or published_at fields or one of your own Date fields (named with a "_date" suffix or otherwise detected to be a Date), you can supply a format string modeled after the Ruby programming language's formatting rules:

 

  %a - The abbreviated weekday name (``Sun'')
  %A - The  full  weekday  name (``Sunday'')
  %b - The abbreviated month name (``Jan'')
  %B - The  full  month  name (``January'')
  %c - The preferred local date and time representation
  %d - Day of the month (01..31)
  %H - Hour of the day, 24-hour clock (00..23)
  %I - Hour of the day, 12-hour clock (01..12)
  %j - Day of the year (001..366)
  %m - Month of the year (01..12)
  %M - Minute of the hour (00..59)
  %p - Meridian indicator (``AM''  or  ``PM'')
  %S - Second of the minute (00..60)
  %U - Week  number  of the current year,
          starting with the first Sunday as the first
          day of the first week (00..53)
  %W - Week  number  of the current year,
          starting with the first Monday as the first
          day of the first week (00..53)
  %w - Day of the week (Sunday is 0, 0..6)
  %x - Preferred representation for the date alone, no time
  %X - Preferred representation for the time alone, no date
  %y - Year without a century (00..99)
  %Y - Year with century
  %Z - Time zone name
  %% - Literal ``%'' character
For example, a format of "%m/%d/%Y" would yield "04/09/2003".
You can also use the special format "time_ago" which will change the date information into an English string expressing the time relative to now (e.g. "3 days ago").

Strings

If the data type is not a Date, then it is treated as a string of characters. The following options are available on strings:

singularize       - Make the final word singular
pluralize         - Make the final word plural
titleize          - Capitalizes all words and cleans up certain characters
downcase          - Converts string to lower case
upcase            - Converts string to upper case
html_escape_once  - Encodes angle brackets and ampersands without re-encoding entities (&)
html_escape       - Encodes angle brackets and ampersands, re-encoding entities (& becomes &)
strip_tags        - Removes all HTML-like open and close tags
uri_encode        - Encoding suitable for URLs (e.g. space becomes %20)
br                - Convert all newline characters to <br /> tags

For example:

<w:kb:item:each category="current">
  <h1><w:my_title format="titleize" /></h1>
  <p>
    <w:description format="strip_tags" />
  </p>
</w:kb:item:each>

yields a title case header and a plain text paragraph.

Truncate Attribute

You can reduce the size of a string by truncating it with the truncate attribute. Several options are available:

paragraph   - Attempts to find the first closing tag and cuts there
N words     - Tries to truncate N words, using white space as word separator (e.g. "10 words")
N           - Truncates after N characters, regardless of character

For example:

<w:description format="strip_tags" truncate="20 words"/>

would remove HTML mark-up, then attempt to take the first 20 words of the description field.

Have more questions? Submit a request

2 Comments

  • 0
    Avatar
    Michael Slater

    We've added another formatting option that is especially useful on fields that contain URLs: strip_protocol.

    This is especially useful on the default URL field, which will automatically add the http:// protocol if you don't enter anything. So if, for example, you enter www.webvanta.com in the URL field, what gets stored is http://www.webvanta.com, so you can write code such as:

    <a href="<w:url />">Go to the site</a>

    This can be annoying, however, if you want to display the URL. For example, you might want to use something like this to both show the URL and make it clickable:

    <a href="<w:url />"><w:url /></a>

    But this will display http://www.webvanta.com, when what you probably want is simply www.webvanta.com.

    The strip_protocol format option fixes this for you. Just write:

    <a href="<w:url />"><w:url format="strip_protocol" /></a>

    and you'll get www.webvanta.com, linked to http://www.webvanta.com

  • 0
    Avatar
    Charity

    is there a way to truncate a field to just get the first letter.  so truncate="1" AND without the ...?

    right now i do that and i get the first three characters with a ...

Please sign in to leave a comment.
Powered by Zendesk