View source for Developing Subforms

[[Subforms]] are the key building blocks of the ARK user interface. Therefore this is probably one of the key areas we expect plugins and community contributions. These notes set out some of the key principles of developing a new subform.

==Overview==

Make sure that your code has the correct header block at the top. Do not just copy some old code. Many older subforms are badly formed.

Process of user input should go at the top. This is followed by error reporting and by data and form display.

Your subform will receive the following live vars

*$sf_state - a string supplied to the subform, but usually based on the settings found in the sf_conf
*$sf_conf - an array of settings for the subform.
*$sf_key - string, an ARK compliant itemkey
*$sf_val - string, and ARK compliant itemvalue

The sf_key and $sf_val are used in order to allow a subform to display data relating to an item other than the main item of the page. Always refer to these keys within a subform and not the main item_key of the page.

==Settings==

More detailed information about how to configure a subform can be found in the administration manual [[subforms]] page. It is important that developers (that's YOU!) conform to rules for settings in subforms so that the architecture does not get all messy and impossible to follow.

Settings will be passed to the subform by the page in the form of an array called sf_conf. This contains the obligatory and optional settings set up for the subform in the settings file. These settings are given in more detail int eh administrators manual.

Optional settings are used if stuff specific to your subform. You must make your subform work even when your op setting is NOT set. This may be a case of setting a default behavior or it may be a case of returning an error for admins to update their settings.

==sf_states==

Subforms are set up to behave differently when called in different environments. Your form should be set up to display data int he main states, in all other states, the default should be used in order to give meaningful feedback to the administrator.

The $sf_state is supplied to the subform as a live string var. The subform then selects which code to use for this state using a switch statement. This means that several different states can make use of the same code.

States can be of three types:

*auto
*transclude
*overlay.

Automatic states are set using a combination of three factors: the column type, the 'view state' and the 'edit state'. This evaluation is performed outside of the subform by the getSfState() function.

====Column Type====

This differentiates primary (wide) columns and secondary (narrrow) columns. This enables us to present data in different ways depending on the approximate width of a column.

====View State====

Min establishes a state for minimised forms. Typically this is just to display the sf_nav (see below), but it could display some very limited information like a number of records. Max establishes fully open subforms.

====Edit State====

View sets the subform to present data in an uneditable way. Edit presents data in an editable format. Enter sets up the form for data entry. This would allow different views for data entry work or casual edits

===Automatic States (Resulting Combinations)===

The following combinations are therefore possible. Things like min_edit are impossible.

*p_max_ent
*p_max_edit
*p_max_view
*s_max_edit
*s_max_view
*min_view

===Transclusion===

When the data from a subform is called into an external web page, this is called transclusion. In this state, the subform will send back its data in a neatly wrapped package. It is important to remember that the subform must wrap its content within a fully formed xhtml page.

*transclude

===Overlays===

Subforms may also be used as popup overlays. Typically this is for dialogues, but could be for any purpose really. In order to design a subform to work as an overlay, it will need to wrap the content into a fully formed xhtml document much like transclusion.

*overlay

==sf_nav==

Within the code for a particular state, it may be desirable to set up a navigation bar. In all of the auto states, a navigation bar should be included. This can then be turned off by the administrator using the sf_conf. If you do not supply a nav bar, this will confuse the admins.

==CSS Classes==

Optional CSS classes can be applied to subforms so that they can be displayed atypically. The default class you should apply is the mc_subform class. This establishes the standard subform CSS across the site. Should an admin require specific CSS for a form, this can be set up from within the sf_conf.

[[Category: Developer]]