Glossary



This is a glossary of terms relating to Zymonic. Search the terms you want, or navigate using the links. Feel free to add information about any terms that are absent.

Zymonic object
What

A perl object that can be created in the XML and has a ZName (unique identifier, see ZName). Examples include blocks, filters and searchmaps (described elsewhere in documentation.)

Purpose

Allows the code to be thought of in terms of the intuitive UI elements it outputs. The Zymonic object also can be redeclared using the ZName elsewhere in the code, and Zymonic will automatically use the same definition, useful to avoid re-writing code, and also to put definitions in another file to make a file look neater to read.

Usage

Created using information from different methods, they are then converted into Perl objects during config build. Elements can then be added to the XML to include them into a system.

Example

Field, is an example of a Zymonic object, from the example below:  test_zname  test_zname_2 DISPLAY varchar 255 This is a random description  test_zname_3</ZName> </FieldGroup> </Field> </SearchField>

Redeclarables
What

Has a Zname (unique identifier, see ZName), but unlike a Zymonic object it is not used to create a Perl object.

Purpose

Allows the redeclarable to be declared in multiple places, without needing to be actually created as an object. This means the XML author can place this ZName elsewhere and the same definition will be used by Zymonic automatically. This saves on code rewrite and also means the XML author can put definition in a seperate file to make a file look neater to read.

Usage

They only need to be given a ZName in the xml, such that can be uniquely identified.

Example

Search field is an example of a redeclarable from the example below:

<SearchField> test_zname</ZName> <Field> test_zname_2</ZName> DISPLAY</DisplayName> varchar</SQLFieldType> 255</MaximumLength> This is a random description</ShortDescription> <FieldGroup> test_zname_3</ZName> </FieldGroup> </Field> </SearchField>

XML Definition/{xmldef}
What

All the information needed in the XML to define a Zymonic object.

Purpose

To include all the information Zymonic needs to create a Zymonic object and allow Zymonic code to easily access these elements.

Usage Accessed in the Perl code using object->{xmldef}->{SomeElement}->{content}. Can also be accessed in the Linux terminal using get_def (see FAQ).

Example

my $class_options      =   $self->{xmldef}->{ClassOptions}
 * Perl


 * XML

<ClassOptions> <CaptureDate>true</CaptureDate> <DateFormat>%d/%m/%Y</DateFormat> <CaptureTime>true</CaptureTime> </ClassOptions>

Field ref
What

A hash ref of data about a field, stored in the Perl code including information from the XML.

Purpose

Used by methods within Zymonic for referring to a field such as when creating searchmaps.

Usage

Stored as a hash ref in Zymonic::FieldFactory::get_field_ref_details.

Relevant modules


 * Base.pm
 * FieldFactory.pm
 * Field.pm

ZName (pronounced zed-name)
What

Unique identifier for Zymonic objects and for redeclarables.

Purpose

For referring to something specifically, it can be used to redeclare objects and redeclarables, and refer to them within the code.

Usage

Usually set in the XML or created automatically in the Perl, it is stored in a hash as part of the Field Ref. It can then be used by Zymonic through ->{ZName} to locate a specific object, check for an objects existence, or used in the debugger.

Example

test_zname</ZName>

Display name
What

Name of a Zymonic object that is displayed to the end user.

Purpose

To allow a user friendly name to be displayed that doesn’t have to be unique, unlike the ZName, which must be unique.

Usage

Set in the XML inside a field element. It is then displayed in the UI for the user, in both the menu and on the block or search field or etc.

Example test_display_name</DisplayName>

Manifest
What

A Zymonic Manifest is a Perl module sub-classed from Zymonic::Manifest and used by the Installer Toolkit to install the components required for some aspect of Zymonic functionality.

Purpose

Zymonic is designed such that components can be installed separately e.g. the Decryptor, the Scheduler, the Core, a Project Management system, an Order Fulfillment system etc.

It will contain a list of files of directories and where those should be installed, additionally it can contain actions that will occur on install or update.

Once a manifest has been installed by the Installer then it will be updated at every update (unless specific manifests are being updated separately - see the Installer documentation for how to do this).

Usage zymonic_toolkit.pl Installer install --manifests [Manifest Name - the part after Zymonic::Manifest::]

Example

The core for example has the following in its 'get_contents' method:

