• InspectorFormConfiguration

Inspector Form Configuration

InspectorApp

• Contents

  1. Inspector Form Configuration
  2. Directory Structure
  3. The Main Loader
  4. Field Definitions
     1. Field Definition File Format
     2. Field Definition Elements
  5. Form Definitons
     1. Form Definition File Format
     2. Form Definition Elements
        1. Detail and Form Definitions
           1. Tab Definition
        2. List Definitions
           1. Form Field Definition
  6. Template Definitions
  7. Report Definitions
     1. Report Definition File Format
        1. Typical Field Options for Report List
        2. Report Filter Options
  8. Examples

Directory Structure

• The appropriate site dependent settings are loaded in lib/couchdb.rb with the following lines:

  module Couchdb
    require 'couchrest'
    require "forms/#{Settings.SXS.Couchdb.SiteName}/config.rb"
    ...

  I.e. the config.rb file under lib/foms#{Settings.SXS.Couchdb.SiteName} loads all of the necessary files used in the configuration. As a convention, the following files are stored in the directory:

  config.rb                 - the main loader
  fields-tag.rb             - field definitions for Item records
  fields-scan.rb            - field definitions for History records
  form-tag-#{form_name}.rb  - 1 or more files for Item forms
  form-scan-#{form_name}.rb - 1 or more files for History forms
  report-#{form_name}.rb    - 1 or more files for reports

The Main Loader

• The main loader, config.rb has to have the following structure (shown with a typical example):

  module Couchdb::CouchdbMeta
  
    require "forms/generic.rb"
  
    require "forms/#{Settings.SXS.Couchdb.SiteName}/form-tag-inspection.rb"
    require "forms/#{Settings.SXS.Couchdb.SiteName}/form-tag-surveillance.rb"
    require "forms/#{Settings.SXS.Couchdb.SiteName}/form-tag-firerateddoor.rb"
  
    require "forms/#{Settings.SXS.Couchdb.SiteName}/form-scan-destructive.rb"
    require "forms/#{Settings.SXS.Couchdb.SiteName}/form-scan-surveillance.rb"
    require "forms/#{Settings.SXS.Couchdb.SiteName}/form-scan-firerateddoor.rb"
  
    require "forms/#{Settings.SXS.Couchdb.SiteName}/fields-tag.rb"
    require "forms/#{Settings.SXS.Couchdb.SiteName}/fields-scan.rb"
  
    require "forms/#{Settings.SXS.Couchdb.SiteName}/report-inspection.rb"
  
    @@forms = {
  
      tag: {
        inspection:     TagInspection.getForm,
        surveillance:   TagSurveillance.getForm,
        fireratteddoor: TagFireRatedDoor.getForm,
      },
  
      scan: {
        "urt-destructive":   ScanDestructive.getForm,
        "urt-surveillance":  ScanSurveillance.getForm,
        "urt-firerateddoor": ScanFireRatedDoor.getForm,
  
        sort_: { # scan.sort_
          "updated_at": "Update time",
          "_id": "Create time",
          "form_": "Inspection type",
          "reference_number": "Reference number",
          "risk_level": "Risk level",
          "status": "Status"
        }
      }
    }.with_indifferent_access
  
    @@fields = {
      tag:  FieldsTag.getFields,
      scan: FieldsScan.getFields,
    }.with_indifferent_access
  
    @@reports = {
      inspection:  ReportInspection.getReport
    }.with_indifferent_access
  
    def self.getForms
      return @@forms
    end
  
    def self.getFields
      return @@fields
    end
  
    def self.getReports
      return @@reports
    end
  end

  Replace, remove only appropriate parts to create a new configuration. The module globals and the module functions are called from outside to get the configuration elements. Using the hash modifier with_indifferent_access is very important.

  NOTE: Generally symbols or strings can be used as keys in all hashes in the definition files, but only strings, booleans or numbers as values, i.e. no symbols.

Field Definitions

• The files fields-tag.rb and fields-scan.rb contain definitions of the fields commonly used in all type of forms. Note that both type of records have the following fields regardless of they are defined here or not:

  _id        - unique database id
  _rev       - database revision
  form_      - name of the form referring this specification
  created_at - creation time of the record in ISO format
  updated_at - last update time of the record in ISO format
  created_by - creator of the record (email address)
  updated_by - updater of the record (email address)

Field Definition File Format

• The files have to have the following format:

  module Couchdb::CouchdbMeta::FieldsTag
  
    @@fields = Hash
  
    def self.getFields
      return @@fields
    end
  end

  TheHash keys are the fields of CouchDB/PouchDB (hereinafter database) records, while the Hash values contain the definitions of the fields.

Field Definition Elements

• The following elements can be used in the field definition:

  Definition Key	Description	Notes
  label	Human name of the field	It is required if no custom template is used
  type	Field type, one of form_, select, checkbox, textarea, text	Optional, default is text
  attributes	HTML attributes as required, unique-value, multiple, step, min, max, rows	Optional. Use true or false for unary attributes, e.g. required.
  options	HTML options list as hash for select types, key = database value, value = human name	Required for select type fields
  htmlType	HTML type attribute for simple input fields, i.e. text type. Typically number	Optional

Form Definitons

• Three types of forms (detail, form and list) and sorting configuration have to be defined in the form definition, furthermore custom templates can be defined.

Form Definition File Format

• The files have to have the following format:

  module Couchdb::CouchdbMeta::TagInspection
  
    @@form = {
      name: "Form Name",
      detail: {
        tabs: [
          Tab0Hash,
          Tab1Hash,
        ],
        templates: { # detail.templates
        }
      },
      form: { 
        tabs: [
          Tab0Hash,
          Tab1Hash,
        ],
        templates: { # form.templates
        }
      },
      list: {
        fields: [ # list.fields
          FieldsHash
        ],
        templates: { # list.templates
        }
      },
      sort_: SortConfigHash
    }
  
    def self.getForm
      return @@form
    end
  end

  NOTES:

  1. Currently only tabbed format can be defined for detail and form.

  2. Custom templates can be defined here, otherwise the standard templates defined in form.service.js can be used.

