Editing API:EPrints/Plugin/InputForm/Component (section)

==DESCRIPTION==
A component is an HTML widget for use in a [[API:EPrints/Workflow/Stage|EPrints::Workflow::Stage]]. A [[API:EPrints/Plugin/InputForm/Component/Field|EPrints::Plugin::InputForm::Component::Field]] component renders the form inputs for a [[API:EPrints/MetaField|EPrints::MetaField]] but component subclasses can be used to provide any required behaviour around user input. Components don't even have to be form inputs e.g. just render a fragment of XHTML.

Where components are shown and configuration are controlled through the EPrints XML workflow. The workflow reads the component type, loads the referenced plugin and passes the XML node to [[API:EPrints/Plugin/InputForm/Component#parse_config|parse_config]]:

<source lang="xml"><component type="Upload" show_help="always" /></source>

In this instance the [[API:EPrints/Plugin/InputForm/Component/Upload|EPrints::Plugin::InputForm::Component::Upload]] component is being inserted into the workflow and its help is being set to always be shown.

Components share many of the features seen in [[API:EPrints/Plugin/Screen|EPrints::Plugin::Screen]]s. The [[API:EPrints/Plugin/InputForm/Component#update_from_form|update_from_form]] method is called from the Screen's [[API:EPrints/Plugin/InputForm/Component#from|from]] stage and the component [[API:EPrints/Plugin/InputForm/Component#render|render]]s a fragment of XHTML that is inserted into the resulting page. Components have no equivalent to [[API:EPrints/Plugin/Screen#can_be_viewed|EPrints::Plugin::Screen/can_be_viewed]] - it is assumed that the workflow only exposes inputs to which the user has access.

A component will be created twice during a workflow response: to process the incoming data ([[API:EPrints/Plugin/InputForm/Component#update_from_form|update_from_form]]) and to generate the new page ([[API:EPrints/Plugin/InputForm/Component#render|render]]). Therefore you can not rely on data persisting between the update and rendering stages, unless you store the data in the [[API:EPrints/ScreenProcessor|EPrints::ScreenProcessor]].

Buttons in components are classed as "internal actions". Internal actions do not normally change the response workflow but only how the component renders. This is used to provide search features, provide more button inputs etc.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_ajax_support -->
===AJAX Support===
Some components support AJAX-like incremental updates. The Javascript Component class can make requests aimed at a Component by specifying the <code>component=cXX</code> CGI parameter and it is then up to the component what it renders.

The default behaviour is to render the XHTML fragment represented by the component, which is used by Javascript as an in-place replament. Elsewhere a JSON response is used to drive client-side behaviour.

Similarly to [[API:EPrints/Plugin/Screen|EPrints::Plugin::Screen]], AJAX components have a life-cycle of:

* 1. update_from_form() reads form values and sets them on the object
* 2. wishes_to_export() determines if this component is exporting
* 3. export() generates a response
See also [[API:EPrints/Plugin/InputForm/Component/Documents|EPrints::Plugin::InputForm::Component::Documents]], which uses a JSON response to determine the documents to update.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_methods -->