Collections describe the parent level in the record structure of tables and table types. The configuration entries in a Collection Configuration relate to Service records in one respect only. That is, you would expect to find entries in the Collection record for services such as Datagrid or Datatree that overwrite the values in the Service record.


; Config File for a Gijgo Grid

[datagrid]

       dataurl = ''

       

       [datagrid:columns:0]

               field = 'id'

               title = '9999:Id'

               headerCssClass = 'strong'

               width = '50'

               filterable = false

               align = 'right'

               order = 'a'

               sortable = false

               tooltip = '9999:Id'


       ; Top buttons

       [datagrid:topbuttons:addbutton]

               class = 'danger'

               icon = 'plus'

               title = '100:Add'

               formid = 'columnform'

               formtype = 'columnform'

               order = 'a'

       

……..


       [datagrid:topbuttons:helpbutton]

               class = 'info'

               icon = 'info'

               title = '85:Help'

               order = 'x'


Thus dbcollection has service entries for virtually all the Services used for display and entry of data.

Common

All Collection and Model records will have a Common section. This, as the array key suggests, provides common information for this table via the stdModel() method to all activities in the system.

Most of the key/value pairs in a [common] section are intuitive. But it is worth explaining a few.


You will note how level is expressed as a string represented by 3 sets of double digits separated by colons. These are the default values for Read, Write and Delete used by the Access Control Level system (ACL) for this table. They can be overwritten at model and record level.


The value attached to “fieldsused” is a string of fieldnames that are used by this table. At Collection level, you would expect that all fields in the table schema are represented.


Values provide the default sort order and which field is used for version control.

Fields

All Collection and Model records will have a Fields section. This, as the array key suggests, provides information about the real or schema fields for this table via the stdModel() method to all activities in the system. Most of the key/value pairs in a [fields] section are intuitive. But it is worth explaining a few.


The most important information stored in the Fields subarray for an individual field, is the information about how the Field will be handled when record data for the field is written to the database. The majority of the fields are treated as strings and the final decision about format and size is left to the Redbean PHP ORM. In dbcollection, the two different fields are Revision (c_revision) and Document (c_document) which are ‘integer’ and ‘json’ respectively. So that this statement makes sense, we must consider the process of writing a record to the database.


As far as possible we have tried to ensure that Cliqon has a common interface for writing records to the database after a form is submitted. All forms are submitted using AJAX. All forms are submitted using the REST API and can accommodate a cross domain / remote json (jsonp) arrangement. Forms can be submitted utilising JSON Web Tokens (JWT). Some forms are submitted via the API Controller and some via the AJAX Controller. All common forms are responded to by $db→postForm($args).


To simplify and summarize the procedure in postForm(), the XHR Post containing FormData is validated and then split into real schema fields (starting with c_) and document or virtual fields (starting with d_). If a valid  record ID has been included in the FormData (value greater than 0 / zero) then an update action is assumed (it should be noted that Redbean ORM does not make this distinction).


If a record insert action, the fields required for this Collection are retrieved via the Model. The value in FormData is used but if the key does not exist in the FormData array, the default value (defval) is used. The value of the ‘required’ key in the Collection > Field > Configuration should reflect the value in the Database Schema (if the Schema has been created manually or via the installation procedure).


If a record update action, the fields required for this Collection are retrieved via the Model. In most cases values in the real fields that are contained in the FormData Post will overwrite the existing record value. However this is handled differently when the Post contains virtual values (fields commencing d_). The postForm() Method must retrieve the JSON string contained in the Document field (c_document) and update it by a process of conversion from JSON to array, update it and then convert the array back to JSON.


As postForm() processes each field key / value pair it sends it for formatting to the required format. This is a two step process. Firstly, the fields with a specific function are processed. Currently there are four fields that require special processing – Who Modified (c_whomodified), Last Modified (c_lastmodified) and Revision (c_revision) or Version (c_version).


Who Modified – the current administrative operator is introduced

Last Modified – the current date and time is introduced

Version – The numeric value of the version number of this record is updated and a copy of the record before update is copied to the archive collection

Revision – The numeric value of the version number of this record is updated.


All the other fields of the Post are then sent to the dbEntry() Method to have the value formatted according to the value in ‘dbtype’ for that field. Current possible values include:


    • password – the string value is converted to a Password Hash
    • boolean – converts ‘false’ to 0 and ‘true’ to 1
    • number – formats a number according to the rules defined in the main configuration file
    • date – formats a date into year – month – day values
    • datetime - formats a date into year – month – day and then hours and minutes values
    • slugify – converts a string into a slugified value. That is it converts spaces to hyphens, converts accented characters to their ascii values and generally tidies up the string so that it can be used as a ‘slug’ or reference.
    • json – the function will receive a JSON string that has been suitable ‘escaped’ to POST. It reverts the string to raw JSON and then tests the valid nature of the JSON before allowing it to be written to the database.
    • toml – the function will receive a plain text string that has been suitable ‘escaped’ to POST. Like the JSON test above, it will ensure it is valid TOML  before allowing it to be written to the database
    • string – this is the default action and no formatting is carried out


As a general rule, the Client AJAX routine is informed of the success of the write (or otherwise) and a success alert is displayed. The display will then be updated to reflect the new or changed data.


The datagrid for Collections includes all the facilities to create a new configuration record or edit an existing one. As was explained previously the Admin system can accept Collection records as plain text files with a .cfg extension which, when used, are located in /models subdirectory.


When you create or edit a Collection record, you will notice that the value of ‘Reference’ and the file name should be the same. Thus the database record with reference “dbcollection” would be found on the file system in /models as dbcollection.cfg.





Created with the Personal Edition of HelpNDoc: Easily create Qt Help files