The Ark model is based on several key concepts. The model is strictly modular. Records are made up of fragments of data. The data entry method aims to mimic the field recording system as closely as possble. Data viewing and analysis is by means of 2 distinct page types. Groups and filters.
- 1 Modules
- 2 Data storage structures
- 3 Macro Level Data - Working with large numbers of records
- 4 Web Output Model
The basic building bricks of ark are its modules. The fundamental module is the 'cor' module. Beyond this even the context recording module is in theory an optional module.
Modules are made up of code in the php folder and tables in the database. Each module should contain a mod_settings file in the mod subfolder of the php directory.
Every module MUST have an item key. This key defines the item which is being recorded by that module. Therefore, every record has an itemkey=itemvalue pair which expresses its exact origin.
Each item has a unique 'item record' which is made up of many 'data fragments'. The unique id of the item is then known as the item value. These 'item' records are the atomic particles of each ark module. Each of these records is however made up of yet smaller particles of data called 'data fragments'. These fragments are the bits of data held in the core tables. Any item value's record will be made up of many fragments.
Item keys are always declared in the format XXX_cd where the letters XXX match the module short form which can be found in the cor_tbl_module.
cross module intermediate tables XMIs
In order to link these basic records such as 'a context' or 'a photo' we make use of the cor_xmi which is a table that contains only links between items. Thus it is possible to link one or many items in a module to an item in another module. Or for example it is possible to link many contexts to a plan or photo.
Each module requires a settings file within its code folder which sets up basic settings for that module, generally, these settings are display related. In particular, the settings file defines what subforms to display for a module in its data entry page and its micro_view
Loaded Modules list
Data storage structures
There are 6 classes of text based data in ark plus spatial data. This area needs further thoughts with regard to more definitively resolving the issue of spatial data integration in ark. These classes are discussed in full on the database page.
Each class of data has a table in the cor module which contains the many 'data fragments' that go to make up each 'item record'. Every data fragment carries the itemkey=itemvalue pair of it's parent 'item record'.
As discussed above, 'data fragments' are the sub-atomic particles of ark. They are individualy useless fragments of information that only make sense when reassembled as an 'item record'.
At present, we dont store the information about what 'data fragments' are needed to make up an 'item record' anywhere in the database.
Events are similar to 'item records' in that they are made up of 'data fragments'. These are people or actors and datetime values. Similarly to 'item records' we don't currently store this information anywhere in the database.
look up tables
Item records/fragments/fragment chains
An 'Item' is a chunk of data in ark. This is identified by its unique identifier, its item_key=item_value pair. This pair indicates the module to which the item belongs and the value indicates the unique identifier of that item within the module. An item acts as the main root record of the ark model. In effect it is the unique record identifier for the data.
An item record is a loose aglomeration of data fragments and chains that are connected to and identified by an item_key=item_value pair. In the ark model as it currently stands, there is no formal way in which this record is defined, meaning that it is not explicitly stated anywhere in the ark what fragments and chains must be attached toa particular record.
An item record therefore has several key features:
- An item_key=item_value pair
- Data fragments and chains attached to it
An item may be viewed in many ways, although the main way to view an entire record would be by using the The Micro Viewer.
Attaching Data Fragments
Data fragments are attached to a record by filling in the item_key and item_value columns in the table of the fragment. Thus a fragment of text is attached to a context by setting the item_key of the text fragment to cxt_cd and the item_value as the cxt_cd (eg FBN05_213). As stated above, there is no way to know what fragments have been attached to a context without searching through all the data class tables for that item_key=item_value pair.
Creating and Attaching Data Chains
A data chain is a linked chain of data fragments that are unlitimately connected to a record by means of the 'head' of the chain. In order to chain a fragment of data to another, it is not the item_key=item_value pair that is entered int he data class table, but the table=frag_id. Thus in order to link a person to a text, you would get the id and table of the text (table for text is always cor_tbl_txt) and insert this into the item_key and item value columns of the people table thus: item_key would be filled with 'cor_tbl_txt' and the item_value would be filled with 3478 ( or whatever the id of the text fragment is).
Again, there is no explicit declaration of what a particular chain must contain and care should be taken in the front end to prevent orphaned record and malformed chains.
This chain is fixed to a record by its first member or 'head' which is attached to the record in the exact same way as a normal data fragment.
This method allows us to endlessly nest and link fragments according tot he particular needs of the recording system.
Stu may develop a way to create these chains as parseable heirachies, but this is not yet incorporated into the core ark code. In this event, chains would be either heirachy OR loose chain, we would not enforce heirachy.
Macro Level Data - Working with large numbers of records
Groups are a way to store static groupings of 'items' in the Ark model. Groups are in fact a module with each group being identified witha key=val pair in the format grp_cd=XXX. The group is stored in the XMI table of the database which permits cross module linkings. The group may then have further data attached to it as it is an item itself. This might include analystical text/interpretation. It is a way fo starting to aglomerate fragments fo data into ever larger units and provides a means to attach interpretation to these larger units.
We could consider making groups a full item with their own module. This would give each group and itemkey=itemval pair, which would facilitate linking further data to the record, for instance a description and interpretations. Using this model, it would then be possible to store groups and the items in them in the cor_xmi table without any problem. In addition it would then also be possible to group groups using the same reasoning.
Filters are a means of selecting out subsets of the Ark dataset. Filters may be layered one above the other to provide very refined data sets. These data sets might then be viewed as a 'view' as set out below (in tandem with some datatypes), or they might be saved out as static groups. It will also be possible to save out a given set of filters for re-use int he future.
The fundamental difference of saving the filters as filters or as a group is that the group will be static and the filters will be dynamic and subject to change in the records.
The dataset is the result of a series of filters or the members of a group. It is an array of itemvalues on the model of the results_array. The dataset should never be saved itself. It could be saved out as a group or the filters that made it might be saved.
A dataset would then be available to the suer to be viewed by means of a 'view'.
Filters or Group | dataset | 'view' = (dataset + datatypes) | 'macro viewer' (xhtml table/map/csv/midas xml)
Data views are a combination of datasets and datatypes. The data types define what data is to be displayed for each record and the dataset is an array of itemvalues which go to make up the rows of the view.
Effectively this is a list of the types of data to display for each record in the current view. Thus in the case of the 'regist' view, we would typically display a short_desc field and a limited amount of meta data for each 'item record'.
Thus this list is critical to explaining to the page what information should be contained in the view.
Furthermore, each datatype element of the view should contain enough meta data about the data that it is possible to automatically retrieve the relevant data from the the cor_tbl of that data class as well as displaying a meaningful alias for the data int eh current language.
In terms of the 'regist' example above, one column would be the 'short_desc' column. This means that 'short_desc' is a datatype of the view 'regist'. This datatype should hold enough information that it is possible to retrieve the alias 'Short Description' from the cor_lut in which the texttype 'short_desc' resides. In addition, it should be possible to get the 'data fragment' of type 'short_desc' from the cor_tbl_txt for this particular itemkey=itemval pair.
This would mean that for any given view, we would hold an array of these datatypes which can be extensibly turned into say a column in a tabular data viewer, or perhaps labels on a plan.
In addition to the datatypes, the view will need to know what records to display. This will be in the format of a php array of itemvals for the given itemkey although conceivably this could be an array of itemkey=itemval pairs.
In terms of storing a view, it may be desirable to be able to store the filters used to achieve the subset of the data. It certainly is not desirable to store the dataset (see above). Therefore, the view handling script should probably be able to handle groups and filters as the originator of the dataset. The view should probably call the dataset needed based on
Web Output Model
A page within the ark xhtml output model is a form of template and addressing system. The page is created in the root level folder of ark and has a code folder located within the php folder. This means that each page is a discreet block of code that can be included or excluded according to for example security settings. This also allows for each page to have partuclar layout characterisitcs.
Views enable a range of content to be displayed within a page. In this way, a variety of different forms might be displayed within the remit of the data entry page.
Skeleton scripts (or Forms) are a means of organising smaller global scripts into module or page specific formats within a given view. The basic aim of these scripts is to allow intelligent extensible layout to take place. Classic (and quite different uses) of the skeleton script are the 'detfrm' and the 'micro_view'.
In the case of the detfrm this is essentially a module specific skeleton which organises subforms into a layout which mimics the paper layouts. This layout is currently treated as a module specific issue.
In the case of the micro_view, this skeleton arranges subforms into a meaningful layout for all records regardless of module according to settings for that module.
These are script fragments that perform both data display and data entry/editing functions. Some of them are more global by their nature and would thus be held in the relevant page code folder. Alternatively they might be considered as too modular for this and thus would be included in the module code folder.
Obviously the ark module is to try to standarise data display as far as possible thus pushing the code into the page wherever possible.
MLC and PLC
Whether the content you are outputting should be coded as mod or page level content is discussed in more detail in the discussion about module level vs page level content.