Controls

RecordOwner and systimestamp

The RecordOwner and systimestamp controls are special text controls that are added to each scheme.These controls default to control ID 1 and 2, respectively, and are not displayed in the scheme layout edit page or the ingestion form. It is a member of collection ID 0, which means that it is not displayed in the scheme layout edit page or the ingestion form. When the ingestion form is submitted, it stores the record’s creator and the time.

The Ingestion Process

While KORA controls are involved in a variety of functions, their core use is ingestion. In order to understand the flow of data through a control, one must have a sense of what occurs during the ingestion process.

When a user visits the [ingest o]ingestObject.php page, the ingestion form ensures that both the project ID and scheme ID are provided. The ingestion form also verifies that the current user has the appropriate permissions to ingest content into that project. Once the record model instantiates each control within the scheme, it prints out the input method for that particular control. Each control class is responsible for printing out its own part of the ingestion form and populating it with any default values. When a user fills out information in a control, the control will validate itself and check for errors.

Once the user enters all required and additional information and there are no errors, the user will click “Submit Data” to submit it. The record model will then attempt to ingest the record into the database. If successful, the user will be redirected to the “View Record” page to view the new record.

Things to Consider When Writing a New Control

There are several important factors which must be taken into consideration when writing a control. The first and most critical is to remember that a scheme may have more than one instance of a given control; thus, any input fields must have unique names/ids. A good way to guarantee this is to implement the control's ID into any field which the control uses.

Another concept is that the user input sections must reside on one page – that is, using HTML forms to submit and process information is impossible. As such, any dynamic content (such as building a list) must be done with Javascript. Remember that Javascript functions will require unique names as well.

It is important to note that if a control shares a good deal of functionality (and potentially code) with another control, it is perfectly acceptable – encouraged, even – to derive one control from another's class and overload only the code which changes. For an example of this, please refer to controls/textControl.php and controls/multiTextControl.php. It is generally a good idea to replicate methods that other controls implement and to take advantage of abstract functions in the controls/control.php class.

Whenever doing database queries, always remember to sanitize any user input]. The escape function in utilities.php is used throughout KORA to sanitize database queries. This includes even things like the passed project/scheme ID. Obviously, the project ID will need to be used unescaped in formulating the name of the Project Tables; to prove that is is legitimite, consider casting it as an integer and querying the scheme table with an escaped version of the project and scheme IDs to see if they correspond to a legitimate scheme.

When adding a new control file to the KORA code, the control collection needs to be updated at http://kora.matrix.msu.edu/systemManagement.php by clicking 'Update Control List'. KORA will not be aware of any new controls until the control collection has been updated.

Writing a New Control

When writing a new control, it must extend/derive from the Control class; as such, it must include the controls/control.php file. It must contain versions of all functions defined in that class. It may contain as many other functions as the author of the control deems necessary, but it must contain the core set. For a detailed explanation of the functions and how they work, consult the comments in controls/control.php, but here is a brief overview of the essential functions:

• Constructor. This must accept four arguments – a project id, a control id, a record id, and a record id. The contructor is responsible for initially loading the control's value (if any) and options.
• delete(). This function is responsible for deleting the value(s) corresponding to a particular control. If a record id was provided to the contstructor, this should delete only the value corresponding to that record. If no record id was provided, however, the data for all objects corresponding to that control (in the provided scheme) should be removed. This function is responsible only for removing data. Removing data corresponding to the control itself in the database is handled by other functions.
• display(). This function displays the user-input form for the control. Remember to take into account the considerations mentioned previously, such as the necessity for unique HTML input field names.
• displayXML(). This function is responsible for returning an XML string corresponding to the control's value. This function has no meaning if a record id is not provided, and as such can return a blank string in such an instance.
• getName(). This function returns the name displayed inside KORA to describe a control. The Text Control displays “Text”, for instance. Please avoid using the redundant word “Control” in the return value of this field.
• getType(). This function returns a slightly longer name for the control used internally. The Text Control returns “Text Control” for this field, for instance.
• ingest(). This function processes the submitted information from $_REQUEST variables as returned in from the form created in the display() function. This function handles both new ingestion and editing, and should be able to differentiate between the two.
• isEmpty(). This function returns a boolean corresponding to whether or not data was ingested into this control. This is used in the ingestion class to determine if at least one control received data.
• isXMLPacked(). This static function returns a boolean corresponding to whether this control stores information in the value column in the database in an XML format [true] or in a plain-text format [false].
• validateIngestion(). This function is used to ensure that the provided input to a control is valid – that is, that any data provided meets any restrictions or criteria and that if the control is required, that a non-empty value was provided.
• initialOptions(). This function returns a string corresponding to the initial XML value with which the options column in the database corresponding to the control should be populated. This function is only called upon control creation.
• setXMLInputValue(). This function formats ingested data into XML for storage in the database.
• showData(). This function retrieves and visually formats the value for use in display.
• storedValueToDisplay($xml, $projectid, $controlid). This function accepts the stored value corresponding to a control from the database (although the variable name is $xml, this argument accepts whatever would be stored in the value column in the database, be it XML or plain text). The projectid and controlid arguments are provided in case the control needs to access its options to determine aspects of the display. The function returns a string corresponding to a graphical table or other format suitable for displaying in internal search results for the control.
• storedValueToSearchResult($xml). This function accepts the stored value corresponding to a control from the database (although the variable name is $xml, this argument accepts whatever would be stored in the value column in the database, be it XML or plain text). From this, it returns a string value or an array of string values corresponding to the object's value suitable for returning in the search results through external libraries such as KORA_Search. The primary aim of this function is to translate any information