Difference between revisions of "Mod settings.php"

Latest revision as of 17:44, 24 February 2011

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

The configuration of subforms is an essential step to setting up the module settings. Given the complexity of the task, please see the dedicated Subforms chapter.

Delete and Edit Functions

As of v0.8 administrators have the option of configuring options for editing modtypes and itemvals, and deleting entire records. Due to the complexity of these tasks (given the string of data fragments that could potentially be deleted/edited), several subforms must be configured from within the mod_settings to allow for this option. The following subforms should be configured to allow for this function:

• sf_modtype_conflicts - To be used for editing modtypes
• sf_dnarecord - Displays the 'dna' of a record to administrator, shows individual data fragments attached to record during the delete process
• sf_delete_record - Performs delete record function
• sf_itemval - To be used for editing itemvals

Example configurations of each subform are located in the individual subform documentation linked above.

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 the 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, but here is an example taken from mod_smp_settings.php

$conf_dat_materi =
    array(
        'col_id' => 'main_column',
        'col_alias' => FALSE,
       	'col_type' => 'collaps_col',
        'subforms' => array(
            $conf_mcd_botanictypes,
	    $conf_mcd_botanic,


        )
);

Micro View

The micro view page is used to display a single record. This page makes use of the subforms set up above and assembles them into columns according to the settings within this section. These columns are then joined/packaged together into a single package for convenience. As the micro view is used for displaying the data in the most suitable format, it is important to note that the organisation of this form does NOT in any way need to follow that of the detfrm used for data entry.

To configure the micro view:

1. Create the micro view columns
2. Package the columns into an array
3. Set the display options

Micro View Columns

In our example from mod_cxt_settings, we are using 2 columns for the micro view. They are configured like this:

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

$conf_mcd_col_2 =
    array(
        'col_id' => 'second_column',
        'col_alias' => FALSE,
        'col_type' => 'secondary_col',
        'subforms' => array(
            $conf_mcd_spat, 
            $conf_mcd_sphxmi,
            $conf_mcd_span_rels,
            $conf_mcd_smpxmi,
            $conf_mcd_spfxmi
        )
);

The subforms contained in each column have already been defined above. Variables needed for the micro view columns are:

• col_id - where is the column to be displayed (main_column, second_column, third_column, etc)
• col_alias - does column have an alias (FALSE/TRUE)
• col_type - the type of column (primary_col, secondary_col)
• subforms - subforms to add to each column

Column Package

The above columns are now grouped into a single column package. In our mod_cxt_settings.php this looks like this:

$cxt_conf_mcd_cols =
    array(
        'op_display_type' => 'cols',
        'op_top_col' => 'main_column',
        'columns' =>
            array(
                $conf_mcd_col_1,
                $conf_mcd_col_2
        )        
);

The variables used in the columns package are:

• op_display_type - how are the columns displayed, set as cols (columns) or tabs (tabs)
• op_top_col - sets which column is the first (main_column)
• columns - an array with all columns in the order they are to appear

Data View

The data view page is used to display many records from different modules, often simultaneously. Within each module settings file it is mandatory to set what information is displayed in the data view.

The data view displays search results as table, chat, or map. The configuration for each view is discussed below.

Table

The data is expressed as a series of xhtml tables. Each module needs configuration of the columns for display and the column headers for each field. The table configuration is basically a simple subform package and follows all the rules of Subforms.

In our mod_cxt_settings.php example, the data view configuration for the table looks like this:

$conf_mac_table =
    array(
        'fields' =>
            array(
                $conf_field_itemkey,
                $conf_field_cxttype,
                $conf_field_short_desc,
                $conf_field_issuedto,
                $conf_field_issuedon,
                $conf_reg_op_no_qed
        )
);

In this case we only need to specify a single variable:

• 'fields - an array of fields to be displayed in the table

Text

In our mod_cxt_settings.php example, the data view configuration for the text view looks like this:

$conf_mac_text =
    array(
        'fields' =>
            array(
                $conf_field_itemkey,
                $conf_field_cxttype,
                $conf_field_short_desc,
                $conf_field_issuedto,
                $conf_field_issuedon,
                $conf_reg_op_no_qed
        )
);

