Drupal Forms User Guide
Custom composite elements
Custom composite elements are discreet sets of data stored in one element, almost a form-within-a-form. Somewhat like a mini-spreadsheets, you can add columns or rows of data (depending on how you format the element). You can allow users to fill in a single row of information, or add multiple entries. These are useful if you want to add an unknown number of the same thing.
For example, you might be creating an entry form for a 'Cutest dog in Southwark' award. You could use the composite element to capture information about a single dog, or multiple dogs in one element. You can include nearly all the different types of element available in any combination, so you can capture all the information in one go.
One important thing to note about custom composite elements is that their default appearance settings aren't great if you have more than a few items in the element. The default layout is very much like a spreadsheet, as you can see here:
As you can see, it's cluttered and not very useable if you have more than 2 or 3 elements in it. To switch to a much more mobile-friendly vertical view, go to the Advanced tab and change the following:
- toggle Display elements in table columns to off
- toggle Allow users to add/remove elements to off
- toggle Allow users to input the number of items to be added to off (optional)
- toggle Allow users to sort elements to off (optional)
You get:
Depending on your needs, there are various options you can tweak to allow users to add and remove whatever the main 'thing' is (in this case, dogs).
Adding elements
One important thing to note when adding individual elements to a custom composite element is that the first setting, 'Add key...', cannot contain spaces or capital letters. So, for an element titled 'Upload a Nice Photo', you'll need to set the key to upload_a_nice_photo. If you get errors when trying to save a custom composite element, always check these to ensure you haven't accidentally put a space or a capital letter in them.
YAML
If you are adding an element with multiple fixed values (select, radio, checkbox), you'll need to add each value in YAML format (key: title). The list for the dog breed select element above is:
bichon: 'Bichon Frisé'
dachshund: Dachshund
pomeranian: Pomeranian
pug: Pug
shihtzu: 'Shih Tzu'
Note the single quotes around the titles with spaces.