Index...
Centrallix Documentation
|
6.8.1.1 Substitute Function
Substitute Function
The substitute() function is used for formatting strings and documents containing fields, such as for form letters, addresses, and more.
The substitute() function takes two string parameters: a format string and an optional object mapping string.
Format String
The format string is a normal string of text that optionally contains fields that will be replaced with data values in the string returned by this function. Here are the field types that can be used:
| Field | Description |
|---|
| [:attrname] | Finds an attribute named attrname in an object in the current scope, or in an object referenced in the mapping string, and inserts it into the returned string. |
| [:object:attrname] | Finds an attribute named attrname within the object object and inserts it into the returned string. If a mapping string is provided, the object name must be listed there. |
All other content in the format string is copied to the returned string exactly as-is.
Object Mapping String
Often, the names of the objects used in the format string need to be "standardized" and may not match the objects in the actual scope within which substitute() is executing. To map the object names in the format string to object names in the current scope, an object mapping string is used.
If the object mapping string is not provided, then any object names in the format string must match object names in the current scope, and there is no restriction on what object names may occur in the format string.
An object mapping string consists of a comma-separated list of object maps:
| Map | Description |
|---|
| object | A simple object name in the map indicates that the object may be used in the format string, and no remapping of the object name will happen. That is, an object of this name in the format string must match an object of this name in the current scope. |
| formatobj=scopeobj | This indicates that an object named scopeobj in the current scope will be made available in the format string as an object named formatobj. |
In all cases, if an object name mapping string is provided, only objects mentioned in the string will be accessible in the format string.
Examples
Let's say we have an object called person in the current scope that contains two attributes: given_name and surname, which have the values "John" and "Smith", respectively, and we have an object called title_info in the current scope that contains one attirbute: titlename which has the value "Mr.". Here are some examples of using substitute() with a simple format string using that data:
substitute("[:given_name] [:surname]")
= "John Smith"
substitute("[:surname], [:given_name]")
= "Smith, John"
substitute("Dear [:given_name] [:surname],")
= "Dear John Smith,"
Using an object map allows us to restrict the use of certain objects:
substitute("[:titlename] [:given_name] [:surname]", "person,title_info")
= "Mr. John Smith"
substitute("[:title_info:titlename] [:person:given_name] [:person:surname]", "person,title_info")
= "Mr. John Smith"
substitute("[:title_info:titlename] [:person:given_name] [:person:surname]", "person")
= error (title_info object not available)
substitute("[:titlename] [:given_name] [:surname]", "person")
= error (titlename not found in any available object)
Finally, using an object map allows us to standardize the object names used in the format string, so that the format string is useful in different contexts with different object names in scope:
substitute("[:t:titlename] [:p:given_name] [:p:surname]", "p=person,t=title_info")
= "Mr. John Smith"
Comments...
(none yet)
Add a Comment...
|
