addedValues Plugin

addedValueMacros.getValue

Syntax

{addedValueMacros.getValue (valueID, attributeOf="messages", groupname="", valueIndex=nil, coercion=nil, entity = nil, prefix="", suffix="")}

• valueID - the shortcut name of a picture to be displayed
• attributeOf (optional, default messages)- the value of the property 'Applies To' for the value to be retrieved
• groupname (optional, default none) - the value of the property 'Group' for the value to be retrieved
• valueIndex (optional) - if supplied, a subscript into a set of multiple values
• coercion (optional) - if supplied, the name of a value coercion script to apply
• entity (optional) - if supplied, a number or shortcut or string to identify which entity to interrogate For
  • messages - a messagenumber or shortcut, defaults to current page.
  • members - a member key, defaults to current member.
  • gems - a gem number or gem shortcut, no default.
  • cornershop - a member key, defaults to basket of current member
• prefix (optional) - if supplied, a string to insert before the value
• suffix (optional) - if supplied, a strign to insert after the value

Examples

Semantics

This macro retrieves a value from an entity, which can be a Manila Discussion group message, a gem, or a membership record or an addedValues entity. the 3 parameters attributeOf, groupname and valueID together identify a variable in the current website. The variable must be defined, even if it is a builtin variable. In this website, msgnum is not defined as a variable, which explains the macro error in the example above. If the variable is a multiple value you must choose which value you want by supplying a "key" in valueindex. Normally a key is a number, but it may be a language code, such as "en", if the multiple language is ordered by language.

The entity which is interrogated to retrieve the value is often implicit in the current page context. For example, if you getValue on message variable it will assume that you want the current message - the message contains the body of the current page - unless told otherwise. To specify another message you may supply a shortcut or a message number. If you call getValue for a member variable, you can specify a member key - typically an email address - as long as you are a Managing Editor. The implied curent context is your own membership record. It is a security violation to attempt to read other members values unless you are a Managing Editor.

If you call getValue for a gem variable, you can specify a gem number if you know it, or a shortcut identifier.

Coercions are scripts which convert a value into a format different from the default. For example, a timestamp variable describes a time and a date, so if you want only a date string you apply a date to string coercion. These are controlled by the server administrator. By default, addedValues installs date, boolean, date.abbrevString and date.shortString as legal coercions.

Suffix and prefix are used to build strings conditionally. If the requested value for an addedValue variable doesn't exist , the default value is returned. Typically that is an empty string. The prefix and suffix are only used if the value is not the empty string.

If you are calling getValue for several variables, you almost certainly should be defining a report and calling the page macro as addedValues is has been designed to do this much more efficiently. It is also easier to layout the look and feel of the page using reports.