Formatting Values with Tcl Procedures

When using one of the NPSOBJ instructions insertvalue meta and var, you can have the CMS call a Tcl procedure during the export to modify the result of the NPSOBJ instruction before it is inserted into the output document. Such a Tcl procedure is called a formatter.

The formatter to be applied can be specified by means of a formatter tag in the NPSOBJ instruction, for example:

<npsobj insertvalue="var" name="title" formatter="formatter_procedure_alias" />

A formatter can also be specified in insertvalue dynamiclink instructions. However, link formatters are a special formatter type because the arguments passed to them are different from the ones passed to standard formatters (the latter are usually applied to field values).

The standard formatters are located in the directory share/script/cm/serverCmds. They must have been registered in the export.tclFormatterCommands system configuration entry before they can be used.

The procedure whose alias name is formatter_proc_alias will be called when the NPSOBJ instruction is evaluated. The instruction will be replaced with the value returned by the procedure.

Definition of a Formatter Procedure

A standard formatter procedure can be defined as follows (from version 6.7.1, standard formatters are in the formatter name space):

namespace eval ::formatter {
  proc myFormatter {value type params} {
      return "To myFormatter the value $value, the type $type,\
              and the parameters $params were passed."
  }
}

The CMS passes the following arguments to the procedure, in the order given below:

  • The first argument is the value of the field referenced by name; if the NPSOBJ instruction also contains the format or separator tag attribute then the formatted value will be passed to the formatter procedure.

  • The second argument is the type of the value passed as the first argument. The following rules apply:

    • If the value results in a context list (this is the case for file and link lists such as children or superlinks, but also for parent etc.), the type is list.
    • If the value has be assigned using npsobj modifyVar, the type is html.
    • If the value results in a link instance, the type is link.
    • If the value results in a valid 14-character date string, the type is date.
    • In all other cases the type string.

  • All other tag attributes and their values (including name but except insertvalue, formatter, format and separator) are passed as a list to the procedure as the third argument; the list contains the tag attribute names and the tag attribute values as name-value pairs.

CMS Fiona includes the formatter procedures described below. The names given are the alias names that can be specified in the NPSOBJ instruction as the value of the formatter attribute.

formatBlobLength

Task

Returns file sizes in a human-readable form. The result is a number as small as possible to which the appropriate unit of measurement (KByte, MByte etc.) has been appended.

Parameters (from version 6.7.1)

  • useBinaryPrefix: A boolean value (true or false) that determines the prefix type of the measurement unit. If this value is true, the file size (Bytes) is divided by 1024, and binary prefixes (Ki, Mi, Gi, Ti) will be used. If the value is false or has not been specified, the divisor is 1000, and SI prefixes (K, M, G, T) are used.

  • maxSteps: specifies the maximum number of divisions to be performed. If, for example, 2 is specified here, values greater than 1000 (or 1024, respectively) M(i)Bytes are still displayed as M(i)Bytes. The default value is 2.

  • precision: Specifies the number of decimal places. The default value is 0.

  • separators: Specifies the characters to be used as thousands separator and as the decimal point character. If only one separator is specified it serves as the decimal point character, and no thousands separator is used. The default value is ’.’.

Examples

<npsobj … formatter="formatBlobLength"/>

This NPSOBJ instruction generates the output 12 MByte from the determined value, 12345678.

The following example generates 12'056.3 KiByte from the input value, 12345678.

<npsobj … formatter="formatBlobLength" useBinaryPrefix="true" maxSteps="1"
          precision="1" separators="'."/>

phpVarDef

Task

This formatter generates a PHP varable definition with which a PHP variable is set to a particular value calculated during the export.

Parameters

  • name: The name of the field whose value is to be determined. This name is also used as the variable name in the generated PHP assignment.

Example

<npsobj insertvalue="var" name="title" formatter="phpVarDef" />

By means of the instruction above the variable assignment <?php $title = "Document Title"; ?> is generated.

formatToRFC822

Task

This formats a date value in accordance with RFC-822. This standard format is used in RSS feeds, for example.

Parameters (from version 6.7.1)

  • withSeconds: A boolean value (yes or no) that determines whether the seconds are output as well. The default is no. Since the standard demands that the seconds are present, 00 is output if this parameter is no.

  • withTwoDigitYear: A boolean value (yes or no) that determines whether two digits are output for the year instead of four. The default setting is no.

Examples

<npsobj … formatter="formatToRFC822"/>

This instruction generates a date in the form 15 Apr 2011 14:36:00 GMT.

The following instruction generates a date in the form 15 Apr 11 14:36:23 GMT.

<npsobj … formatter="formatToRFC822" withSeconds="yes" withTwoDigitYear="yes"/>

dehtmlize

Task

Converts the HTML entities &lt;, &gt;, &quot;, and &amp; into their textual equivalents, <, >, ", and &.

Parameters

This formatter does not have any parameters.

Example

<npsobj … formatter="dehtmlize"/>

The instruction above converts the input value &lt;div&gt;Large &amp; &quot;small&quot;&lt;/div&gt; to <div>Large & "small"</div>.