Zymonic Objects and Redeclarables

A Zymonic object is a perl object that can be created in the XML and has a ZName.

They allow 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.

They are 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.

Redeclarables

They have a ZName, but unlike a Zymonic object it is not used to create a Perl object.

This 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 separate file to make a file look neater to read.

They only need to be given a ZName in the XML, such that can be uniquely identified, like the following example:

  <SearchField>
    <ZName>ts_sf_customerforename</ZName>
    <ShortDescription>The customer's first and middle names</ShortDescription>
    <Field>
      <ZName>ts_f_customerforename</ZName>
    </Field>
  </SearchField>

You can use <Base> to fetch the definition of an object, then change/add fields as you see fit. This helps to stop code being repeated unnecessarily.

Zymonic Objects

Each object or redeclarable will be given an example XML definition so it is easy to see how to write it in real code. We removed duplicate tags (for example, if more than one field was on a form) to shorten the examples and to simplify them. If there is more information on a subject, the header will be a hyperlink.

Page

A Zymonic object that contains the blocks that make up a system.

  <Page Preferred="2">
    <ZName>ts_p_customeraccounts</ZName>
    <DisplayName>Customer Accounts</DisplayName>
    <Block>
      <ZName>ts_b_customeraccounts</ZName>
    </Block>
    <Layout>
      <ZName>SingleColumnLayout</ZName>
    </Layout>
    <RolePermission>
      <ZName>ts_rp_customeraccounts</ZName>
    </RolePermission>
  </Page>

Table

A table is defined in the XML and inserted into MySQL. It allows a system to store data in fields, which can easily be linked to processes, forms and filters.

  <Table>
    <ZName>ts_t_customeraccounts</ZName>
    <SQLName>t_customeraccounts</SQLName>
    <Field>
      <ZName>ts_f_customerid</ZName>
    </Field>
    <Key>
      <ZName>ts_k_customerid</ZName>
    </Key>
    <RelationshipPermissions>
      <ZName>AdminsAllPerms</ZName>
    </RelationshipPermissions>
  </Table>

Block

A Zymonic object that is 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.

  <Block>
    <ZName>ts_b_purchaserecords</ZName>
    <DisplayName>Purchase Records</DisplayName>
    <Location>Main</Location>
    <Filter>
      <ZName>ts_fil_purchaserecords</ZName>
    </Filter>
  </Block>

Process

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.

  <Process>
    <ZName>ts_pro_customeraccounts</ZName>
    <DisplayName>Customer Account</DisplayName>
    <InitialState>
      <ZName>ts_s_ca_createnew</ZName>
    </InitialState>
    <Transition>
      <ZName>ts_tra_ca_disable</ZName>
    </Transition>
    <State>
      <ZName>ts_s_ca_active</ZName>
    </State>
  </Process>

Form

A form in Zymonic is essentially just a wrapper around the HTML form element, which holds a collection of fields. A process would usually link a form by using it's states.

  <Form>
    <ZName>ts_for_customeraccounts</ZName>
    <DisplayName>Customer Accounts</DisplayName>
    <Table>
      <ZName>ts_t_customeraccounts</ZName>
    </Table>
    <Field>
      <ZName>ts_f_rocustomerid</ZName>
    </Field>
  </Form>

Field

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.

  <Field>
    <ZName>ts_f_customerid</ZName>
    <DisplayName>Customer ID</DisplayName>
    <SQLName>f_customerid</SQLName>
    <SQLFieldType>int</SQLFieldType>
    <MaximumLength>255</MaximumLength>
    <DisplaySize>20</DisplaySize>
    <FieldGroup>
      <ZName>ts_fg_basic</ZName>
    </FieldGroup>
  </Field>

SearchField

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 essentially act as a flag to ‘make’ the field a search field.

  <SearchField>
    <ZName>ts_sf_customerid</ZName>
    <ShortDescription>The customer's unique ID</ShortDescription>
    <Field>
      <ZName>ts_f_customerid</ZName>
    </Field>
  </SearchField>

