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 Toolkit
The Zymonic Toolkit is a collection of useful scripts written in perl to enable you to manage existing systems and create new ones.

Zymonic Objects and Redeclarables
Zymonic objects are unique definitions that provide the building blocks for the Zymonic front end. Redeclarables are similar in as far as they have unique definitions, however they do not have to be a Perl object.

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

 true %d/%m/%Y true 

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

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

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

ZZRF &lt;= ?

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  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> test_zname</ZName> hidden  test_zname_2</ZName> test_display_name</DisplayName> <Field> test_zname_3</ZName> </Field> <Test>Equals</Test> <DesiredValue> <StaticValue>test_static_value</StaticValue> </DesiredValue> </Condition> </ConditionalFormat>

<Field> test_zname_4</ZName> test_display_name_2</DisplayName> <ConditionalFormat> 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> test_zname</ZName> test_display_name</DisplayName> <Field > test_zname_3</ZName> test_display_name_2</DisplayName> <Base>test_base</Base> </Field> <Field ">     test_zname_4</ZName>      test_display_name_3</DisplayName>      <Base>test_base_2</Base>    </Field>  </Form>

<Field class="SubForm"> test_zname</ZName> 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