Datamanager 2 Form Manager core class.

This class controls all form rendering and basic form data i/o. It works independent of any data storage, getting its defaults from some external controlling instance in the form of a type array (f.x. a datamanager class can provide this). The list of types is taken by-reference.

The form rendering is done using the widgets and is based on HTML_QuickForm.

package midcom.helper.datamanager2


__construct (\midcom_helper_datamanager2_schema $schema, array $types, $state)

Initializes the Form manager with a list of types for a given schema.



\midcom_helper_datamanager2_schema&$schema The schema to use for processing. This variable is taken by reference.


array&$types A list of types matching the passed schema, used as a basis for the form types. This variable is taken by reference.


_translate (string $string)

This is a shortcut to the translate_schema_string function.
see \midcom_helper_datamanager2_schema::translate_schema_string()



stringThe string to be translated.


stringThe translated string.

compute_form_result ()

This function computes the form result based on the button clicked and on the current validation result.

Validation is only checked when save/next has been clicked; if it fails, the exitcode reverts to 'edit'.


stringOne of 'editing', 'save', 'next', 'previous' and 'cancel'

create_renderer (string $name)

Creates a new instance of the renderer specified by $name.

It must be a valid renderer name of the renderers defined in the renderer subdirectory of this component. The file loaded is renderer/$name.php, while the class instance created is midcom_helper_datamanager2_renderer_{$name}. The class must be default constructible and will be available in the renderer member of this class.

If name is 'none', no renderer instance is created, instead the default QuickForm Renderer is activated.

You cannot create custom renderer instances with this function, you need to create the instance manually and set it using set_renderer().



stringThe renderer to create

display_form ()

This call will render the form.

display_view ()

This function displays a quick view of the record, using some simple div based layout, which can be formatted using CSS.
todo Make this better customizable
todo Factor this out into a separate class This function should be deprecated.

freeze ()

Special form freeze handling.

get_clicked_button ()

This is a shortcut function which allows the calling application to determine the pre-validation return code of the current form.

This function does not do any form specific operations. It is primarily geared on shortcutting out of existing processing chains to avoid the expensive controller startup operation in cases where cancel or similar buttons are clicked.


stringOne of 'edit', 'save', 'next', 'previous', 'preview' and 'cancel'

get_submit_values ()

Use this function to get the values of submitted form without going through a storage backend.


arraythe submitted values.

get_value (string $field)

Get the user input for one particular field in the storage format



stringThe field to query

initialize (mixed $name)

This function fully initializes the class for operation.

This is not done during the constructor call, to allow for full reference safety.

todo Refactor into subfunctions for better readability.



mixedThe name of the form. This defaults to the name of the currently active component, which should suffice in most cases.


booleanIndicating success.

process_form ($ajax_mode)

Call this before any output is made.

It will process the form results, if applicable, and return an according exit code.

This indicates which (if any) submit button was pressed. If 'editing' is returned, this means that either there was not data submitted yet, or that form validation has failed.

//This call ensures that MidCOM runs uncached.




stringOne of 'editing', 'save', 'next', 'previous' and 'cancel'

set_renderer (mixed $renderer)

Sets the form's renderer based on an existing renderer instance.



mixed&$renderer A prepared HTML_QuickForm_Renderer (or subclass thereof) instance.

set_value (string $key, string $value)

Set the value of a formelement.



stringthe form field name


stringthe new value to set

unfreeze ()

Special form freeze handling.

_add_filter_rules ()

Add form-wide filter rules

_add_operation_buttons ()

_check_freeze_status (string $name, array $config)

Checks if widget is editable and sets freeze status accordingly



stringThe name of the widget.


arrayWidget configuration.


Truewhen widget is frozen, false otherwise

_create_default_renderer ()

Creates an instance of the renderer set in the system configuration.

This is called during the initialize code and will make the renderer available immediately after startup.

_create_form ()

_end_fieldset (string $name, array $config)

End a fieldset.

Ends the requested amount of fieldsets when 'end_fieldset' key is defined in the schema field or at least once when the key exists in the field.






_is_widget_visible (string $name, array $config)

This helper function checks whether a given widget is visible.



stringThe name of the widget.


arrayWidget configuration.


booleanVisibility state.

_load_field_default ($name, $config)




_load_widget (string $name, $initialize_dependencies)

This function will create all widget objects for the current schema.

It will load class files where necessary (using require_once), and then create a set of instances based on the schema.



stringThe name of the field for which we should load the widget.



booleanIndicating success

_start_fieldset (string $name, array $config)

Start a fieldset and set the styles accordingly.

Fieldsets can be initialized by key start_fieldset

see \midcom_helper_datamanager2_schema








\midcom_helper_datamanager2_schema $_schema

The schema (not the schema <i>database!</i>) to use for operation.

This variable will always contain a parsed representation of the schema, so that one can swiftly switch between individual schemas of the Database.

access protected

Array $_types

The list of types which should be used for rendering.

They must match the schemadb passed to the class.

The member is initialized by-reference.

access protected

\HTML_Quickform $form

This is the QuickForm generated out of the schema.

This member is set during the initialize call.


\const $namespace

The namespace of the form.

This value is to be considered read only.

This is the Namespace to use for all HTML/CSS/JS elements. It is deduced by the formmanager and tries to be as smart as possible to work safely with more then one form on a page.

You have to prefix all elements which must be unique using this string (it includes a trailing underscore).


\HTML_Quickform_Renderer $renderer

This is the renderer that quickform will use.

It is set using the set_renderer() or create_renderer() calls.

If the configuration option 'default_renderer' (and possibly 'default_renderer_src') are set, the class will create instances of these renderers during startup, so that site users can directly use these defaults without further work. The following rules are used when determining which renderer to use:

If the default_renderer_src config option is null (the default), the class assumes that a default MidCOM renderer from the renderer subdirectory of this component should be used. In this case, you set only the actual renderer name (e.g. "simple") in default_renderer.

On the other hand, if you set the default_renderer_src option, the system first loads the snippet identified by that config option. the default_renderer option then has to hold the name of the renderer class that should be created. It must be default constructible.

If you don't want any renderer to kick in, set the (default) renderer to 'none' will stick to the QF Default renderer.

Authors note: Be aware that on the long run this rendering system will get some base classes which make building renderers with MidCOM support easier. Right now we simply use the standard run-of-the-mill renderers of QF, but be prepared that the API of this might change a bit (reflected in that new base class) on the long run.


string $state

State of the form manager

Array $widgets

A list of widgets, indexed by the field names from the schema, thus matching the type listing.

mixed $_defaults


integer $_fieldsets

Number of open fieldsets.

This will be used to close the same amount to prevent open fieldset tags