ReportField

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 essentially act as a flag to ‘make’ the field a report field.

  <ReportField>
    <ZName>ts_rf_customerid</ZName>
    <Field>
      <ZName>ts_f_customerid</ZName>
    </Field>
    <SearchMap>
      <ZName>ts_sm_customerid</ZName>
    </SearchMap>
  </ReportField>

SearchMap

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.

  <SearchMap>
    <ZName>ts_sm_customerid</ZName>
    <SearchFieldName>ts_sf_customerid</SearchFieldName>
    <FalseIfEmpty>true</FalseIfEmpty>
    <Condition>ZZRF LIKE ?</Condition>
    <PercentBefore>true</PercentBefore>
    <PercentAfter>true</PercentAfter>
  </SearchMap>

State

A state is the state in which a process is in. For example, if you had a list of customer accounts they could be in a creation state (not yet made), active or disabled.

  <State>
    <ZName>ts_s_ca_active</ZName>
    <Form>
      <ZName>ts_for_customeraccounts</ZName>
    </Form>
  </State>

Key

A key in a table.

  <Key>
    <ZName>ts_k_customerid</ZName>
    <Autoincrement>true</Autoincrement>
    <FieldName>f_customerid</FieldName>
    <UniqueKey>true</UniqueKey>
  </Key>

Transition

An object that changes the state of a process and performs actions on a process, for example disabling an account.

  <Transition>
    <ZName>ts_tra_ca_disable</ZName>
    <DisplayName>Disable</DisplayName>
    <StateBeforeTransition>
      <ZName>ts_s_ca_active</ZName>
    </StateBeforeTransition>
    <StateAfterTransition>
      <ZName>ts_s_ca_disabled</ZName>
    </StateAfterTransition>
  </Transition>

RolePermission

An object that allows access permissions to be set on a page.

  <RolePermission>
    <ZName>ts_rp_customeraccounts</ZName>
    <DisplayName>Access Customer Accounts</DisplayName>
    <ShortDescription>Users with this role permission can view Customer Accounts.</ShortDescription>
  </RolePermission>

Layout

Allows setting of layouts on the UI.

  <Layout>
    <ZName>SingleColumnLayout</ZName>
    <Location>Main</Location>
  </Layout>

FilterAction

A FilterAction allows you to perform an action on a filter, usually loading a process or another filter.

  <FilterAction>
    <ZName>ts_fa_newcustomeraccount</ZName>
    <DisplayName>New Account</DisplayName>
    <ActionType>Process</ActionType>
    <ProcessOrFilterZName>ts_pro_customeraccounts</ProcessOrFilterZName>
    <AutoClose>true</AutoClose>
  </FilterAction>

FieldGroup

A group of fields on the UI, to separate different types of fields (User Information, Audit History etc).

  <FieldGroup>
    <ZName>ts_fg_basic</ZName>
    <DisplayName>Basic Information</DisplayName>
  </FieldGroup>

Condition

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

  <Condition class="UserInput">
    <ZName>ts_c_confirmdelete</ZName>
    <DisplayName>Confirm Delete</DisplayName>
    <SkipPreCheck>true</SkipPreCheck>
    <ClassOptions>
      <Prompt>Are you sure you want to delete this?</Prompt>
      <PossibleValues>Delete,Don't Delete</PossibleValues>
      <DisplayAs>Buttons</DisplayAs>
      <OnlyShowOnFail>true</OnlyShowOnFail>
    </ClassOptions>
    <Test>Equals</Test>
    <DesiredValue>
      <StaticValue>Delete</StaticValue>
    </DesiredValue>
  </Condition>

Action

Creates a change, such as updating records in a table.

  <Action class="PerformUpdates">
    <ZName>ts_act_saveaszymonicuser</ZName>
    <DisplayName>Save Zymonic User Record</DisplayName>
    <PerformUpdates>
      <ZName>ts_pu_savezymonicuserupdate</ZName>
    </PerformUpdates>
  </Action>

