Difference between revisions of "Mod settings.php"

Revision as of 08:05, 14 November 2008

These files contain settings for each installed module. Each module will require different settings depending on the data structure. For this documentation a standard single-context recording 'mod_cxt_settings.php' file will be discussed as an example.

Display Options

The display options influence how specific types of context record are displayed in navigation forms. Context data often requires brackets denoting the type of context. The code for configuring display looks like this:

$conf_br = array('type_2_L' => '(', 'type_2_R' => ')','type_1_L' => '[', 'type_1_R' => 
']','type_6_L' => '*', 'type_6_R' => '*', 'type_4_L' => '', 'type_4_R' => '');

In the above, 'type_#' refers to the type number in cxt_lut_cxttype. The L or R refers to the whether the symbol will be displayed to the left or right of the context number. The symbol itself appears after => between ' '. Please note that in some cases (as in type 6 in the above example) a symbol can be placed only to one side of the item number.

Custom Fields

Although most fields will be setup in field_settings.php, some fields are classified as 'custom' and are set-up in each modules settings file.

The three most common custom fields are as follows:

• conf_field_itemkey - This value is always setup within the module settings
• conf_field_modtype - This may be setup if there are any modtypes for the module
• conf_field_modxmi - Custom fields for xmi are also often needed, and should be included in the module settings file.

Please see below for an example of the custom field 'conf_field_itemkey' for the module Contexts:

$conf_field_itemkey =
    array(
        'dataclass' => 'itemkey',
        'classtype' => 'cxt_cd', //this is needed to correctly request the qtype
        'alias_tbl' => 'cor_tbl_module',
        'alias_col' => 'itemkey',
        'alias_src_key' => 'cxt_cd',
        'alias_type' => '1',
        'module' => 'cxt',
        'editable' => TRUE,
        'hidden' => FALSE,
        'add_validation' => $key_add_validation,
        'edt_validation' => $key_edt_validation
);

Custom Validation

Some custom fields will also require module specific custom validation rules. These must also be configured in the module settings. Custom validation rules can be inserted into the validation arrays for each field using the following:

$field['add_validation'][] = $your_custom_rule;

All custom validation must be set BEFORE adding a field using custom validation to any subform. In the example of mod_cxt_settings, custom validation for the item_key is setup with other custom fields and looks like this:

$conf_field_itemkey['add_validation'][] = $key_vd_modtype;
$conf_field_itemkey['edt_validation'][] = $key_vd_modtype;

Subforms

Spatial Data

To display spatial data, a spatial viewer subform will be required. The configuration of this subform is discussed in detail in Subforms. There are also other spatial settings that need to be set within the module settings, as follows:

• $refmap_show - decide if you want to show a reference map when teh spatial subform is in primary column, options TRUE, FALSE
• $view_map_default - decide if you want maps to display on default, options TRUE, FALSE
• $refmap_type - sets the parameters from the reference map, options SCALE (to zoom to set scale) or SHAPE (to zoom to outline of a specific shape)
• $refmap_scale - set as NULL if zooming to SHAPE, else set as integer for desired scale (ie. $refmap_scale = 500 will zoom to scale 1:500)
• $refmap_width - OPTIONAL, a value for specifying a non-default width for reference map. If not specified, the value is taken directly from the $map object.
• $refmap_height - OPTIONAL, a value for specifying a non-default height for reference map. If not specified, the value is taken directly from the $map object.
• $refmap_layer - OPTIONAL, if zoomtype SHAPE is stated this value is the name of the layer to zoom to, if not set as NULL
• $refmap_field - OPTIONAL, if zoomtype SHAPE is stated this value is the name of attribute field of the shape to zoom to, if not set as NULL
• $refmap_fieldvalue - OPTIONAL, if zoomtype SHAPE is stated this value is the specific value in the attribute field of the shape to zoom to, if not set as NULL

Data Entry Forms

Data Entry Forms are forms used for entering new items to the module or adding further details on items already issued in the module. The data entry form needs a different package for each of its different views. Each package is essentially a series of subforms contained within a single column. Data Entry views are as follows:

• Registers - for issuing new items to the module
• Detform - for detailed record entry to pre-existing items
• Optional - additional views specific to an ARK project.

Register

The register form is used for issuing new items to the module. In most cases the register is used as a standalone form, although sometimes a register is embedded within other module pages. The basic steps to setting up the Register form are as follows:

1. Set up any validation rules needed in the vd_settings file. In most cases this should already be completed. Any module specific validation should be set up in the module settings file, as discussed above.
2. Set up any fields needed within the form. Most fields are entered in the field_settings.php file. Module specific fields have already been created for this module in the Custom Fields section above.
3. Set up the register subform using the standard Subforms format.
4. Set up the register column

The register column requires a set of specific column variables. From our example of mod_cxt_settings, the register column is configured using the following code:

$conf_dat_regist =
    array(
        'col_id' => 'main_column',
        'col_alias' => FALSE,
        'col_type' => 'register_col',
        'subforms' => array(
            $conf_register
        )
);

The variables needed for the register column are:

• col_id - in the case of a data entry register, there is only one column so this should always be set as 'main_column'
• col_alias - variable stating whether or not the column has an alias, set as TRUE or FALSE
• col_type - the type of column, for registers this should always be set as 'register_col'
• subforms - the subforms to add to the register column, in this case only the $conf_register

Detfrm

The detform is a form used for rapid data entry of a single record. The detfrm is a series of subforms contained within a single column. Unlike the register, the detfrm does not generally need an additional specific subform. Instead the Subforms created already within the module settings are inserted directly into the detfrm column. Set up the detfrm in the following steps:

1. Set up any validation rules needed in the vd_settings file. In most cases this should already be completed. Any module specific validation should be set up in the module settings file, as discussed above.
2. Set up any fields needed within the form. Most fields are entered in the field_settings.php file. Module specific fields have already been created for this module in the Custom Fields section above.
3. Set up the detfrm column

The detfrm column requires the same variables as the register column discussed above. From our mod_cxt_settings.php example, the column for the detfrm looks like this:

$conf_dat_detfrm =
    array(
        'col_id' => 'main_column',
        'col_alias' => FALSE,
        'col_type' => 'collaps_col',
        'subforms' => array(
		$conf_mcd_short_desc,
		$conf_mcd_description,
		$conf_mcd_matrix,
		$conf_mcd_span_rels,
		$conf_mcd_interp,
		$conf_mcd_event
        )
);

Differences between the register and detfrm columns are needed for the following variables:

• col_type - states the column type, for detfrm use either 'single_col' (a simple single column) or collaps_col (for collapsing columns, useful with more complex data entry sheets)
• subforms - unlike the register, in the detfrm we have not created a specific detfrm subform, instead include the subforms specific to the module settings as configured above.

Optional Views

Like the register and detfrm, optional views are displayed in a single column for rapid data entry. Different optional views are defined by the ARK administrator. Additional custom validation is usually required for optional views. Like the detfrm, the steps required to set up an optional view are:

1. Set up any validation rules needed in the vd_settings file. In most cases this should already be completed. Any module specific validation should be set up in the module settings file, as discussed above.
2. Set up any fields needed within the form. Most fields are entered in the field_settings.php file. Module specific fields have already been created for this module in the Custom Fields section above.
3. Set up the optional view column

The column fields for the optional view will be the same as the register and detfrm. There are no optional views for the example mod_cxt_settings.

Micro View

Data View

XMI View

Export