Difference between revisions of "Mod settings.php"

Revision as of 07:50, 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. Set up the detform in the following steps:

• 1 - set up any validation rules you need in the vd_settings file. Anything mod
• specific ought to go in this settings file, example syntax is given below.
• 2 - set up any fields to put into the form. generally these ought to go into
• the field_settings file as this means they can be used by other modules. mod
• specific fields may go into this file at the top in the 'fields' section.
• 3 - add in any custom validation
• 4 - set up the form using the standard subform format. The form is an array
• containing variables that define the form an an array of fields

• VARIABLES FOR DETFRM COLUMN
• col_id = only one column (main_column)
• col_alias = does column have an alias (FALSE/TRUE)
• col_type = type of column (single_col)
• subforms = subforms to add to colums
• /

// COLUMN PACK FOR DATA ENTRY

$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
        )
);

Optional Views

/** OPTIONAL VIEWS

• Optional views, like the two previous, are displayed in a single column for
• rapid data entry. Different optional views can be defined by the administrator.
• Additional custom validation is generally required for custom views.
• 1 - set up any validation rules you need in the vd_settings file. Anything mod
• specific ought to go in this settings file, example syntax is given below.
• 2 - set up any fields to put into the form. generally these ought to go into
• the field_settings file as this means they can be used by other modules. mod
• specific fields may go into this file at the top in the 'fields' section.
• 3 - add in any custom validation
• 4 - set up the form using the standard subform format. The form is an array
• containing variables that define the form an an array of fields
• Note: custom validation
• In order to add custom validation rules on a use per use basis of a field
• the additional or custom rules may be inserted into the validation arrays for
• each field using the following shorthand syntax. This must be done before
• adding the field to the suform
• $field['add_validation][] = $my_custom_rule;
• /

// No optional views in this settings file

Micro View

Data View

XMI View

Export