API:EPrints/Plugin/InputForm/Component

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

---

API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki

NAME

EPrints::Plugin::InputForm::Component - A single form component

DESCRIPTION

A component is an HTML widget for use in a EPrints::Workflow::Stage. A EPrints::Plugin::InputForm::Component::Field component renders the form inputs for a 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 parse_config:

<component type="Upload" show_help="always" />

In this instance the 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 EPrints::Plugin::Screens. The update_from_form method is called from the Screen's from stage and the component renders a fragment of XHTML that is inserted into the resulting page. Components have no equivalent to 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 (update_from_form) and to generate the new page (render). Therefore you can not rely on data persisting between the update and rendering stages, unless you store the data in the 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.

AJAX Support

Some components support AJAX-like incremental updates. The Javascript Component class can make requests aimed at a Component by specifying the component=cXX 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 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 EPrints::Plugin::InputForm::Component::Documents, which uses a JSON response to determine the documents to update.

METHODS

new

$component = EPrints::Plugin::InputForm::Component->new( %opts )

Create a new component object with following parameters:

  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

See also EPrints::Plugin::InputForm::Surround::Default.

parse_config

$bool = $component->parse_config( $config_dom )

Parses the supplied DOM object and populates $component configuration.

is_required

$bool = $component->is_required()

returns true if this component is required to be completed before the workflow may proceed

get_surround

$surround = $component->get_surround()

returns the surround for this component.

is_collapsed

$bool = $component->is_collapsed()

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

render_help

$help = $component->render_help( $surround )

Returns DOM containing the help text for this component.

get_name

$name = $component->get_name()

Returns the unique name of this field (for prefixes, etc).

wishes_to_export

$bool = $component->wishes_to_export

See EPrints::Plugin::Screen/wishes_to_export.

export_mimetype

$mime_type = $component->export_mimetype

See EPrints::Plugin::Screen/export_mimetype.

export

$component->export

See EPrints::Plugin::Screen/export.

render

$xhtml = $component->render

Renders the component in its surround.

render_title

$title = $component->render_title( $surround )

Returns the title of this component as a DOM object.

render_content

$content = $component->render_content( $surround )

Returns the DOM for the content of this component.

has_help

$boolean = $component->has_help()

Returns true if this component has help available.

get_fields_handled

@field_ids = $component->get_fields_handled

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

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/.