Label Bundles

From CollectiveAccess Documentation
Jump to: navigation, search


Label Bundle Editing Component

The label bundle editing component implements a generic form-based editing interface for locale-specific labels (aka. "titles" or "names") attached to any of the database entities that support them (including objects, entities, places, occurrences, collections and list items).

Label bundle.png

The component allows users to easily attach as many labels to an item as are required and specify a locale and (for label that support them) a type specifier. The component also allows for removal of labels. Two modes of operation are provided:

  • preferred mode enforces locale restrictions for preferred labels, specifically that an item may have no more than one preferred label per-locale. In preferred mode the component will restrict the locale drop-down menu for individual labels to only those locales that are not yet in use. It will also restrict the total number of labels to the number of locales defined.
  • non-preferred mode allows an unlimited number of labels and does not enforce locale restrictions.

The label bundle system is comprised of two parts:

  • a server-side API implemented in app/lib/ca/LabelableBaseModelWithAttributes (a sub-class of BaseModel) that provides functions to add, edit and delete labels as well as generate HTML required for editing. This API is available in the model for that class to which the labels are attached, rather than in the model for the labels themselves. This means you don't have to instantiate a separate class to add/edit/delete labels.
  • a client-side UI component for both preferred and non-preferred labels

Server-side API

The server-side API is implemented as a sub-class of BaseModel. Model classes that inherit from LabelableBaseModelWithAttributes will have the following label-API methods:

Method Parameters Description
To come

TODO: Add API details

Client-side UI component

The component, like other Providence-specific UI components, is defined in a file (ca.labebundle.js) in the js/ca directory and accessible via the caUI namespace. The component is designed to be included within a larger form. It makes no assumptions about what else is in the form and provides options allowing you to control the naming (both the 'name' and 'id' attributes) of the data input elements in the component.

To use the component, define a form with <form> tags and add any other input elements as required. Where you want the component to appear you must place a markup "framework" upon which the component will be erected. The framework includes a
that contains the component as a whole (the "container"), a
that contains the list of labels (the "label list") and a <a> (with href='#') that will function as an "add label" button. Most critically, the framework also includes a template for the label input form in a hidden textarea. This template is used as many times as necessary to create the label input forms in the label list. A working framework could looking like the following code:
<div id="ObjectPreferredLabels">
        <!-- BEGIN TEMPLATE -->
	<textarea class='caLabelTemplate' style='display: none;'>
		<div id="ObjectPreferredLabel_{n}">
			<?= $t_label->htmlFormElement('locale_id', "^ELEMENT", array('classname' => 'labelLocale', 'id' => "{fieldNamePrefix}locale_id_{n}", 'name' => "{fieldNamePrefix}locale_id_{n}", "value" => "{locale_id}", 'no_tooltips' => true)); ?>
			<?= $t_label->htmlFormElement('name', "^ELEMENT", array('name' => "{fieldNamePrefix}name_{n}", 'id' => "{fieldNamePrefix}name_{n}", "value" => "{name}", 'no_tooltips' => true)); ?>
			<a href="#" class="caDeleteLabelButton">[Delete label]</a>
        <!-- END TEMPLATE -->
	<div class="labelInfo">
		<div class="labelInfo caLabelList">
			<div class='formLabel'>Preferred labels for this object</div>
			<div class='button'><a href='#' class='caAddLabelButton'>Add label</a></div>

Note that this example assumes that the HTML form elements in the template are created by calling the htmlFormElement() method of the label's model, and then passing various parameters to override default name, id and value attributes. Also note that template placeholders are designated by curly brackets ("{" and "}). The following placeholders are defined and can be used in your templates:

Placeholder Description
{fieldNamePrefix} Text to prefix field names with, defined when creating the component with a call to caUI. initLabelBundle() - see below
{n} A field name suffix defined by the component when creating a new label form in the label list. This will be either the label_id value for pre-existing labels or the string "new_" + an incrementing integer. For the first label form created by clicking on the "add label" button this value will be "new_0"; a subsequent add label request will result in the suffix being passed as "new_1" For your templates, be sure to end the name and id of all label form elements with this placeholder
{fieldname} Each of the fields defined in your template will have a placeholder defined to be the value of the field (for pre-existing labels or nothing (the empty string "") for new labels. You must list the names of the fields in your label form template in the templateValues option when you call caUI. initLabelBundle()

Once you have your framework you create the component by invoking the caUI.initLabelBundle() constructor method as in the following example, which assumes $va_initial_values is an associative array keyed on label_id with associated values being associative arrays with field names as keys and values as field values.

	<script type="text/javascript">
		caUI.initLabelBundle('#ObjectPreferredLabels', {
			mode: 'preferred',
			fieldNamePrefix: 'ObjectPreferred',
			templateValues: ['name', 'locale_id'],
			initialValues: <?= json_encode($va_inital_values); ?>,
			labelID: 'ObjectPreferredLabel_',
			localeClassName: 'labelLocale',
			templateClassName: 'caLabelTemplate',
			labelListClassName: 'caLabelList',
			addButtonClassName: 'caAddLabelButton',
			deleteButtonClassName: 'caDeleteLabelButton'

The first parameter is a [1]-compatible selector for the container. The second parameter is an associative array specifying options for the component. Available options are:

Option Description Default
mode Mode of operation for the component. Valid values are 'preferred' or 'non-preferred' In 'preferred' mode the restriction that an item may have only one preferred label per locale is enforced. Preferrred
fieldNamePrefix A string to prepend to all form field names and ids in the component. This value should be set to something page-unique, in case you are using multiple component instances on the same page. Empty string ("")
templateValues A list of field names present in your label form template; this should be a simple Javascript array of names as they appear in the template. Empty list ([])
initialValues A Javascript associative array containing data about existing labels for the current item. The data in this array is used to populate the initial list of labels upon initialization of the component. The array is indexed by label_id, with each value being an associative array indexed by field name and containing field values. Empty associative array ({})
labelID Value to use when assigning ID's to new labels; is followed by the label_id or a "new_{n}" identifier. You should make sure this matches the id (sans {n}) of the label
in your template.
localeClassName Class name assigned to locale_id drop-downs. This is used to retrieve the drop-down for manipulation by the component, so you must assign this class name to all locale drop-downs or the component will fail. caLabelLocale
templateClassName Class name assigned to your <textarea> template. This is used to retrieve the template so you must set this properly for the component to work. caLabelTemplate
labelListClassName Class name assigned to the
containing the list of labels in the component.
addButtonClassName The class of the <a> representing the "add label" button. caAddLabelButton
deleteButtonClassName The class of the <a> representing the "remove label" button. caDeleteLabelButton
Retrieved from ""

Personal tools