Difference between revisions of "Compound field"

From EPrints Documentation
Jump to: navigation, search
m (Additional Properties)
 
(16 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{reference}}
 
 
{{fieldtypes}}
 
{{fieldtypes}}
== Inherritance ==
+
 
* [[Metadata]]
 
** [[Compound field]]
 
  
 
== Description ==
 
== Description ==
 +
This field that contains multiple sub-fields such as used for creators so both a name and ID can be captured.
  
== Properties ==
+
== Inheritance ==
 +
* [[Metadata]]
 +
** [[Compound field]]
  
 +
== Additional Properties ==
 
{| border="1" cellpadding="3" cellspacing="0"
 
{| border="1" cellpadding="3" cellspacing="0"
| name || default || description
+
! Name !! Default Value !! Required !! Description !! Notes
 
|-
 
|-
| '''fields''' || n/a || '''This property is always required.'''
+
| '''fields''' || n/a || YES || The sub-fields for this compound field. ||
 
|-
 
|-
| '''fields_cache''' || n/a || '''This property is always required.'''
+
| '''fields_cache''' || n/a || YES || A cache of the sub-fields. || Although this is required it is generated from <code>fields</code> so does not to be included in the field definition.
 
|-
 
|-
| '''show_in_fieldlist''' || 0 || ...
+
| '''show_in_fieldlist''' || <tt>0</tt> || NO || Whether field should be included in data object's field list. || Different to parent default (<tt>1</tt>), as individual sub-fields are already shown in field list.
 
|}
 
|}
  
 
== Required Phrases ==
 
== Required Phrases ==
 +
In addition to the [[Metadata#Required_Phrases|standard metadata field phrases]] other phrases that 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 <code><dataset>_<fieldname>_<subfieldname></code>. For example, the related URL for an EPrint (<tt>related_url</tt>) has a URL and a type, so would have tables named <tt>eprint_related_url_url</tt> and <tt>eprint_related_url_type</tt>.
 +
 +
The tables in this instance have the following structure:
 +
eprint_related_url_url:
 +
  eprintid INT(11)
 +
  pos INT(11)
 +
  related_url_url LONGTEXT
 +
 +
eprint_related_url_type:
 +
  eprintid INT(11)
 +
  pos INT(11)
 +
  related_url_type VARCHAR(255)
 +
 +
<tt>eprintid</tt> is the ID of the eprint to which the field applies.  <tt>pos</tt> contains the position of the entry (starting at 0).  The remaining field uses the appropriate field type for the sub-field (in this case <code>LONGTEXT</code> for the [[Url field|URL]] and <code>VARCHAR(255)</code> for the type).
 +
 +
== API ==
 +
See [[API:EPrints/MetaField/Compound|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 <tt>related_urls</tt>.  This has a <tt>url</tt> and <tt>type</tt> subfields and initial specifies an initial single input row.  The <tt>render_value</tt> 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 <tt>creators</tt>.  This uses a <tt>name</tt> and <tt>text</tt> 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,
 +
},

Latest revision as of 20:41, 11 April 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 - Relation - Search - Secret - Set - Storable - Subject - Subobject - Text - Time - Timestamp - Url - Uuid


Description

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

Inheritance

Additional Properties

Name Default Value Required Description Notes
fields n/a YES The sub-fields for this compound field.
fields_cache n/a YES A cache of the sub-fields. Although this is required it is generated from fields so does not to be included in the field definition.
show_in_fieldlist 0 NO Whether field should be included in data object's field list. Different to parent default (1), as individual sub-fields are already shown in field list.

Required Phrases

In addition to the standard metadata field phrases other phrases that 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 LONGTEXT

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). The remaining field uses the appropriate field type for the sub-field (in this case LONGTEXT for the URL and VARCHAR(255) for the 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,
},