my %Manifest = (

# bin - move contents to modules/[correct module]/bin cgi_bin => { destination => 'cgi-bin', files       => ["$Working_copy/cgi-bin/"], user        => $self->{app_server}->{options}->{apache_user}, group       => $self->{app_server}->{options}->{apache_group}, post_install => [ sub { my $app_server = shift; $app_server->restart_webserver; } ] },       ui_stylesheets => { destination => 'stylesheets', files       => ["$Working_copy/stylesheets/"], user        => $self->{app_server}->{options}->{apache_user}, group       => $self->{app_server}->{options}->{apache_group}, post_install => [ sub { my $app_server = shift; $app_server->combine_stylesheet; } ] },       images => { destination => 'images', files       => ["$Working_copy/images/"], user        => $self->{app_server}->{options}->{apache_user}, group       => $self->{app_server}->{options}->{apache_group}, post_install => [] },       javascript => { destination => 'javascript', files      => ["$Working_copy/javascript/"], user       => $self->{app_server}->{options}->{apache_user}, group      => $self->{app_server}->{options}->{apache_group},

post_install => [] },       perl_modules => { destination => '', files       => ["$Working_copy/modules/Zymonic/"], post_install => [ sub { my $app_server     = shift; my $zymonic_version = "Z". $self->current_revision('with_type');

$app_server->install_perl_module( "Zymonic Core", "$Working_copy/modules/Zymonic/" ); $app_server->set_versions($zymonic_version); }           ]        },        xml => { destination => '', files       => ["$Working_copy/xml/"], post_install => [ sub { my $app_server   = shift; my @changed_files = $self->get_changed_files('xml'); $app_server->offer_config_build( "$Working_copy/xml/", @changed_files );

# this relies on changes to AppServer, however manifests are updated first # so wrap this in an eval so we don't get errors when this change appears # before the AppServer ones eval {

# run build cache command on any systems which contain one of the changed # files, and one of those files has the flag to build caches map { $app_server->run_toolkit_command( 'System', 'build_object_caches', { system => $_ } ); } $app_server->get_systems_by_xml( 'build_cache="true"', \@changed_files ); 1;                   } or do                    { my $exception = $@; $app_server->write_log(                           "Error checking whether to rebuild caches: " . $self->ll_exception($exception) ); };               }            ]        },    );

Pod
What

Section of comment at the top of methods and modules with a standard format.

Purpose

Describes the properties of the code within the code block, and how it should be used.

Usage

Copied and pasted from other similar code, it should include the method’s name, usage, what it returns, arguments, and any exceptions it throws.

Example


 * 1) subroutine header begin ####################

=head2 load_search_field

Usage    : $filter->load_search_field($zname) Purpose  : Loads single search_field for the filter. Returns  : field ref, or nothing is not loaded Argument : zname of search field Throws   : nothing Comment  : Will not load SubForm or MultipleChoiceLinkedField type fields

See Also  :

=cut


 * 1) subroutine header end ####################

Parents
What

The class in which a Perl object was created. This is Separate from the built in Perl concept.

Purpose

To refer to attributes and methods of the parent.

Usage

Set as a key in the object ref when the object is created so that parent can be referenced from $self->{parent}.

Example

Seen below, adding the parent key when creating a Perl object allows calling of methods from the parent. Zymonic::SearchMap->new(               xmldef           => $_,                config           => $self->{config},                zname            => $_->{ZName}->{content},                parent           => $self,                report_field_ref => $report_field_ref->{ref}              )

$self->{parent}->get_search_field

System
What

Database interfaces that use Zymonic to build and run them and are described in the XML.

Purpose

Product sold to customers.

Usage

Can be accessed on the web.

Example

http://test_site/zymonic/test_system

Condition
What

An SQL style rule optionally put in by the XML author, to be used in a where clause of an SQL query.

Purpose

Put into the XML manually inside a searchmap to specify how the database should be searched.

Usage

Placed in a condition element including ZZRF as a placeholder for the database record and ? as a placeholder for the value input to the searchfield. These placeholders are then replaced with the appropriate values later, for security reasons (google prepared statements). If no condition is specified by the XML author, ZZRF == ? is used.

Example

<Condition>ZZRF &lt;= ?</Condition>

Block
What

A Zymonic object. It is a moveable, closable, interactive section in the user interface which contains either a filter or a process. Everything attached to the block is associated with a single process or filter.

Purpose

To allow the user to enter all the relevant details to search the database or add data to the database.

Relevant Modules


 * Base.pm
 * Block.pm
 * Filter.pm
 * Field.pm
 * FieldFactory.pm

Filter
What

A Zymonic object and type of block containing search fields and report fields for searching the database.

Purpose

Used by the user for querying the database using the search fields, and reporting the results using the report fields.

Usage

Defined in the XML and contains definitions for relevant search fields and report fields.

Relevant Modules


 * Filter.pm

Process
What

A Zymonic object, and a type of block used by the user for adding data to the database. The process contains fields for capturing data from the user and can exist in multiple states, which are transitioned between using buttons at the bottom of the filter.

Purpose

To capture new data from the user, and enter it into the database.

Usage

Defined in the XML it contains definitions for the different states, transitions, and tables.

Relevant modules


 * Process.pm
 * Filter.pm

Search Field
What

A type of field, which looks like an input box, that allows the user to enter data. The data entered into a search field is compared to the data in the database, using the condition defined in the XML (see condition). Search fields are an example of a redeclarable and essentially act as a flag to ‘make’ the field a search field sub type.

Purpose

To allow the user to search the database, so results can be returned by the report fields.

Usage

Defined in the xml and contains the definition on of which field. Used by the user by simply typing in data of the right type.

Relevant modules


 * Field.pm
 * Filter.pm
 * SearchMap.pm

Report Field
What

A type of field, that reports back to the user, data, from the database. Results are based on the data entered into the search field and the condition. Report fields are an example of a redeclarable and essentially act as a flag to ‘make’ the field a report field sub type.

Purpose

To report back the relevant data to the user.

Usage

Defined in the XML and contains definitions on of a field. Used by the user simply by searching a viewing the results reported back.

Relevant modules


 * Field.pm
 * Filter.pm
 * SearchMap.pm

Form
What

A form in Zymonic is essentially just a wrapper around the HTML form element, which holds a collection of fields.

Purpose

To allow Zymonic to interact with and control the HTML form element.

Usage

Defined in the xml, and contains definitions for fields.

Relevant modules


 * Form.pm

Field
What

A Zymonic object, that wraps a database field to control how it is displayed (both when searching and reporting and inputting data) and what data is allowed in the field.

Purpose

A wrapper to allow control over how the database field is displayed. It can be used to display, search on or capture data.

Usage

Defined in the xml, within a report field or search field with a ZName, display name, and base table.

Example

<Field> test_zname</ZName> <Base>test_base</Base> test_display_name</DisplayName> </Field>

Relevant modules


 * Field.pm
 * FieldFactory.pm

SearchMap
What

A Zymonic object, that handles ‘communication’ between search fields and report fields, including getting the value entered, setting up the where clause, replacing the placeholders ZZRF and ? and passing this information to the report field.

Purpose

To take information needed from the user, and the xml, and put it into a format that can be used for querying the database.

Usage

Defined in the XML inside a report field element and contains a ZName, searchfieldname, optional condition, and optional percentbefore/percentafter.

Example

<SearchMap> test_zname</ZName> <SearchFieldName>test_searchfield_name</SearchFieldName> <Condition>ZZRF LIKE ?</Condition> <PercentBefore>true</PercentBefore> <PercentAfter>true</PercentAfter> </SearchMap>

Relevant modules


 * SearchMap.pm

Base
What

Similar to the coding concept of inheritance, Zymonic objects have a ‘base’ functionality that allows them to use features of other Zymonic objects.

Purpose

To increase re-use of code, thereby making the code easier to understand and saving time. Also means that features changed from one Zymonic object can affect all objects that are based on it, making the code easier to maintain.

Usage

Can be set in the XML using tags, and will be interpreted during config build.

Example

Below, 'test_zname_2' inherits all properties of ‘test_zname’. Any properties with the same name will be overwritten with ones from shipping_weight: <Field> test_zname</ZName> test_display_name</DisplayName> int</SQLFieldType> <ShortDescription>This is a short description</ShortDescription> </Field> <Field> <ZName>test_zname_2</ZName> <Base>_test_base_zname</Base> <DisplayName>test_display_name_2</DisplayName> <ShortDescription>This is another short description</ShortDescription> </Field>

Conditional format
What

Conditional formatting in Zymonic allows CSS styles to be applied to a field dependant on the value of a field.

Purpose

Conditional formatting allows the UI to change dynamically depending on what the user is doing. An example might be highlighting fields that are not filled in, or hiding fields that are not needed/shouldn't be used.

Usage

Can be set in the XML using <ConditionalFormat> tags and has a ZName. A condition should be defined within the conditional format definition that specifies the field to be tested and the conditions for the test to pass. A "condition combination" can also be defined to specify how multiple conditions should be applied.

Example

Below, the conditional format hides a field when the test_zname_3 field equals "test_static_value". Below that is an example of including the conditional format in a field definition, so the test_zname_4 field would now hide if test_zname_3 has the value "test_static_value" except that there is also a condition combination, that in this case it specifies that the condition should be applied when the test is not met. In other cases "and" or "or" can be used in condition combinations between multiple conditions.

<ConditionalFormat> <ZName>test_zname</ZName> hidden <Condition> <ZName>test_zname_2</ZName> <DisplayName>test_display_name</DisplayName> <Field> <ZName>test_zname_3</ZName> </Field> <Test>Equals</Test> <DesiredValue> <StaticValue>test_static_value</StaticValue> </DesiredValue> </Condition> </ConditionalFormat>

<Field> <ZName>test_zname_4</ZName> <DisplayName>test_display_name_2</DisplayName> <ConditionalFormat> <ZName>test_zname</ZName> </ConditionalFormat> <ConditionCombination>!Clause[test_mode]</ConditionCombination> </Field>

SubForm
What

A SubForm is a special field class that allows a separate form to be defined within another form (the parent or outer form). The SubForm contains its own fields and a link to a database table.

Purpose

SubForms can be used to have multiple of the same type of record in the same parent form, the user can click the 'add' transition to add. This allows them to enter more data in the next record, and thus populate a table - the parent form record and SubForm records will be 'linked' (foreign key) in the database by having the same 'parent_process_id'.

This might occur in processes where you have some header information and then multiple lines of information - an order for example would contain: date, time, delivery address etc. at the 'parent' form level and then have a SubForm field to contain each line of the order - each line of the order might have a catalogue code, description, price, quantity etc.

Usage

Can be set in the XML using <SubForm> tags and writing the definition inside a field definition that has the SubForm class set.

Example

Below, is an example of setting up a subform that has 2 fields, and referencing the defintion inside a field definition:

<Form> <ZName>test_zname</ZName> <DisplayName>test_display_name</DisplayName> <Field > <ZName>test_zname_3</ZName> <DisplayName>test_display_name_2</DisplayName> <Base>test_base</Base> </Field> <Field ">     <ZName>test_zname_4</ZName>      <DisplayName>test_display_name_3</DisplayName>      <Base>test_base_2</Base>    </Field>  </Form>

<Field class="SubForm"> <ZName>test_zname</ZName> <DisplayName>test_display_name</DisplayName> <SubForm> <Form> <ZName>test_zname_2</ZName> </Form> </SubForm> </Field>

SourceFilter
What

A SourceFilter is a filter used for the 'background' task of extracting data from a database table and passing it to a subform. The subform can then be automatically populated with records based on the records passed in by the SourceFilter.

Purpose

This allows a multiple record form to be set up for use in a process based on data already in the system saving time over having to set up many records manually in the GUI.

Usage

The SourceFilter can be set up in the ordinary way for a filter, with a base table and reportfields that are desired to be passed on. This filter is then referenced within a form using the </JoinFrom> <JoinTo> </JoinTo> <JoinType>LEFT</JoinType> <JoinCondition>test_zname_4.[ztsm_size_types_autolinkedfield] = sizes_to_size_types.[test_zname_5]</JoinCondition> </TableInclude> SELECT * FROM test_zname LEFT JOIN test_zname_2 ON test_zname_3.id = test_zname_4.id;

$self
What

$self is a hashref used in nearly every Zymonic method to store data about an object, and can call Zymonic methods.

Purpose

$self gives a large degree of flexibility to allow Zymonic to link itself between various modules.

Usage

$self can be used to store definitions - such as data on a filter (what states associate with it, it's zname etc) - it can call Zymonic methods - such as get_def - and stores data about the object currently active in the code - such as it's zname ($self->{ZName}->{content}.

Example

Below: $self calls a method to get the definition of a process to then get it's related transitions by using a method called get_array and get_def - it then stores it in an array which contains each transition's definition. From there, you can use a foreach loop to go through each definition to pick out the data that you need.

my @process_transitions = get_array( ( $self->get_def( 'Process', 'test_zname' ) )->{Transition} )

Config Build
What

The config build is used to prepare the system definition for the program.

Purpose

The config build provides xml definitions for objects, reads through the XML and updates tables.

Usage

It is used after a zymobuild to collate the updated code pulled from the repository in the zymobuild and creates the backbone for the entire system.

Examples

Below: This command is inputted into the linux terminal of the host server to do a config build. This is a basic version; more variants are below. The system is the program you want to run the config build on.

sudo zymonic_toolkit.pl System config_build --system test_system

This next one initiates a full config build - this is usually unnecessary and very time-consuming, but can be useful in diagnosing errors.

sudo zymonic_toolkit.pl System config_build --system test_system --full yes

Finally, this one debugs the config build, so if there is an error in the build you can go through it, line by line, in the perl debugger and usually narrow down the problem to one or two lines.

sudo perl -d `which zymonic_toolkit.pl` System config_build --system test_system