Difference between revisions of "Compound field"

From EPrints Documentation
Jump to: navigation, search
m (Spacing after ToC)
(Moved description to top. Added link to API page.)
Line 1: Line 1:
 
{{fieldtypes}}
 
{{fieldtypes}}
  
 +
 +
== Description ==
 +
A field that contains multiple sub-fields such as used for Creators so both a name and ID can be captured.
  
 
== Inheritance ==
 
== Inheritance ==
 
* [[Metadata]]
 
* [[Metadata]]
 
** [[Compound field]]
 
** [[Compound field]]
 
== Description ==
 
A field that contains multiple sub-fields such as used for Creators so both a name and ID can be captured.
 
  
 
== Properties ==
 
== Properties ==
 
 
{| border="1" cellpadding="3" cellspacing="0"
 
{| border="1" cellpadding="3" cellspacing="0"
 
| name || default || description  
 
| name || default || description  
Line 37: Line 36:
  
 
== API ==
 
== API ==
''To be added''
+
See [[API:EPrints/MetaField/Compound|API page]].
  
 
== Examples ==
 
== Examples ==

Revision as of 08:19, 21 March 2023

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


Metadata Fields: Arclanguage - Base64 - Bigint - Boolean - Compound - Counter - Dataobjref - Date - Decimal - Email - Fields - Float - Id - Idci - Image - Int - Itemref - Keywords - Langid - Longtext - Longtext_counter - Multilang - Multipart - Name - Namedset - Pagerange - Recaptcha - Recaptcha3 - Relation - Search - Secret - Set - Storable - Subject - Subobject - Text - Time - Timestamp - Url - Uuid


Description

A field that contains multiple sub-fields such as used for Creators so both a name and ID can be captured.

Inheritance

Properties

name default description
fields n/a This property is always required.
fields_cache n/a This property is always required.
show_in_fieldlist 0 ...

Required Phrases

Additional phrases are typically required for the field name of the sub-fields in the form:

 datasetid + "_fieldname_" + fieldname + "_" + subfieldname

Individual fieldhelp phrases are not required the help for sub-fields should be included in the fieldhelp for the main field.

Database

Each sub-field within a compound field has its own table named <dataset>_<fieldname>_<subfieldname>. For example, the related URL for an EPrint (related_url) has a URL and a type, so would have tables named eprint_related_url_url and eprint_related_url_type.

The tables in this instance have the following structure:

eprint_related_url_url: eprintid INT(11), pos INT(11), related_url_url VARCHAR(255)
eprint_related_url_type: eprintid INT(11), pos INT(11), related_url_type VARCHAR(255)

eprintid is the ID of the EPrint to which the field applies, pos contains the position of the entry (starting at 0), and the remaining field uses the appropriate field type for the subfield (in this case VARCHAR(255) for both URL and type).

API

See API page.

Examples

Most basic example:

{
    name => 'match',
    type => 'compound',
    subfields => [
        {
            'sub_name' => 'home_team',
            'type' => 'text',
        },
        {
            'sub_name' => 'away_team',
            'type' => 'text',
        },
    ],
}

Most use cases for compound fields require multiple rows like for related_urls. This has a url and type subfields and initial specifies an initial single input row. The render_value attribute allows a bespoke rendering of the field and its sub-fields rather than the default rendering for a compound field.

{
    name => 'related_url',
    type => 'compound',
    multiple => 1,
    render_value => 'EPrints::Extras::render_related_url',
    fields => [
        {
            sub_name => 'url',
            type => 'url',
            input_cols => 40,
        },
        {
            sub_name => 'type',
            type => 'set',
            options => [qw(
                pub
                author
                org
            )],
        }
    ],
    input_boxes => 1,
    input_ordered => 0,
 },

The most conspicious use of a compound field is creators. This uses a name and text sub-fields and specifies an initial four input rows.

{
    name => 'creators',
    type => 'compound',
    multiple => 1,
    fields => [
        {
            sub_name => 'name',
            type => 'name',
            hide_honourific => 1,
            hide_lineage => 1,
            family_first => 1,
        },
        {
            sub_name => 'id',
            type => 'text',
            input_cols => 20,
            allow_null => 1,
            export_as_xml => 0,
        }
    ],
    input_boxes => 4,
},