CSV value templates
Note
This section describes using CSV value templates in your configuration file. For information on CSV field templates, see the "CSV field templates". For information on CSV file templates, see the "CSV file templates" section.
Applying CSV value templates to rows in your input CSV
In create
and update
tasks, you can configure templates that are applied to all the values in a CSV column (or to each subvalue if you have multiple values in a single field) as if the templated text were present in the values in your CSV file. The templates are configured in the csv_value_templates
option. An example looks like this:
csv_value_templates:
- field_linked_agent: relators:aut:person:$csv_value
For each value in the named CSV field (in this example, field_linked_agent
), Workbench will apply the template text (in this example, relators:aut:person:
) to the CSV value, represented in the template as $csv_value
. An input CSV file that looks like this:
file,id,title,field_model,field_linked_agent
IMG_2940.JPG,03,Looking across Burrard Inlet,25,"Jordan, Mark|Cantelo, M."
will have the template relators:aut:person:$csv_value
applied to so it is converted to:
file,id,title,field_model,field_linked_agent
IMG_2940.JPG,03,Looking across Burrard Inlet,25,"relators:aut:person:Jordan, Mark|relators:aut:person:Cantelo, M."
This example configuration defines only one field/template pair, but csv_value_templates
can define multiple field/template pairs, for example:
csv_value_templates:
- field_linked_agent: relators:aut:person:$csv_value
- field_subject: subject:$csv_value
- field_local_identifier: SFU-$uuid_string
The following template variables are available:
$csv_value
: The verbatim string value of the field.$file
: The verbatim value of thefile
column in the row.$filename_without_extension
: The filename portion only (with no leading directory path or file extension) in thefile
column in the row.$weight
: The value of thefield_weight
column in the CSV, or for paged content created using the "Using subdirectories" option, the sequence number embedded in the page's filenme.$random_alphanumeric_string
: A randomly generated string containing numbers and mixed-case letters. This string's default length is 5 characters, but this can be overridden by includingcsv_value_templates_rand_length
in your configuration file, e.g.csv_value_templates_rand_length: 10
.$random_number_string
: A randomly generated string containing only numbers. This string's default length is 5 characters, but this can be overridden by includingcsv_value_templates_rand_length
in your configuration file, e.g.csv_value_templates_rand_length: 10
.$uuid_string
: A valid version 4 UUID.
A few things to note about CSV value templates:
- The variable can be anywhere in your template (beginning, middle, or end).
- You can only define a single template for a given field in
csv_value_templates
, but you can include multiple variables in a single template. If multiple variables are present in a template, they are applied in the order listed above. - If a CSV field contains multiple subvalues, the same template is applied to all subvalues in the field (as illustrated above).
- Values in the templated CSV output are validated against Drupal's configuration in the same way that values present in your CSV are validated.
- By default, CSV value templates won't be applied to empty fields. However, if you want a template to be applied to a field if that field is empty, you can include the
allow_csv_value_templates_if_field_empty
setting in your config file defining a list of column names. For example,allow_csv_value_templates_if_field_empty: [field_identifier]
will apply any templates defined forfield_identifier
in yourcsv_value_templates
setting, even iffield_identifier
is empty in your input CSV; for example, the following will apply templated defined in the above example configuration even if the named fields are empty:
allow_csv_value_templates_if_field_empty: ['field_local_identifier', 'field_subject']
Applying CSV value templates to paged content
Paged content (or as sometimes referred to, children) created using the "Using subdirectories" method do not have their own rows in input CSV files. However, you can apply CSV value templates to their node fields using. In this case:
- the CSV row that is used as the source of
$csv_value
is the page's (or child's) parent row - the
$file
variable is the name of the page/child's filename (and$filename_without_extension
is derived from this value) - the
$weight
variable is taken from the page/child's sequence indicator, e.g. a filename ofpage-002.jpg
would result in a$weight
value of "2".
If you want to apply CSV field templates to page/child items using this technique, register the templates in the csv_value_templates_for_paged_content
config setting. The structure of the field-to-template mappings is identical to those used in the csv_value_templates
setting as illustrated above. For example:
csv_value_templates_for_paged_content:
- field_linked_agent: relators:aut:person:$csv_value
- field_edtf_date_issued: $csv_value
- field_local_identifier: $csv_value-$weight
Note
Fields that are configured to be required in a content type are automatically applied to paged/child items created using the "Using subdirectories" method using the same values for those fields as their parents' rows in the CSV input file. However, you can also configure templates using the csv_value_templates_for_paged_content
setting if you wish.