PerformUpdates

Creates the instructions to be able to perform updates in the database.

  <PerformUpdates>
    <ZName>ts_pu_savezymonicuserupdate</ZName>
    <DestinationTable>
      <Table>
        <ZName>ts_t_customeraccounts</ZName>
      </Table>
    </DestinationTable>
    <UpdateType>UpdateOrInsert</UpdateType>
    <UpdateKeyMap>
      <ZName>ts_ukm_savezymonicuserupdatekeymap</ZName>
    </UpdateKeyMap>
    <FieldMap>
      <ZName>ts_fm_savezymonicuserupdatefieldmaprole</ZName>
    </FieldMap>
  </PerformUpdates>

FieldMap

Gives instructions to map fields.

  <FieldMap>
    <ZName>ts_fm_purchasehistory</ZName>
    <SourceField>
      <Field>
        <ZName>ts_f_customerid</ZName>
      </Field>
    </SourceField>
    <DestinationField>
      <Field>
        <ZName>ts_sf_customerid</ZName>
      </Field>
    </DestinationField>
  </FieldMap>

UpdateKeyMap

Provides information to update a key for a table.

  <UpdateKeyMap>
    <ZName>ts_ukm_savezymonicuserupdatekeymap</ZName>
    <SourceField>
      <Field>
        <ZName>ts_f_customeremail</ZName>
      </Field>
    </SourceField>
    <DestinationField>
      <Field>
        <ZName>zz_user</ZName>
      </Field>
    </DestinationField>
  </UpdateKeyMap>

FieldFillCalculation

Fills a field with data from another field.

  <FieldFillCalculation>
    <ZName>ts_ffc_customerfullname</ZName>
    <FromOther>
      <FieldZName>ts_f_customerfullname</FieldZName>
    </FromOther>
  </FieldFillCalculation>

ConditionalFormat

A way of applying formatting to an object, only conditional if a condition is added to it.

  <ConditionalFormat>
    <ZName>ts_cf_orderformatting</ZName>
    <Condition no_cache="true">
      <ZName>ts_c_orderdiffers</ZName>
      <DisplayName>Order Type Different from Stock Type</DisplayName>
      <Field>
        <ZName>ts_f_orderdifference</ZName>
      </Field>
      <Test>NotEquals</Test>
      <DesiredValue>
        <StaticValue>0</StaticValue>
      </DesiredValue>
    </Condition>
    <classes>ts_cla_highlightdifference</classes>
  </ConditionalFormat>

System Option

A system option is a zymonic object, and type of field. The value of it is stored in the database in the zz_system_options table, and can be edited by the user using the "system options" filter/process in the admin area. This value can then be used in the code or the XML and therefore allows customization by the user.

<SystemOption>
    <ZName>cheese_type</ZName>
    <DisplayName>Set the type of cheese to use.</DisplayName>
    <Category>food</Category>
    <SubCategory>cheese</SubCategory>
    <UserSetting>true</UserSetting>
    <Default>Cheddar</Default>
    <Field>
      <ZName>cheese_field_sys_opt</ZName>      
      <DisplayName>Set the type of cheese to use.</DisplayName>
      <ShortDescription>Select a cheese to send to customers, but no bree please.</ShortDescription>
    </Field>
  </SystemOption>

This can then be referernced and used as a value in the perl:

my $dairy_product = $self->{config}->sys_opt('cheese_type');

or in the xml for example like:

<Field>
        <ZName>zz_food_basket</ZName>
        <FieldFillCalculation>
          <ZName>zz_fill_food_basket</ZName>
          <SystemOption>cheese_type</SystemOption>
        </FieldFillCalculation>
</Field>

Not to be confused by a similar concept, of adding system options to the SystemOptions.xml file found in every zymonic system.

Messaging

The Zymonic Messaging System has its own page.