In this case we only need to specify a single variable:

• 'fields - an array of fields to be displayed in the table

Map

The view as map option is configured within the Settings.php file and not in the module specific settings.

User Field Configuration

As of v0.8 the user can add or remove fields to any of the views available on the data_view page. This is the sf_conf for the subform that is used to add/remove fields. The fields listed here are the fields that the admin wishes to make available to the user as options for adding to the view. Keeping the list short can help to make the user interface easier to understand.
Fields in this list MUST have field_id set up (correctly) in field_settings

// Add fields to the current view subform
$conf_mac_userconfigfields =
    array(
        'view_state' => 'max',
        'edit_state' => 'view',
        'sf_nav_type' => 'none',
        'sf_title' => 'userconfigfields', 
        'sf_html_id' => 'mac_userconfigfields', // Must be unique
        'script' => 'php/data_view/subforms/sf_userconfigfields.php',
        'op_label' => 'space',
        'op_input' => 'go',
        'op_modtype' => FALSE,
        'fields' => // these are the fields available to the user - only fields with 'field_id' work
            array(
                $conf_field_itemkey,
                $conf_field_cxttype,
                $conf_field_smyinterp,
                $conf_field_dr,
                $conf_field_finish,
                $conf_field_short_desc,
        ),
);

XMI View

Any module item will likely be viewed in a reduced form from within another module. Therefore it is necessary to configure the XMI view settings in each mod_settings file. The XMI view describes how a specific module represents itself when called into an XMI view by another module.

In our example of mod_cxt_settings.php, the XMI configuration looks like this:

$cxt_xmiconf =
    array(
        'op_xmi_hdrbar' => 'link', // we put optional stuff in here 
        'op_xmi_label' => TRUE, // we put optional stuff in here           
        'fields' => 
            array(
                $conf_field_short_desc,
                $conf_field_issuedto,
                $conf_field_issuedon,
        )
);

The variables we are using for the XMI settings are:

• op_xmi_hdrbar - how to display the header of each XMI record, options 'link' (as a link), 'name' (display the name only)
• op_xmi_label - set whether the record type will be displayed, set as TRUE/FALSE
• fields - which fields, as set up above or in field_settings.php should be displayed with each record in XMI view

Export

As of v0.8 the export functionality has been greatly revised. The aim here has been to make these settings arrays fall into a more familiar architecture. As such, each download mode will now need to be set up as a subform. The CSV downloader is pretty much now the model for this now. As the conf is a 'mac' or macro view (a.k.a data_view) subform, it should appear in the mod_settings as such.

The call to the sf_conf is setup in settings.php in the toolbar conf. As the downloads are called using a subform within an overlay, the conf is passed to overlay holder.

In the example mod_cxt_settings.php the export configuration is:

// Data View Export Download Subform For CSV
$conf_mac_exportdownloadcsv =
    array(
        'view_state' => 'max',
        'edit_state' => 'view',
        'sf_nav_type' => 'none',
        'sf_title' => 'exportdownloadcsv', 
        'sf_html_id' => 'mac_exportdownloadcsv', // Must be unique
        'script' => 'php/data_view/subforms/sf_exportdownload.php',
        'op_label' => 'prepdl',
        'op_input' => 'go',
        'op_modtype' => FALSE,
        'fields' =>
            array(
                $conf_field_itemkey,
                $conf_field_cxttype,
                $conf_field_smyinterp,
                $conf_field_dr,
                $conf_field_short_desc,
        ),
        'op_field_delimiter' => ',',
        'op_text_delimiter' => '"',
        'op_clean_headers' => TRUE //use this to force GIS friendly headers
);
 

In this example the CSV (Comma Separated Values) is configured. Along with the usual subform requirements, the following variables are needed:

• fields - the fields to be exported, as configured above or in field_settings.php
• op_field_delimiter - delimiter between fields (use a comma for CSV exports)
• op_text_delimiter - delimiter between text (use a space for CSV exports)
• op_clean_headers - if this is set then the headers will be made lowercase and the spaces in them will be underscores (mainly so ArcGIS can read it). If you DON'T want this then take the op out completely.