# _global_ | Antville 1.4 API Reference

Documentation generator: JsDoc Toolkit 2.4.0
Template: Codeview 1.2
Generated on: 2012-4-22 10:17

# Built-In Namespace _global_

Field Summary
Field Attributes | Field Name and Description
--- | ---
| html An instance of Helma’s HTML rendering module.
| lessParser An instance of the LESS parser.
<constant> | NAMEPATTERN Regular Expression according to Jala’s HopObject.getAccessName().
| rome A collection of Java classes and namespaces required for parsing and generating RSS.
<constant> | SQLDATEFORMAT The date format used in SQL queries and commands.

## Method Summary

Method Attributes | Method Name and Description
--- | ---
| age_filter(value, param) Helma macro filter wrapping the Date#getAge method.
| breadcrumbs_macro(param, delimiter) Renders a breadcrumbs navigation from the current HopObject path.
| cgettext(key, context) This method is useful for disambiguation of messages (single words most of the time) that have different meanings depending on the context.
| clip_filter(input, param, limit, clipping, delimiter) Macro filter for clipping output.
| default_filter(value, param, defaultValue) A simple Helma macro filter returning one of two possible values depending on which one is truthy.
| defineConstants(ctor) Helper method to simultaneously define constants and a corresponding array of localized display names.
| disableMacro(ctor, name) Disables a macro with the idle() function.
| file_macro(param, id, mode) Renders the URL or an arbitrary skin of a file.
| fixRssText(rss) Replaces elements in a string with elements to fix RSS output which is not capable of displaying images.
| format_filter(value, param, pattern, type) Helma macro filter wrapping the global formatting methods.
| formatDate(date, format) Formats a date according to a formatting string and the site’s locale and time zone.
| formatNumber(number, pattern) Formats a number according to a pattern and the site’s locale setting.
| getLocale(language) Retrieves the locale object from a language string.
| getLocales(language) Creates an array of all available Java locales sorted by their names.
| gettext_macro(param, text) Helma macro wrapper for the gettext() method.
| getTimeZones(language) This method returns an array of structs providing two properties each: `value` – a unique time zone ID `display` – a (more) user-friendly string Although Java is great in providing all time zones one can imagine, this vast amount of choices fails to support easy time zone selection.
| idle() Shortcut for a function with empty body.
| if_macro(param, firstValue, _is_, secondValue, _then_, firstResult, _else_, secondResult) Renders a string depending on the comparison of two values.
| image_macro(param, id, mode) Renders the URL, a thumbnail or an HTML element of an image.
| injectXslDeclaration(xml) Injects the XSLT stylesheet declaration into an XML string until Mozilla developers will have mercy.
| link_filter(text, param, url) Helma macro filter wrapping the renderLink method.
| link_macro() Renders a link.
| list_macro(param, id, limit) The “swiss army knife” list macro.
| listItemFlag_macro(param, str) Renders a string vertically in the global listItemFlag skin.
| markgettext_macro(param, singular, plural) Helma macro wrapper for the markgettext() method.
| ngettext_macro(param, singular, plural) Helma macro wrapper for the ngettext() method.
| nightly() The nightly scheduler.
| now_macro(param, format) Renders the current date and time.
| onStart() The startup handler Helma is calling automatically shortly after the application has started.
| onStop() This handler is called by Helma automatically before the application is stopped.
| pluralize(singular) Transforms an english singular form of a noun into its plural form.
| poll_macro(param, id, mode) Renders the URL, a link or the visual representation of a poll.
| quote(str) Surrounds a string by programmer quotes (").
| random_macro(param, type, mode) Renders either a skin or the URL of a random site, story or image.
| renderLink(param, url, text, handler) Renders an HTML element from a URL or HopObject.
| renderList(collection, funcOrSkin, itemsPerPage, pageIdx) Renders an HTML list from a HopObject collection or an array.
| renderPager(collectionOrSize, url, itemsPerPage, pageIdx) Renders the page navigation for a collection of HopObjects.
| scheduler() Helma’s built-in main scheduler function.
| sendMail(recipient, subject, body, options) General mail sending function.
| singularize(plural) Transforms an english plural form of a noun into its singular form.
| skin_macro(param, name) Renders a skin from within a skin.
| story_macro(param, id, mode) Renders the URL of, a link to or an arbitrary skin of a story.
| user_macro() Helper macro for checking if a user session is authenticated (logged in).
| validateEmail(str) Validates if a string is suitable for e-mail messaging.
| validateUrl(str) Validates if a string is suitable for requesting a URL.
| value_macro(param, name, value) Defines and renders a value.
| version_macro(param, type) Renders the Antville version string.
| wait(millis) Halts the execution of the thread for the specified amount of milliseconds.

## Field Detail

{helma.Html} html
An instance of Helma’s HTML rendering module.
Defined in: Global.js.
{less.Parser} lessParser
An instance of the LESS parser.
Defined in: Global.js.
<constant> {RegExp} NAMEPATTERN
Regular Expression according to Jala’s HopObject.getAccessName().
Defined in: Global.js.
{Object} rome
A collection of Java classes and namespaces required for parsing and generating RSS.
Defined in: Global.js.
<constant> {String} SQLDATEFORMAT
The date format used in SQL queries and commands.
Defined in: Global.js.

## Method Detail

- {String} age_filter(value, param)
  Helma macro filter wrapping the Date#getAge method.
  Defined in: Global.js.
  Parameters:
  {Date} value
    The original date.
  {Object} param
    The default Helma macro parameter object.
  Returns:
    {String} The resulting age string of the original date.
  See:
    Date#getAge
- Renders a breadcrumbs navigation from the current HopObject path.
  Defined in: Global.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object
  {String} delimiter Optional, Default: ' : '
    The string visually separating two navigation items
- {String} cgettext(key, context)
  This method is useful for disambiguation of messages (single words most of the time) that have different meanings depending on the context. Example: comment – the verb "to comment" vs the noun "a comment".
  Defined in: i18n.js.

      cgettext('comment', 'verb')

  Parameters:
  {Object} key
    The message ID.
  {Object} context
    The context of the message.
  Returns:
    {String}
- {String} clip_filter(input, param, limit, clipping, delimiter)
  Macro filter for clipping output.
  Defined in: Global.js.
  Parameters:
  {String} input
    The original input.
  {Object} param
    The default Helma macro parameter object.
  {Number} limit Optional, Default: 20
    The maximum amount of text parts to be displayed.
  {String} clipping Optional, Default: '...'
    The replacement for the clipped portions of the text.
  {String} delimiter Optional, Default: '\\s'
    The regular expression string used to split the text into parts.
  Returns:
    {String} The clipped result.
- {Object} default_filter(value, param, defaultValue)
  A simple Helma macro filter returning one of two possible values depending on which one is truthy.
  Defined in: Global.js.
  Parameters:
  {Object} value
    The original (desired) value.
  {Object} param
    The default Helma macro parameter object.
  {Object} defaultValue
    The fallback value for use if the original value should be untruthy.
  Returns:
    {Object} The value argument if truthy, the defaultValue argument otherwise.
- {Function} defineConstants(ctor)
  Helper method to simultaneously define constants and a corresponding array of localized display names.
  Defined in: Global.js.
  Parameters:
  {HopObject} ctor
    The desired prototype constructor the constants should be defined for.
  Returns:
    {Function}
- {Function} disableMacro(ctor, name)
  Disables a macro with the idle() function.
  Defined in: Global.js.
  Parameters:
  {HopObject} ctor
    The prototype constructor the macro is defined for
  {String} name
    The macro’s name
  Returns:
    {Function}
  See:
    idle
- file_macro(param, id, mode)
  Renders the URL or an arbitrary skin of a file.
  Defined in: Global.js.

      <% file 1810 url %> URL of file #1810
      <% file blog/text.pdf skin=preview %> File in site “blog” using preview skin
      <% file /image.raw %> Static file of root site

  Parameters:
  {Object} param
    The default Helma macro parameter object
  {String} param.skin Optional, Default: 'main'
    The name of a file skin
  {String} id
    The id or path of the desired file
  {String} mode Optional
    Currently only possible value is 'url'
- {String} fixRssText(rss)
  Replaces elements in a string with elements to fix RSS output which is not capable of displaying images.
  Defined in: Global.js.
  Parameters:
  {String} rss
    The original RSS output.
  Returns:
    {String} The transformed RSS output.
- {String} format_filter(value, param, pattern, type)
  Helma macro filter wrapping the global formatting methods.
  Defined in: Global.js.
  Parameters:
  {Object} value
    The original value.
  {Object} param
    The default Helma macro parameter object.
  {String} pattern
    A formatting pattern suitable for the formatting method.
  {String} type Optional
    Deprecated.
  Returns:
    {String} The formatted string.
  See:
    formatNumber
    formatDate
- {String} formatDate(date, format)
  Formats a date according to a formatting string and the site’s locale and time zone.
  Defined in: Global.js.
  Parameters:
  {Date} date
    The original date.
  {String} format Optional, Default: "full"
    The formatting string. Either a Java SimpleDateFormat pattern//docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html or of “short”, “medium”, “long”, “full”, “date”, “time”, “iso” or “text”.
  Returns:
    {String} The formatted date string.
- {String} formatNumber(number, pattern)
  Formats a number according to a pattern and the site’s locale setting.
  Defined in: Global.js.
  Parameters:
  {Number} number
    The original number.
  {String} pattern
    The formatting pattern.
  Returns:
    {String} The formatted number string.
- {java.util.Locale} getLocale(language)
  Retrieves the locale object from a language string.
  Defined in: Global.js.
  Parameters:
  {String} language
    The name of the language.
  Returns:
    {java.util.Locale} The corresponding locale object.
- {Object[]} getLocales(language)
  Creates an array of all available Java locales sorted by their names.
  Defined in: Global.js.
  Parameters:
  {String} language
    The optional language of the locales
  Returns:
    {Object[]} A sorted array containing the corresponding locales
- {String} gettext_macro(param, text)
  Helma macro wrapper for the gettext() method.
  Defined in: i18n.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object.
  {String} text
    The text used as message ID.
  Returns:
    {String} Either the translated or the original text.
  See:
    jala.i18n.gettext
- {Object[]} getTimeZones(language)
  This method returns an array of structs providing two properties each: `value` – a unique time zone ID `display` – a (more) user-friendly string Although Java is great in providing all time zones one can imagine, this vast amount of choices fails to support easy time zone selection. Furthermore, the L10n features of the java.util.TimeZone class are insufficient as they do only translate the generic string returned by the getDisplayName() method (e.g. Central European Time), not the more usable time zone IDs (e.g. Europe/Vienna). Thus, time zone selection in Antville is rather limited.
  Defined in: Global.js.
  Parameters:
  {String} language
  Returns:
    {Object[]} A sorted array containing the corresponding timezones
- idle()
  Shortcut for a function with empty body. Used e.g. in the disableMacro() method.
  Defined in: Global.js.
  See:
    disableMacro
- {String} if_macro(param, firstValue, _is_, secondValue, _then_, firstResult, _else_, secondResult)
  Renders a string depending on the comparison of two values. If the first value equals the second value, the first result will be returned; the second result otherwise.
  Defined in: Global.js.

      <% if <% macro %> is value then <% yes suffix=! %> else 'no :(' %>;
      Note that any value or result can be a macro, too. Thus, this can be used as
      a simple implementation of an if-then-else statement by using Helma macros only.

  Parameters:
  {Object} param
    The default Helma macro parameter object
  {String} firstValue
    The first value
  {String} _is_
    Syntactic sugar; should be "is" for legibility
  {String} secondValue
    The second value
  {String} _then_
    Syntactic sugar; should be "then" for legibility
  {String} firstResult
    The first result, ie. the value that will be returned if the first value equals the second one
  {String} _else_
    Syntactic sugar; should be "else" for legibility
  {String} secondResult
    The second result, ie. the value that will be returned if the first value does not equal the second one
  Returns:
    {String} The resulting value
- image_macro(param, id, mode)
  Renders the URL, a thumbnail or an HTML element of an image.
  Defined in: Global.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object
  {String} id
    The id or path of the desired image
  {String} mode Optional
    Either of 'url' or 'thumbnail'
  See:
    Image#thumbnail_macro
    Image#render_macro
- {String} injectXslDeclaration(xml)
  Injects the XSLT stylesheet declaration into an XML string until Mozilla developers will have mercy.
  Defined in: Global.js.
  Parameters:
  {String} xml
    An XML string
  Returns:
    {String} An XML string containing the XSLT stylesheet declaration
- {String} link_filter(text, param, url)
  Helma macro filter wrapping the renderLink method.
  Defined in: Global.js.
  Parameters:
  {String} text
    The link text.
  {String} param
    The default Helma macro parameter object.
  {Object} url Optional, Default: text
    The link URL.
  Returns:
    {String} The rendered link element
  See:
    renderLink
- {String} link_macro()
  Renders a link.
  Defined in: Global.js.
  Returns:
    {String} The rendered HTML link element
  See:
    renderLink
- list_macro(param, id, limit)
  The “swiss army knife” list macro. Lists collections of HopObjects. There is hardly a thing it cannot do… but it’s kind of messy, though.
  Defined in: Global.js.

      <% list sites %>
      <% list updates 10 %>
      <% list blog/comments %>
      <% list featured skin=promotion %>
      <% list images %>
      <% list postings %>
      <% list stories %>
      <% list tags %>

  Parameters:
  {Object} param
    The default Helma macro parameter object
  {String} param.skin Optional, Default: preview
    The name of a skin suitable for the collection
  {String} id
    The identifier of the desired collection
  {Number} limit Optional, Default: 25
    The maximum amount of items listed
- listItemFlag_macro(param, str)
  Renders a string vertically in the global listItemFlag skin.
  Defined in: Global.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object.
  {String} str
    The string to be rendered.
- markgettext_macro(param, singular, plural)
  Helma macro wrapper for the markgettext() method.
  Defined in: i18n.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object.
  {Object} singular
    The text used as the singular message ID.
  {Object} plural
    The text used as the plural message ID.
  See:
    jala.i18n.markgettext
- ngettext_macro(param, singular, plural)
  Helma macro wrapper for the ngettext() method.
  Defined in: i18n.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object.
  {String} singular
    The text used as the singular message ID.
  {String} plural
    The text used as the plural message ID.
  Returns:
    String Either the translated or the original string.
  See:
    jala.i18n.ngettext
- nightly()
  The nightly scheduler. This method is called according to the cron settings in app.properties.
  Defined in: Global.js.
- {String} now_macro(param, format)
  Renders the current date and time.
  Defined in: Global.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object
  {String} format Optional
    A date format string
  Returns:
    {String} The formatted current date string
  See:
    formatDate
- onStart()
  The startup handler Helma is calling automatically shortly after the application has started.
  Defined in: Global.js.
- onStop()
  This handler is called by Helma automatically before the application is stopped.
  Defined in: Global.js.
- {String} pluralize(singular)
  Transforms an english singular form of a noun into its plural form.
  Defined in: Global.js.
  Parameters:
  {String} singular
    The noun in singular form.
  Returns:
    {String} The english plural form of the original input.
- poll_macro(param, id, mode)
  Renders the URL, a link or the visual representation of a poll.
  Defined in: Global.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object
  {String} id
    The id or path of the desired poll
  {String} mode
    Either of 'url' or 'link'
- {String} quote(str)
  Surrounds a string by programmer quotes (").
  Defined in: Global.js.
  Parameters:
  {String} str
    The original string.
  Returns:
    {String} The processed string.
- random_macro(param, type, mode)
  Renders either a skin or the URL of a random site, story or image. The corresponding story and image collections will be retrieved either from res.handlers.site or from the prefixed “type” argument (e.g. “mySite/story”). Furthermore, both collections can be reduced to a specific tag or gallery, resp.
  Defined in: Global.js.

      <% random site skin=preview %> Renders the preview skin of a random site.
      <% random story tag=essay url %> Renders the URL of a random story tagged with “essay”.
      <% random foo/image gallery=cat %> Renders the default skin of a random image in the gallery “cat“ of the site “foo”.

  Parameters:
  {Object} param
    The default Helma macro parameter object.
  {String} param.skin Optional, Default: "preview"
    The name of the skin to render in default output mode.
  {String} param.tag Optional
    Reduce the story collection to stories with the specified tag.
  {String} param.gallery Optional
    Reduce the image collection to images from the specified gallery.
  {String} type
    The type of object to render. Either of “site”, “story” or “image”. It can be prepended by a site name delimited by a slash: “mySite/image”.
  {String} mode Optional
    Set the output mode. Currently, only “url” is supported.
- renderLink(param, url, text, handler)
  Renders an HTML element from a URL or HopObject.
  Defined in: Global.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object.
  {String} param.title Optional
    An optional link title for use in the “title” attribute.
  {String} url
    A complete or partial URL string. Optional if “handler” is specified.
  {String} text Optional
    An optional link text.
  {HopObject} handler
    The HopObject used as base URL. Optional if “url” is specified.
  See:
    helma.Html#link
    HopObject#link_macro
- {String} renderList(collection, funcOrSkin, itemsPerPage, pageIdx)
  Renders an HTML list from a HopObject collection or an array.
  Defined in: Global.js.
  Parameters:
  {HopObject|Array} collection
    The original collection of objects.
  {Function|Skin} funcOrSkin
    A skin name or a rendering function.
  {Number} itemsPerPage
    The amount of rendered items per page.
  {Number} pageIdx
    The current page index.
  Returns:
    {String} The rendered list.
- {String} renderPager(collectionOrSize, url, itemsPerPage, pageIdx)
  Renders the page navigation for a collection of HopObjects.
  Defined in: Global.js.
  Parameters:
  {HopObject|Array|Number} collectionOrSize
    A collection or just the size of a collection.
  {String} url
    The base URL for rendering links.
  {Number} itemsPerPage
    The amount of rendered items per page.
  {Number} pageIdx
    The current page index.
  Returns:
    {String} The rendered page navigation.
- {Number} scheduler()
  Helma’s built-in main scheduler function. This method is regularly called by Helma after a defined period of time. The period is either defined by the return value or by the schedulerInterval property in app.properties.
  Defined in: Global.js.
  Returns:
    {Number} The period in milliseconds the scheduler will be called again.
- {Number} sendMail(recipient, subject, body, options)
  General mail sending function. Mails will be queued in app.data.mails.
  Defined in: Global.js.
  Parameters:
  {Object} recipient
    The recipient's email addresses
  {String} subject
    The e-mail's subject
  {String} body
    The body text of the e-mail
  options
  Returns:
    {Number} The status code of the underlying helma.Mail instance
- {String} singularize(plural)
  Transforms an english plural form of a noun into its singular form.
  Defined in: Global.js.
  Parameters:
  {String} plural
    The noun in plural form.
  Returns:
    {String} The english singular form of the original input.
- {String} skin_macro(param, name)
  Renders a skin from within a skin.
  Defined in: Global.js.
  Parameters:
  param
  name
  Returns:
    {String} The rendered skin
  See:
    HopObject#skin_macro
- story_macro(param, id, mode)
  Renders the URL of, a link to or an arbitrary skin of a story.
  Defined in: Global.js.

      <% story 1810 skin=preview %> Story #1810 in preview skin
      <% story blog/1971 url %> URL of the story of site “blog”

  Parameters:
  {Object} param
    The default Helma macro parameter object
  {String} param.skin Optional, Default: 'embed'
    The name of a story skin
  {String} id
    The id or path of the desired story
  {String} mode Optional
    Either of 'url' or 'link'
- {Boolean} user_macro()
  Helper macro for checking if a user session is authenticated (logged in). Returns true if user is logged in, false otherwise.
  Defined in: Global.js.
  Returns:
    {Boolean}
- {String|null} validateEmail(str)
  Validates if a string is suitable for e-mail messaging.
  Defined in: Global.js.
  Parameters:
  {String} str
    The string to be validated.
  Returns:
    {String|null} The e-mail string if valid, null otherwise.
  See:
    String#isEmail
- {String|null} validateUrl(str)
  Validates if a string is suitable for requesting a URL.
  Defined in: Global.js.
  Parameters:
  {String} str
    The string to be validated.
  Returns:
    {String|null} The URL string if valid, null otherwise.
- value_macro(param, name, value)
  Defines and renders a value. This works like a variable that can be set in one skin and rendered in another – which must be rendered later than the one setting the variable.
  Defined in: Global.js.

      <% value foo=bar %> Defines res.meta.values.foo = bar

      <% value foo %> Renders the value of res.meta.value.foo

  Parameters:
  {Object} param
    The default Helma macro parameter object.
  {String} name
    The name of the value.
  {String} value Optional
    The desired value. If no value is given, the current value will be rendered.
- version_macro(param, type)
  Renders the Antville version string.
  Defined in: Global.js.
  Parameters:
  {Object} param
    The default Helma macro parameter object.
  {String} type Optional, Default: 'default'
    The type of version string.
  See:
    Root.VERSION
- wait(millis)
  Halts the execution of the thread for the specified amount of milliseconds. Use only for debugging.
  Defined in: Global.js.
  Parameters:
  {Number} millis
    The amount of milliseconds.