XML Module Definition

From AADoc

Jump to: navigation, search

Module Definition files define the structure of a module in Active Agenda, in a specific XML format. These files typically reside in the s2a/active_agenda/xml folder in the source tree. A recent feature allows placing customized (for a specific installation of AA) files in a subdirectory, which keeps customizations from getting overwritten when updating.

The following is a very basic outline of the XML structure in a module definition XML file: 

<Module>
  <ModuleFields>
     (Any valid ModuleField)
  </ModuleFields>
  <ModuleInfo>
     <PrimaryKey>
        (One or more FieldRefs)
     </PrimaryKey>
     <Index> (several allowed)
        (One or more FieldRefs)
     </Index>
     <OwnerField />
     <RecordDescriptionField />
     <RecordLabelField />
     <ConsistencyCondition> (several allowed)
        (One or more ConditionTriggers)
        (One or more LocalFieldTargets)
        (One or more SubModuleTargets)
     </ConsistencyCondition>
  </ModuleInfo>
  <SubModules>
     (Submodule definitions)
  </SubModules>
  <Screens>
     (Any valid Screen definitions)
  </Screens>
  <RecordSummaryFields>
     (RecordSummaryFields definitions)
  </RecordSummaryFields>
  <Exports>
     (Export grid definitions)
  </Exports>
  <Documentation>
     (DocumentationSection definitions)
  </Documentation>
  <Revision/>
</Module>

Please note that required attributes have been omitted above, for clarity. Also note that text within round parenteses are comments and not actually part of the code.

Contents

[edit]

The Module Element

A requirement for valid XML is that every document contain a single "root element". In the Active Agenda Module definition, this element is called <Module>. Therefore, all other XML elements must be contained between the <Module> and </Module> tags in the module definiton.

[edit]

Attributes

addNewName
Optional. An abbreviated, more generic, version of the module name. Example: "Permit"
allowAddRecord
Recommended. Whether users can add records directly in this module. Setting this to "no" still allows records to be added from an editable grid in a parent module. If not indicated, "yes" is applied by default. Valid choices: "yes", "no".
dataCollectionForm
Recommended. Whether the module will generate a blank data collection form during module generation. Setting this to "yes" enables a user to generate a blank data collection form for a module and its sub-modules from the List screen. This attribute can also be inserted on an edit grid to suppress a sub-module data collection form from being included in a parent module's data collection form. Valid choices: "yes", "no".
extendsModuleID
Optional. Used if the module should extend another module.
isMasterData
Optional. Used if the module data should be included in the default installation file.
name
Required. A short but descriptive name for the module. Example: "Hot Work"
moduleID
Required. A unique letter combination (3-5 characters) that identifies the module. For new modules, please check the list of Module IDs to ensure that the selected moduleID is not already taken. Also see the guidelines for choosing a module ID. Example: "hwk"
pluralRecordName
Recommended. A word or phrase that describes a single record. Example: "Hot Work Activities"
singularRecordName
Recommended. A word or phrase that describes a single record. Example: "Hot Work Activity"
[edit]

Subsections

For convenience and clarity, the definitions in the module definition file are grouped into separate parent elements, which we call subsections. Although it's not strictly required, we suggest that you always keep the subsections in the order below.

ModuleFields
Required. This section defines the database meta-structure of the module. Any valid ModuleField is allowed here; for instance:
ModuleInfo
Required. A place holder for additional definitions that affect the database table structure. These include:
SubModules
Required if any of the screens below contain any grids. Contains SubModule definitions, which describe the logical relationship between the data in the parent module (the current module definition) and that of any submodules.
ListFields
Optional, to be deprecated. Currently defines the fields that appear in the List screen. This is inconsistent with the definition of other screen and will be deprecated.
Screens
Optional. This section defines much of the module-specific parts of the user interface. A typical module would contain a:
RecordSummaryFields
Optional. Contains view-only fields that are re-used by Edit screens by using the RecordSummaryFieldsRef element.
Exports
Optional. Contains standard implementations of grids. These can be referenced by a parent module by defining an empty (no fields defined) grid. When parsing the parent module, the parser will import any matching grid definitions from submodules. In other words, the module where the grids are defined will "push" the grid to any module containing the empty grid definition.
Custom view grids may be used to display stipulated fields from a module included within the sub module reference section and can include any field contained in the respective sub module's module field section. In this instance, the parent module "pulls" the data from the sub module on an included field basis.
Charts
Optional. Contains the definitions required to produce charts for display on the Charts screen.
Documentation
Optional. Contains module-specific documentation, organized in DocumentationSection elements.
[edit]

Add-on definitions

In order to enable easier distribution of additions to the standard module definitions, recent changes implement support for separate add-on files to a module. These will be processed together with the main XML file, and the resulting generated application will reflect the contents of both the main XML file and all the applied add-ons.

Retrieved from "http://www.activeagenda.net/documentation/index.php?title=XML_Module_Definition"
Personal tools