Form Definition Elements

• Definition Key	Description	Notes
  name	human name of the form	Value of the form_ in the database is defined by the hash key in config.rb (e.g. urt-inspection above).
  detail	Definition of the detail view
  form	Definition of the input form
  list	Definition of the list view
  sort_	List sorting options as hash	Hash key is the database field name, value is the human name of the sorting field

Detail and Form Definitions

• Both types have the same tabbed format:

  Definition Key	Description	Notes
  tabs	Array of tab definitions
  templates	Custom templates	Optional

Tab Definition

• Definition Key	Description	Notes
  title	Title of the tab	Doesn't appear anywhere on Android
  icon-on	Ionic icon for selected tab
  icon-off	Ionic icon for unselected tab
  fields	Array of form fields definition

List Definitions

• Definition Key	Description	Notes
  fields	Array of form fields definiton
  templates	Custom templates	Optional

Form Field Definition

• Definition Key	Description	Notes
  name	Database name or an array of database names	Array is not allowed for inputs (form). The database names have to be defined in the field definition files above.
  template	Name of the template to be used	The template to be defined in the current form definition or a global template from form.services.js can be used.

Template Definitions

• Templates are used to render individual fields or field groups on detail, input or list views. The templates are searched by name in the following precedence:

  1. In the form definitions, as mentioned above

  2. In the appropriate section (detail, form, list) of the templates global variable in form.service.js.

  3. In the top level of the templates global variable in form.service.js. (Currently no one is defined there.)

  
  The templates are Ionic/HTML codes, with the following variable interpolation:

  Form type	Variable name	Variable value	Notes
  detail, list, form	label	field label	Only if the form field definition contains a single database field.
  detail, list	value	field value	Only if the form field definition contains a single database field.
  detail, list	l_{field name}	field label	Only if the form field definition contains an array of database fields.
  detail, list	{field name}	field value	Only if the form field definition contains an array of database fields.
  detail, list, form	scope	current JavaScript scope	It is possible access the curent record and a couple methods through the scope
  detail, list	values	options_{random key}	array of dereferenced values are passed through a random scope variable if the field contains an array and has attribute multiple
  form	table	tag or scan
  form	id	record's unique id
  form	htmlType	HTML input type from field config
  form	attributes	HTML attributes	Singe string composed from attributes
  form	model	name of the angular JS model variable	e.g. tagEditData
  form	form	name of the the HTML form
  form	field	database name of the current field

  
  NOTES:

  1. For detail and list the template name is default if not defined in the form configuration.

  2. For form the template name is input if type is not defined in the field configuration, otherwise taken from type.

  3. For form _unique appended to the template name if the attribute unique-value is set.

Report Definitions

A Report Definition contains the list of fields which have to be appear on the detailed (detail) or summarized (list) report results, furthermore the definition of the report filter fields.

Report Definition File Format

One file contains the definition of on report.

• module Couchdb::CouchdbMeta::ReportInspection
  
    @@report = {
      name: "Report Name",
      detail: {                  # Detailed report definition
        tag: {                   # Field lists for location (tag) records
          form_name1: {          # Field list for location records with _form = 'form_name1'
            fields: [
              { name: :name1 },
              { name: :name2 },
              ...
            ]
          }
        },
        scan: {                 # Field lists for inspection (scan) records
          form_name1: {         # Field list for inspection records with _form = 'form_name1'
            fields: [
              { name: :name1 },
              { name: :name2 },
              ...
              ]
          },
          form_name2: {         # Field list for inspection records with _form = 'form_name2
            fields: [
              { name: :name1 },
              { name: :name2 },
              ...
            ]
          }
        }
      },
      list: {                           # List report definition
        fields: [
          { table: :tag, name: name1 }, # Report column definition for location fields
          ...
          { table: :scan, name: :name2, # Report column definition for inspection fields
            format: :datetime,          # Optional format is not used yet
            header_options: {           # Optional HTML options for the report table <th> tag
              ...
            },
            data_options: {            # Optional HTML options for the report table <td> tag 
              ...
            }
          },
          ...
        ]
      },
      filter: {                        # Filter definitions
        tag: [                         # Location filter fields
          { name: :name1, options },   # Location filter field definition with optional options
          { name: :name2, options },
          ...
        ],
        scan: [                        # Inspection filter fields
          { name: :name1, options },   # Inspection filter field definition with optional options
          { name: :name2, options },
          ...
        ]
      }
    }
  
    def self.getReport
      return @@report
    end
  end

Typical Field Options for Report List

Typical options are HTML with and class, but any others can be used. E.g.

•     list: {
        fields: [
           { table: :scan, name: :updated_at,
            header_options: {
              width: '15%'
            },
            data_options: {
              class: 'text-nowrap'
            }
          },
      ...

Report Filter Options

• Definition Key	Description	Notes
  required	The field will be a required field on the filter form of set to true
  as	The as options used in a simple form field, see in Simple Form - Available input types	There are two simple form custom inputs, defined in app/inputs: between_dates and 'between_numbers, for range inputs
  default_sort	The field is part of the default report sorting, the value defines the sort direction (:desc or :arc)
  filter_type	Not exact match, but simple matching (SQL Like) will be used if value is :match	Currently only :match is allowed

Examples

• config.rb

  fields-scan.rb

  fields-tag.rb

  form-scan-firerateddoor.rb

  form-tag-surveillance.rb

  report-inspection.rb