Fragments
(As of 3.1.001.01)
DocOrigin Design and Merge provide a means to create a library of pre-defined form objects that can be placed on a form template. These library objects are called Fragments. A fragment is any DocOrigin template object - a Field, Text Label, Table, Group, Pane, Page - that can be drawn in Design. Fragments are typically created with a preset set of attributes and settings.
In the simplest use of fragments, you select a fragment from one of the libraries and place it on the page. This is an embedded fragment. It just becomes a normal part of your design. It can be edited, moved, modified just as if you had drawn it all yourself. This is more-or-less the equivalent of doing a copy/paste from one form to another.
A second option called Linked Fragments also exists. A Linked fragment is a "read-only" instance of a library fragment. You can position a linked fragment, and give it a new name, but you cannot modify any of its other attributes. Those other attributes are linked to the original library, and only change when the library is changed.
Whenever a template with a linked object is re-loaded in Design, it is automatically updated to the latest version of that fragment in the library. So an update to the original library will automatically be reflected in any template that links to it. A similar mechanism is also available (as an option) in the Merge program (see below). This allows library changes to be reflected automatically in the runtime Merge output.
Note that although the above automatic updates to existing templates by Merge may be a powerful way to make system-wide changes to forms, it should always be used with caution. Proper testing and QA of the changes to production forms is very important. Changes to library fragments can cause unexpected effects. Text labels that originally display correctly might now overflow or overlap other design elements. Font changes may require changes to Merge configurations.
Use of automatic updating of linked fragments in Merge should always be carefully tested before going "Live".
Libraries
Fragment Libraries are essentially normal DocOrigin form files stored in a designated Library folder, but with a file extension of .xatwlib. You can create them and modify them with Design in exactly the same way you work with other designs.
The DocOrigin install comes with some standard fragment libraries which are located in the DocOrigin/DO/Library subfolder. These libraries typically have "Default-" at the front of their name - such as "Default-Zebra.xatwlib" and "Default-Fragments.xatwlib". The Default-Zebra library has a number of barcode formats for Zebra label printer. The Default-Fragments library includes a template for the Auto Email feature of Merge - see Auto Email.
You can of course copy these files and modify them, but you should never save the new files back to this /DO/Library folder as that folder will be replaced whenever you install a newer version of DocOrigin software.
Libraries you create or modify should be stored in the DocOrigin/User/Library folder. (or more correctly $U/Library). These User libraries and will not be affected by any upgrade of the DocOrigin software.
It is recommended that when creating a Fragment Library, you use the Design Notes feature to provide a brief description of each fragment. The Tools>EditObjectNotes or Tools>EditPageNotes commands will enable you to add the notes.
When the Fragment Selection dialog is displayed (see below) the Notes for the fragment are displayed for the current selection. This gives allows you to provide additional document to the designer.
Adding Fragments
Fragments are added using the + button on the Design toolbar. This allows you to select a fragment library and either Link or Embed a library object into your design (including full pages). When a fragment is Linked a small 'infinity' symbol will be displayed in the Design Form Explorer next to the object as an indication that it has been linked. Design will not let you change the attributes of a linked fragment except for its position and name.
You can review the list of fragments used on a form using the Tools>ViewAllFragments command.
When adding fragments to a completely filled Container, it is recommended that you turn on the option "Display a small gap between top-level Panes". This allows you to insert Pane fragments into the Container by targeting them between existing Panes. To set this option "On":
- Select the menu option Tools/Options
- Check on the option "Display a small gap between top-level Panes"
- Click "OK"
Fragment Resolution
When a form containing Linked Fragments is opened in Design, each associated fragment library is checked to see if the library contains a different (newer) version of the fragment. If so, that new library version is loaded into the form and replaces the original one.
If a linked fragment cannot be found in its original library, or if the library cannot be found, Design displays a list of all the fragments and highlights those that have not been found. If you know that the fragment has moved to a different library, you can make that change immediately.
Linked fragments whose library entry have not been found are said to be unresolved fragments. You can continue to use the form with these unresolved fragments and they will work as they always did. However, Design will continue to report on any unresolved fragments whenever the form is opened or saved.
Fragments in Merge
By default, Merge does NOT attempt to resolve link fragments. The existing definition in the form file will be used. You can however direct Merge to check all linked fragments and load in new definitions just as is done in Design by using the -FragmentAutoResolve option. Set Merge ... -FragmentAutoResolve Yes ...
to enable this processing.
Linked fragments whose library cannot be found, or that cannot be found in the library are simply ignored and the original fragment definition in the form continues to be used.
A detailed summary of which fragments were resolved can be found in the trace file by using the -Trace option of Merge.
