Section - 2 : Snippets
A snippet is a programming term for a small file of re-usable text or source logic written to allow substitution of variables. Snippets are generally small files written with a text editor or program source code editors.
Mobile output processing begins by loading a “master” snippet that directs the output process. Each object included by the output generation has a default snippet that is named for that particular object type. For example, text area uses "textarea.xml" as the default snippet name. Fields use “field.xml” as the default snippet name. Sections use “section.xml” as the default snippet name. See the table below for a full list.
While the Documaker Mobile installer includes both xml and json snippets, Documaker Mobile assumes snippet files have an .xml extension. If you will be using snippets with a .json extension to produce mobile output, set the SnippetExt to .json in the <PrtType:MRO> configuration group as shown below:
<PRTTYPE:MRO>
SnippetExt = .JSON
The following table identifies the default snippet name associated with objects that might be included in mobile responsive output. All snippet names are required to be lowercase file names.
| Snippet Name (without extension) | Object Type Using That Snippet |
|---|---|
| master | The controlling snippet that drives the process and directs the layout of the responsive output. This snippet is assumed related to the entire document. |
| group | Forms Lists, also know as “Line of Business”, “Form Groups” or references to KEY2 or KEY3 |
| form | Forms (.FOR) |
| page | Pages |
| section | Sections |
| box | Box, line, and shaded areas defined within sections |
| bitmap | Graphic bitmaps and logos |
| textarea | Text Areas |
| stext | Text Labels, also sometimes referred to as “static text”. This object snippet is also used for individual text elements found within text areas. |
| field | Fields that are not barcode or multiline text fields. May also be used for barcode and multiline fields if a specific snippet is not available for those objects. |
| field_barcode | Fields that are barcode type |
| field_textarea | Fields that are multiline text fields |
| barcode | Barcodes |
| font | Fonts |
| note | Note objects where the type is sticky note |
| note_bookmark - bookmark notes | |
| note_memo - note objects where the type is memo | |
| mtformat | End of paragraph marks found within textareas |
| chart | Charts Note: The axis values will be output only for chart text labels that have names beginning with POINTAXIS or SCALEAXIS. The label's text value should be set to the content you wish to display on the chart. |
| vector | Vectors |
| signature | Signatures |
| table | Tables (Note that components within a table will reference other object snippets like textarea and stext). |
Default Snippets
By default, the Documaker mobile solution provides object level snippets and stylesheets for rendering content for mobile use. However, these resources are meant to only provide a generic mobile enabled solution that is not designed for use as final output within a company's mobile strategy. It is up to the company to build upon the snippets provided to achieve the look and feel desired for mobile documents.
Overriding Snippets with Custom Definitions
To support the use of non-default snippets, the Documaker author can directly update the default snippets provided, thus changing the snippets used for all documents, or they can override the default definitions on a document per document basis, using context tags. See the Customizing Mobile Output with Context Tag and Omit Properties topic for more information on using context tags.
Snippet Contents
Documaker's Mobile installer includes both XML and JSON snippets. MRO assumes snippet files have an extension of .xml. Should you want to produce JSON mobile output, set the SnippetExt setting to .json in the <PrtType: MRO> configuration group. However, exactly what a snippet contains depends on what type of object is referenced by the snippet, the intended output format, and the desired behavior. Documaker does not validate the content of the snippet, it only looks for variable replacement tags to replace with content from the transaction being processed. For more information on the variable replacements or supported keywords, see the topic Understanding Snippet Keywords.
Snippet Location
All snippets used by a given MRL will be found in the same location defined within the MasterResource INI group option MROLIB, as shown here:
<MasterResource>
MROLIB=
MasterResouce settings option can be redirected to the CONFIG group that controls other MRL options.
Master Snippet
Each mobile generation begins by looking for the master snippet. The master can be thought of as the shell that drives the mobile transformation process. The master snippet name for XML snippets is 'master.xml'. The master snippet name for JSON snippets is 'master.json'.
The master snippet must also be located in the location defined by the MROLIB= option within the MasterResource group – as are all other snippets.
Information will be presented to show that you can have multiple master snippets to drive the mobile transformation process for different situations. See Global Context Tag for more information.
Object Specific Snippets
The default snippets provided with Documaker Mobile demonstrate a hierarchy of object processing to help you understand the sequence of processing content that follows from the master snippet. The following diagram shows the layers of objects within the system as it relates to the provided snippets.
In the default output there is a DocSet element which serves as the document root and contains Groups. Groups have Forms. Forms have Pages. Pages have Sections. Sections have low level contents that include all the publishing objects in the section in reading order including text content, field content, images, tables, charts and all other publishing objects available.
In the default snippets the Page layer is omitted. If you want to have pages in your output, you can change your Form snippet to list Pages instead of Sections. This will cause Pages to be inserted into your Mobile output.
Customizing Mobile Output with Context Tag and Omit Properties
An object property can be used to define a tag that will be appended to the default snippet name for the object, generating a “custom” named snippet for that particular object.
Within Documaker Studio and the Microsoft Word Add-In, each object that may be included in mobile output has two new properties available for use: Omit and Context.
The Context property is used to define a value you wish to append to the default snippet name and thereby generate a “custom” snippet name to use for this particular object. For example, the field object by default will look for a snippet with the name “field.xml”. If you associated a tag of “green” on a particular field object, this would expect to locate a snippet with the name “field_green.xml”. Any field not specifying a context tag will continue to look for the normal “field.xml”. See details below on Snippet Search Behavior for more information.
The Omit check box is used to suppress a particular object from being included in the responsive output. Depending upon the exact nature of the desired output, it may not be necessary to include an object. For instance, when generating a responsive HTML output, you may wish to suppress certain boxes or large graphics that may not format in the desired output or cause that output to become overly large; therefore the object's Omit property can be enabled. In addition, Omit might be used to suppress certain sensitive field or text information that you don't want to include when output in a given format might be considered a security risk in a mobile landscape. Omitting an object does not omit embedded objects within that object.For example, omitting a text area does not omit embedded fields, boxes or graphics within the text area. You must also omit the field, box or graphic itself.
Application-wide Context Tags For User Selection
A predefined list of context tags can be defined for user selection within Documaker Studio and the Word Add-In. These are defined and maintained in the Application Definition (BDF).
When Oracle Documaker Mobile is installed in your development environment, a new tab appears in the same area as the Category and Transactions tabs. This tab is called Context Tags.
The Description property of the Context option is simply to associate some descriptive text to assist the Document Author in choosing the correct context. Note, since the tag name ultimately becomes part of the file name for the snippet, the Context tag name follows file naming restrictions. Therefore, the characters : / \ > < ? * cannot be used in the name field. Characters with ASCII scan codes lower than 32 or higher than 127 are also not permitted. Uppercase letters will be lowercased. A name with all spaces is not valid. The Context Tag list simply holds those tags that you would like the Document Author to be able to select when creating content. It is possible to assign security restrictions to users that will force selection from this list or to allow users to create a custom tag not defined in the Application Definition.
The application defined Context Tag list is also included in the Workspace Definition file Studio creates and that is consumed by Word Add-in users. See below for an example of the file contents.
Security option for choosing from available tags
A security setting determines if a user is required to select from the application defined context tag list. This is similar to other security attributes that determine whether a user is limited to choosing predefined fields, triggers, and templates. The context tag restriction attribute can be found on the User Rights page of the Security Wizard.
When checked, that user is only allowed to select from the predefined tag list specified by the application definition. Users without this rights restriction are allowed to define a mobile context tag not defined within the application list. The default restriction attribute for a new user is not selected, but if the user is created based on another user, this property will be carried forward.
In the drop-down selection box the user sees the available tags as well as the descriptions defined for each. Only the selected tag name appears in the actual control after selection. The description is not maintained in the individual object property.
Snippet Search Behavior
As mentioned, each object type that can be included in mobile responsive output has a default snippet named for that type of object. As identified in the previous section, you may customize a snippet for a given object for any reason where the output for that particular object should be different than other similar objects of the same 'type' - i.e. fields, sections, forms. The custom snippet is named starting with default snippet name for that object and followed with an underscore and appended with additional text.
When a snippet name contains underscores, the mobile output generation will attempt multiple searches looking first for more highly qualified snippet names and working back to less qualified snippet names until a snippet with that name is found. For instance, in the snippet name reference table (shown earlier) you will find that fields of a barcode type expect to use the default snippet name "field_barcode.xml". If a file with that name is not found, the search will continue and look for "field.xml". A new search attempt will occur at each underscore, reversing through the names until a matching snippet file is found.
For example, if starting with a snippet name of "object_one_two_three_four.xml", the following names will be searched for order until one was found.
- object_one_two_three_four.xml
- object_one_two_three.xml
- object_one_two.xml
- object_one.xml
- object.xml
This is an important behavior to note since objects allow for the definition of a mobile tag to be appended to the names. If the custom snippet name is not found, the system will then continue parsing backwards until eventually the default snippet name is used.
Remember a previous example where a field defined a mobile context tag "green", when that particular field object is output the first attempt will be to locate a snippet with the name "field_green.xml". If that is not found, then the name "field.xml" (the default for fields) will be used. If that field happened to have been a barcode type, the first search would have been to look for "field_barcode_green.xml". If that file is not found, then "field_barcode.xml" will be next. If that is not found, then simply "field.xml" will be used.
If a snippet of a given name is not located, this is not considered an error. As a default, a warning message will be output that takes the following form where the name of the missing snippet and its extension is listed as shown:
Unable to open file snippetname.ext
This warning message causes no harm and will generally only be output once per run. A subsequent reference to the same file will simply shortcut to the name that was eventually used for that object snippet request. You can suppress the output messages if desired by using this INI option within the Mobile options group defining the responsive output.
<PRTTYPE:MRO>
Verbose = No
As mentioned, the default is Yes, and messages will be generated when snippets of a given name are not found.
Global Context Tag
It is possible to assign a global context tag to a document on its application definition. When a global context tag is defined, all objects will first look for the associated snippet with the global tag appended to the name, just as if the context tag had been set on each and every instance of an object being evaluated.
For example, if a global context tag "claim" is assigned at the transaction level, then a search for a field's snippet will first look for "field_claim.xml". This occurs even through the field did not specify a mobile context.
In fact, if the field does have a custom mobile context tag defined, that tag is still added into the initial search name with the global tag appended at the end. Returning to an earlier example where a field defines a mobile tag "green", assume that field is part of a transaction that defines a global tag "claim". The first snippet name searched for this field will be "field_green_claim.xml". (Remember, that snippet searches iterate by shortening the name at each underscore until a snippet is found.)
This global context tag feature is to be used in situations where it is desirable to generate customized output for a given transactions.
This different output can start with the master snippet. The global context tag defined for a document will also apply to determining the master snippet name. This means if a transaction has "claim" assigned as the global context tag, the initial master snippet searched for will be "master_claim.xml". (Just as any other snippet search, if this name is not found, then the "master.xml" will be searched next.)
Since the master snippet drives the start of the mobile generation, having a global tag modify the master snippet name offers the ability to generate customized by doing things such as referencing different style sheets or other layout resources not used in the normal output case.
Although the global context tag is first appended to all object snippet searches, there is no requirement that you have a custom snippet for every object. The normal snippet search method will continue looking for a snippet by truncating the name at the underscores. You need only define custom snippets for those objects that require custom output for that tag, which very often will just be the master snippet.
Assigning a Global Context Tag to a Transaction Document
A global context tag can be defined for particular lines of business or Key1/Key2 combinations in the application definition (BDF). Within the definition of the Forms Lists options for a Key1/Key2 combination, you will see an additional option in the Mobile properties. The Global Context Tag is not the same as the Context tag defined for any other object - seen here just above this option.
Remember, a Mobile Context tag definition only applies to the given object at run time. Conversely a Global Context Tag defines a tag that will be applied to every object, including the master snippet, when generating output for the entire transaction.
The Global Context Tag is associated with the document via the normal triggering or key selection process. The first Forms List assigned to the transaction will have its Global Context Tag setup to the document level.
If multiple Forms Lists are included in a transaction document, only the first Forms List definition determines the Global Context Tag for the document.
Alternatively, it is possible to assign a document Global Context Tag without defining the tag within the Forms List options of the Application Definition. Instead, you can use a DAL script to assign or override this document level (Global) tag. You just have to ensure the script is executed prior to the start of mobile responsive output generation.
DAL Functions for Global Context Tag Support
Two DAL functions are available that determine or assign the document Global Context Tag. These new functions appear under the Miscellaneous grouping in the Trigger Manager Keyword List.
GetGlobalMROTag() - This function can be used to obtain the value of the Global Context Tag that is assigned to the transaction. There are no parameters expected. Usage in a script must pick up the return value or else a runtime syntax error will be generated.
Example:
Tag = GetGlobalMROTag()
If (Tag = "")
// No tag assigned yet
The Global Context Tag determines the initial snippet names used by mobile responsive output (MRO). If a tag is defined, then it is assumed that the transaction will attempt to use specific snippet names before reverting to defaults.
SetGlobalMROTag( tag ) - This function assigns the given parameter string as the Global Context Tag associated with the active transaction document. There is one expected parameter which is assumed to be a string that defines the Global Context Tag to assign.
Example:
SetGlobalMROTag("claim")
Using this function will override any previously assigned Global Context Tag assigned to the document whether assigned implicitly via the triggering process or by previous script assignment. If you pass an empty string to this function, example: Passing an empty string to the SetGlobalMROTag function, for example, SetGlobalMRLTag(""), is the equivalent of removing the documents assigned Global Context Tag and allows the mobile responsive generation to use normal defaults for all snippet references.