Shortlist

Extra Data

New in Shortlist 3.0 is the ability to add extra arbitrary data to items. It's really simple.

Every item in lists can have extra data fields associated. We prefix all the data fields with 'extra:..'. The actual data can be set when the item is added to a list, or updated later by the list owner. In the {exp:shortlist:view}, {exp:shortlist:item} and {exp:shortlist:list} tags, the data is directly available as variables like {extra:notes}.

Dealing with 'extra:..' data per-item can be done at 3 points :

1. Adding data during the initial adding to a list action
2. Adding or updating data once an item is in a list
3. Outputting the data later

For these examples, we'll pretend we want to add data points called 'notes' and 'qty', but the exact same process can be used for any field you'd like to add.

1. Adding Initial Data

We can setup some initial values for our data values by adding the values we want to the item tag. Like so :

<a href="{exp:shortlist:add entry_id="12" extra:qty="1"}">Add this Item</a>

This will create a normal add to list shortlist link, and when the item is added, it'll be created with a value for qty set to '1'.

You can also use the :add_form to let your users set the values directly before adding the item (or allow them to override a default value before adding). Something like :

{exp:shortlist:add_form entry_id="12"}
	<select name="extra:qty">
		<option>1</option>
		<option>2</option>
		<option>3</option>
	</select>

	<input type="submit" value="Add to List"/>
{/exp:shortlist:add_form}

2. Updating the Data on Items

As well as setting data directly during initial list add, you can set it after the item is in the list proper. This might be good to have in a list detail or edit view, or could even be used as a simple cart system. There are two (very similar) ways to set the data. Per-item, or in bulk, both use the {exp:shortlist:item_form} tag.

First - per-item, usually within the {exp:shortlist:item} tag :

{exp:shortlist:item entry_id="12"}
	{title}

	{exp:shortlist:item_form item_id="{item_id}"}
		Qty : <input type="text" name="extra:qty" value="{extra:qty}"/>

		Notes :
		<textarea name="extra:notes">{extra:notes}</textarea>

		<submit>
	{/exp:shortlist:item_form}
{/exp:shortlist:item}

This creates a simple form and lets the user update the details for this specific item. If you wanted to let them update the details for all the items in a list (or even across all their lists), that's just as easy, we just name the form inputs slightly differently :

{exp:shortlist:view}
Your List : {list_title}

{exp:shortlist:item_form}
	{items}

	{title}
	Qty : <input type="text" name="extra:qty[{item_id}]" value="{extra:qty}"/>
	Notes :
	<textarea name="extra:notes[{item_id}]">{extra:notes}</textarea>

	{/items}
<submit>
{/exp:shortlist:item_form}
{/exp:shortlist:view}

Note the only difference here is the naming of the inputs. :

<input type="text" name="extra:qty[{item_id}]" value="{extra:qty}"/>

Simply make your inputs multi-dimensional, with the {item_id} as the key, and Shortlist will do the rest. Hey, presto, your users can update all their extra data values in a single action.

Note: Only list owners can update the values on items. Shortlist will validate every individual action, and will ignore any attempts by anyone other than the owner to update extra data values on items.

Outputting the Extra Data

This is the simplest part. Everywhere you can view the list items, you'll have access to the extra data, via variables named like : {extra:qty} or {extra:notes} etc.. It's really that simple.

Note: Shortlist will parse any variables like {extra:not_a_real_name} and turn them into empty strings if there's no real extra data set for them per item.