ALT MultiField

Overview

ALT MultiField is designed for storing smallish datasets in a compact and easily-manipulable way.

Think of the following sorts of data:

• An address, consisting of separate fields for Street Address, Suite/Box/Apartment Information, City, State, Zip, and Country;
• A set of stats for a roleplaying game, which might consist of such things as Strength, Wisdom, Dexterity, Intelligence, Charisma, and Constitution; or
• Information for a particular garden plant, such as what kind of Soil it prefers, how much Water it likes, its Shade Tolerance, and how many Days it takes to mature.

What these have in common is:

1. The individual bits of data are RELATED to each other, so you may want to output individual pieces, but you might also want to manipulate them as a unit; and
2. You only need one SET of the fields per entry, so a Matrix is overkill (especially if there are more than seven or eight, at which point a Matrix row starts to stre-e-e-e-e-tch your Publish form out unpleasantly).

You could do something similar, layout-wise, by creating seven or eight individual Publish fields in your field group; but they would take up a fair bit more space, even if you shrank them with the Publish Layout tools so they were three or four across. ALT MultiField fields can also be individually styled, either the whole group or individual subfields, within each field instance. Separate MultiFields will NOT have their style settings overlap or collide, even if there are multiple MultiFields on a single Publish form.

Further, individual Publish fields have no notion of association, which is a big strength of this Fieldtype. You can always grab an individual item or its label, or several of them, using the standard tag pair syntax; but in addition to that, you can manipulate the subfields as a unit using the single-tag syntax.

Installation

1. Download the GitHub repository and unzip. Add the alt_multifield directory to your /system/expressionengine/third_party/ directory.
2. Go to Add-Ons -> Fieldtypes and install the ALT MultiField fieldtype.

Setup

The way ALT MultiField works, you create your Field, and then you define a number of Subfields that will hold your actual data. Field creation works as normal; go into one of your Field Groups and create a new field, setting it to type ALT MultiField.

At that point, you will see two textareas under Field Options; one is for defining Subfields, and one is for styling. The syntax for defining Subfields is very similar to Pixel & Tonic's syntax for setting up Dropdowns, Radio Groups, and Checkbox Groups, so it may look familiar to you. A subfield is defined as follows:

subfield_name : Subfield Label : input type

• The subfield_name must follow the same rules as URL Titles and Field Names: no spaces, no special characters except - and _.

• The Subfield Label may contain spaces and special characters but may not contain newlines.

• The input type is optional: if you leave it blank, it will default to text. Other valid values are 'textarea' and several of the HTML5 input types: tel, email, url, number, and date.

  Note that only modern browsers will validate the types; no Javascript backup or shim is in place to catch older browsers. Also note that the date type will have the standard EE Datepicker attached to it automatically.

Output Info

There are two ways to output the contents of a MultiField: the tag pair or the single tag. The tag pair gives you flexibility; the single tag is a quick-and-dirty way to handle some common use cases.

So, first, let's say we have a MultiField named my_multifield, with Subfields defined as follows:

subfield_one : A Subfield : text
subfield_two : Another Subfield : text
subfield_date : An Arbitrary Date : date

Let's take a look at how to output that in various useful ways.

Tag Pair

You can output subfields, their labels, and their types using the tag pair syntax, as follows:

{my_multifield}
    {subfield_one:label} : {subfield_one} (type: {subfield_one:type})
{/my_multifield}

The tag pair takes no parameters.

Single Tag

The single tag outputs your ENTIRE list of subfield labels and values (optionally excluding empty values) in a couple of different useful formats.

The syntax for the single tag looks like this:

{my_multifield style="table" show_empty="yes" include_wrapper="yes" 
               subfield_classes="odd|even"}

• The style parameter currently has two values: table, which outputs table rows, and dl, which outputs a definition list. If you fail to include a style parameter it will default to table.
• The show_empty parameter determines whether the tag outputs subfields whose values are empty; it defaults to no.
• The include_wrapper parameter determines whether wrapper <table></table> or <dl></dl> tags are output at the beginning and end of the loop; it defaults to yes.
• The subfield_classes parameter takes a pipe-delimited list of classes that will be applied in order to the subfields as it loops through. It works much like the EE {switch} tag. In the example above, the first subfield will get class odd as it loops, the second will get class even, the third will get odd again, and so forth. If you do not add any classes to this loop, all of your subfields will get class multifield. Note that the value of the style tag may cause additional classes to be applied to portions of the output as well!

Example Tag Outputs

The following single tag, applied to our example field above:

{my_multifield style="dl" show_empty="yes" include_wrapper="yes"}

Will return the following output:

<dl>
    <dt class="multifield label">A Subfield</dt>
        <dd class="multifield value">(some value)</dd>
    <dt class="multifield label">Another Subfield</dt>
        <dd class="multifield value">(some value)</dd>
    <dt class="multifield label">An Arbitrary Date</dt>
        <dd class="multifield value">YYYY-MM-DD hh:ii:ss aa</dd>
</dl>

The following single tag, applied to our example field above:

{my_multifield style="table" show_empty="yes" include_wrapper="no" subfield_classes="odd|even"}

Will return the following output (note that include_wrapper is set to no, meaning the wrapper <table></table> tag is not returned!):

    <tr class="odd">
        <td class="label">A Subfield</td>
        <td class="value">(some value)</td>
    </tr>
    <tr class="even">
        <td class="label">Another Subfield</td>
        <td class="value">(some value)</td>
    </tr>
    <tr class="even">
        <td class="label">An Arbitrary Date</td>
        <td class="value">YYYY-MM-DD hh:ii:ss aa</td>
    </tr>

NOTE: Dates are output as standard MySQL dates and there is currently no built-in formatting capability. There are other plugins that will allow you to format arbitrary dates using EE format codes; use them with the tag pair syntax! Nice Date by Low is a good choice for this.