Performance activity elements

Terminology

Term	Description
Section	Performance activities can be either single section activities (one implicit section without a name) or multi-section activities (the activity is broken up into separate named sections). A section is a container for elements and is represented by a single page with a submit button for a participant when they take part in the activity. Multi-section activities have navigation to allow participants to navigate between sections. All elements within a section are submitted at the same time so validation applies to the section as a whole and progress and availability are associated with the section rather than individual elements.
Element	An element is a single piece of content within a section. Elements can be questions (where the participant must respond) or non-respondable elements (such as a static piece of text where no participant response is required). Currently when an element is added it is only used once, within the section where it has been added. However the design allows for the creation of an 'Element bank'. In that model elements can be created as standalone items in the bank, and then associated with one or more activities. This will allow complex elements to be reused.
Section element	Because elements are designed to be reused, the section element links an element to a specific section in an activity (to support a many-to-many relationship). The section element record also tracks the sort order of the element. In the future when elements are reusable it might make sense to move some other element metadata into this table if it may differ per element use. For example the is_required field that currently sits on the element itself.
Element identifier	Since there is no element bank at present, element identifiers provide a way to associate multiple different elements together for reporting purposes. Element identifiers are stored in a single global table of unique identifiers then linked to individual elements via a foreign key. When selecting reporting IDs, users only see reporting IDs that are already in use in activities that they have permission to report on. Element identifiers are called Reporting IDs on the front end.
Element response	An element response represents a single answer to a single question element by a single participant. Internally it links a section element record (the usage of the element in the activity) with a participant instance (the person involved in the activity). Response data is stored in a TEXT field in a JSON encoded format that is specific to the particular element type being responded to. The element plugin is responsible for decoding the response when it needs to be displayed. Responses are captured at a point in time. In some cases responses can be updated, in which case the original record is overridden. If the user is required to repeatedly respond to an activity this would be solved using repeating via scheduling and creating multiple subject instances, at which point each response would be stored against a different participant instance. Activities provide the option to save as draft - when this is done validation is not performed but the data is still saved to the database as before. The only way to tell between a draft and submitted response is by the progress status of the participant_section - if it is 'In progress' then the responses are draft, if it's 'Complete' then they've been submitted. It follows that you can't save a new draft of a completed activity - all you can do is resubmit it.

Element plugin structure

Elements are implemented as a sub-plugin of the 'mod_perform' component. That means all code relating to a specific element is contained within the plugin's code folders. The core performance activity code will request information from the plugin when attempting to achieve a specific goal.

The general distribution of responsibility is that core code handles general behaviour such as:

Building the admin pages where elements are added
Providing a way to add an element
Saving changes to the section
Display the end-user activity form, including end user navigation
Handling form submission, including overall validation
Storing response data

On the other hand the core code requests information or delegates tasks to specific plugins as required to complete these tasks. That includes:

Requesting a vue component from the element that can handle creation and editing of the admin view of the element
Requesting a vue component for a preview view of the element
Requesting a vue component for a read-only view of the element
Requesting a vue component for the participant's view of the element in the activity form
Requesting a vue component for the participants' view of a response in the activity form
Server side validation of the response
Decoding of the response from JSON encoded form into a usable format

Although the core code stores the element data it does so in a JSON encoded format determined by the element, then passes the data back to the element when required, so the core code doesn't know anything about the format of the data.

Respondable vs non-respondable elements

There are currently two types of element plugins; question elements and non-respondable elements. Non respondable elements are different in that they do not require a response from the end user and are therefore shown the same to all participants. Question elements must implement the respondable_element_plugin interface which requires them to implement some extra methods.