Editing Compound field

{{fieldtypes}}


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

== Inheritance ==
* [[Metadata]]
** [[Compound field]]

== Additional Properties ==
{| border="1" cellpadding="3" cellspacing="0"
! 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 <code>fields</code> so does not to be included in the field definition.
|-
| '''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 ==
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,
 },