Customization Guidelines
This wiki article will outline best practices for banks customizing ATiM. When building or modifying forms (and related tables) the following guidelines must be followed to ensure successful upgrades when new versions are released. For general recommendations on how to install, customize and migrate data to ATiM see the wiki page ATiM Project Outline.
Contents |
Tables
- Do not drop existing fields.
- If you do not require a field in your local installation turn the form field off but leave the table field.
- Do not rename existing fields.
- Renaming fields can break forms in ATiM. If you need a new field add another instead of renaming one you don't.
- Prefix all new fields and tables with a local identifier to help prevent future conflicts.
- Fields within new tables do not need to be prefixed but you may want to. If all new fields have your local identifier it is easier to track.
Language Aliases
- ATiM is a multi-lingual application and as such everything is referenced through an alias so the system can display the correct text in the preferred language to the end user. If you are adding new language aliases use the same rule as adding new fields - prefix all aliases with a local bank identifier. This ensures your local changes are protected from future updates.
Example: You want to change the help message for the field "Date of Birth".
Technically, there are multiple ways to alter this help message but to protect your changes from future updates alter the `language_help` alias to something like: <bank_prefix>_help_<fieldname> and then add the appropriate translated value to the `i18n` table. If you were to keep the existing alias and only update the translated value your change might be lost if a future patch also updated the translation for that alias.
Structures
Structures, more commonly known as forms, should only be added in certain cases. Examples include:
- You have a new 'Annotation' event such as a lab report, screening event, study, other clinical data not already present in ATiM.
- New treatment, sample, aliquot, consent, or diagnosis form not already present.
Fields
Altering Existing Fields
Field attributes are highly customizable. Some of these attributes can be easily altered without impacting system operation. They are:
- On-screen label
- Help information
- Placement on a structure. This refers to the column, ordering, and whether the field appears on its own line or in line with other fields
- Set which views (Add, Edit, Index, Search, Datagrid, Detail) on which the field appears
Other changes may cause immediate problems or future issues with upgrading. Use care when altering these field attributes:
- Field type (Radio buttons, select list, text area)
The following attributes should never be changed for existing fields.
- Public Identifier, Plugin, Model, Tablename, Field
Adding New Fields
A new field should be created whenever an element does not exist in ATiM, or the existing element is not a good match. In these cases create a brand new field to store your data. Be sure to prefix your new field with a bank identifier.
For example, assume you wish to collect the participant's hair colour. This field does not exist in ATiM and will need to be added. Do NOT take an existing field and alter it.
Validations
Except in a few rare cases, custom validations may be added to any new or existing field. Validations that should not be altered are:
- Participant Identifier must be unique
- Any barcode field (Aliquot, Storage Entity) must be unique
Value Domains and Permissible Values
Many fields in ATiM have existing value domains (a set of values) pre-defined. In most cases, a list of permissible values for a field can be extended (by adding new ones) or reduced (by de-activating unused values).
If an entirely new set of lookup values is desired, build a new value domain and structure field.
