Editing API:EPrints/Plugin/InputForm/Component

<!-- Pod2Wiki=_preamble_ 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Plugin/InputForm/Component.pm|package_name=EPrints::Plugin::InputForm::Component}}[[Category:API|COMPONENT]][[Category:API:EPrints/Plugin/InputForm|COMPONENT]][[Category:API:EPrints/Plugin/InputForm/Component|COMPONENT]]<div><!-- Edit below this comment -->


<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
==NAME==
'''EPrints::Plugin::InputForm::Component''' - A single form component 

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_description -->
==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 -->
==METHODS==
<!-- Pod2Wiki=head_new -->
===new===

<source lang="perl">$component = EPrints::Plugin::InputForm::Component->new( %opts )

</source>
Create a new component object with following parameters:

<pre>  session - session object
  collapse - whether the component starts collapsed
  no_help - hide field help
  no_toggle - hide help toggle button
  surround - surround class, defaults to 'Default'
  prefix - prefix for the component id
  dataobj - object the field is being rendered for</pre>

See also [[API:EPrints/Plugin/InputForm/Surround/Default|EPrints::Plugin::InputForm::Surround::Default]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_parse_config -->
===parse_config===

<source lang="perl">$bool = $component->parse_config( $config_dom )

</source>
Parses the supplied DOM object and populates $component configuration.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_is_required -->
===is_required===

<source lang="perl">$bool = $component->is_required()

</source>
returns true if this component is required to be completed before the workflow may proceed

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_get_surround -->
===get_surround===

<source lang="perl">$surround = $component->get_surround()

</source>
returns the surround for this component.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_is_collapsed -->
===is_collapsed===

<source lang="perl">$bool = $component->is_collapsed()

</source>
returns true if this component is to be rendered in a compact form (for example, just title / required / help).

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_render_help -->
===render_help===

<source lang="perl">$help = $component->render_help( $surround )

</source>
Returns DOM containing the help text for this component.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_get_name -->
===get_name===

<source lang="perl">$name = $component->get_name()

</source>
Returns the unique name of this field (for prefixes, etc).

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_wishes_to_export -->
===wishes_to_export===

<source lang="perl">$bool = $component->wishes_to_export

</source>
See [[API:EPrints/Plugin/Screen#wishes_to_export|EPrints::Plugin::Screen/wishes_to_export]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_export_mimetype -->
===export_mimetype===

<source lang="perl">$mime_type = $component->export_mimetype

</source>
See [[API:EPrints/Plugin/Screen#export_mimetype|EPrints::Plugin::Screen/export_mimetype]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_export -->
===export===

<source lang="perl">$component->export

</source>
See [[API:EPrints/Plugin/Screen#export|EPrints::Plugin::Screen/export]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_render -->
===render===

<source lang="perl">$xhtml = $component->render

</source>
Renders the component in its surround.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_render_title -->
===render_title===

<source lang="perl">$title = $component->render_title( $surround )

</source>
Returns the title of this component as a DOM object.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_render_content -->
===render_content===

<source lang="perl">$content = $component->render_content( $surround )

</source>
Returns the DOM for the content of this component.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_has_help -->
===has_help===

<source lang="perl">$boolean = $component->has_help()

</source>
Returns true if this component has help available.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_get_fields_handled -->
===get_fields_handled===

<source lang="perl">@field_ids = $component->get_fields_handled

</source>
Returns an array of the names of the metadata fields which this field handles. Used for jumps.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_copyright -->
==COPYRIGHT==
Copyright 2000-2013 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=_postamble_ -->
<!-- Edit below this comment -->