accessories

A "Swiss Army Knife" widget builder, this provides access to Interchange's product option attributes (e.g. to choose or access product options such as a shirt's size or colour).

Can build selection objects (radio buttons, check boxes, select boxes, etc.), forms and hyperlinks, or can simply return a value.

Summary

• [accessories code arg]
• [accessories code attribute type other_named_attributes]
• [accessories code arg other_named_attributes] *DEPRECATED*

Parameter	Description	Default
code	Value of the SKU code in the ProductFiles (or specified other) table.	None
key	Alias for code.	None
row	Alias for code.	None
arg	Positionally interpreted comma-delimited list of values for the following attributes:  attribute, type, column, table, name, outboard, passed.  (Deprecated)	None
append	Specify a string to append to the returned output.	None
attribute	The item attribute the tag will work with.	None
cols	Specify a number to pass to the to the "cols" parameter in HTML widgets that accept it.	Varies with type (often 40)
column	Specifies the column in the table that contains an item's attribute values.	attribute
col	Alias for column.	attribute
field	Alias for column.	attribute
contains	Determine whether a substring match of the value will cause a radio box or check box to be selected..	None
default	Sets the default attribute option in the widget returned by this tag.	None
delimiter	Specify the attribute parameter list delimiter.	Comma (",")
empty	Request that this tag should include a hyperlink for the empty "--select--" option, when type is "links".	None
extra	Specify extra HTML tag attributes, such as "id" or "class" etc.	None
form	Set the base value for the form, when type is "links".	mv_action=return
href	Sets the base href for the hyperlinks, when type is "links".	Current page
joiner	Override the default string (<br>) that joins the hyperlinks, when type is "links".	None
js	Specify JavaScript to be placed within the start tag of the widget's HTML output.	None
new	Sets a value in place of the "New" or "Current" option in a combo box, when type is "combo" or "reverse_combo"	None
name	Sets the name of the form variable to use.	mv_order_attribute
outboard	Used with the [PREFIX-accessories] tag to specify the table lookup value.	None
passed	Used to pass custom values to the widget built by this tag.	None
prepend	Specify a string to prepend to the returned output.	None
price	Force prices to be displayed along with item attributes.	None
price_data		None
rows	Specify a number to pass to the to the "rows" parameter in HTML widgets that accept it.	Varies with type (often 4)
secure	Cause the generated link(s) to point to your secure (HTTPS/SSL) Interchange URI, when type is "links".	No
table	Specifies database table that contains the item's attribute values	See ProductFiles
base	Alias for table.	See ProductFiles
database	Alias for table.	See ProductFiles
db	Alias for table.	See ProductFiles
template	Allows you to override the standard Interchange template for the hyperlinks, when type is "links".	None
type	The display widget to use.	select
width	Quasi-alias for the cols parameter that only works with the "text" and "password" widgets.	None

Examples

Tag expansion example

Perl example

or similarly with positional parameters: 

Description

This is the "Swiss Army Knife" widget builder for providing access to Interchange's product option attributes (e.g., to choose or access product options such as a shirt's size or colour).

Interchange allows you to choose item attribute values for each ordered item;  You can attach a size, colour or any other modifier to a line item in the shopping cart.  You can also resubmit previous attribute values via hidden form fields.

The UseModifier local configuration directive is used to set the name of the modifier(s).  For example:

will attach both a size and colour attribute to each item code that is ordered.

Warning You may not use the following names for attributes:  "item", "group", "quantity", "code", "mv_ib", "mv_mi" or "mv_si"

You can also set modifier names with the "mv_UseModifier" scratchpad variable, as follows:

which has the same effect as the above.

This allows multiple options to be set for products.  Whichever one is in effect at order time will be used.  Be careful:  You cannot set it more than once on the same page.  Setting the mv_separate_items or the SeparateItems directive places each ordered item on a separate line, simplifying attribute handling.  The scratchpad setting for mv_separate_items has the same effect.

The modifier value is accessed in the [item-list] loop, with the [item-param attribute] tag, and form input fields are placed with the [modifier-name attribute] tag.  This is similar to the way quantities are handled.

Note You must be sure that none of the fields in your forms have digits appended to their name if the variable is the same name as the attribute name you select.  This is because the [modifier-name size] variables will be placed in the user session with names like size0, size1 and size2 etc.

Interchange will automatically generate the select widgets when the [accessories code="os28044" attribute="size"] or [PREFIX-accessories size] tags are called.  They have the following syntax:

Notes: 

• The attribute attribute is required.
• See the type attribute for a list of types.
• The trailing "*" in value2 will mark it as the default ("selected") value in the select widget (see below).

When called with an attribute, the database is consulted to find a comma-separated list of item attribute options, which take the following form:

The label text is optional.  If no label is provided then the name will be used (as in the "name_b" in the above example).

If an asterisk (*) is the last character of the label text, then the item will be the default selection.  If no default is specified then the first item in the list will be the default.  For example:

This will search the ProductFiles table(s) for a column named "colours".  If an entry such as "beige=Almond, gold=Harvest Gold, White*, green=Avocado" is found then a select widget like the following will be built:

You can use this in combination with the mv_order_item and mv_order_quantity session variables to allow a customer to enter an item attribute during an order.

If used in an [item-list], and the user has changed the value, the generated select widget will automatically retain its current value</i>, as selected by the user.  The value can then be displayed with [item-modifier colour] on the order report, order receipt or any other page containing an [item-list] tag.

Emulating with a loop

You can also build widgets directly, without using the [accessories] tag.  You may have to do so if you need more control of the content than the tag offers.  The following is a fragment from a shopping basket display form, which shows a selectable size with sticky setting, and a price that changes based upon the modifier setting.  Note that this example would normally be contained within the [item-list][/item-list] pair.

The output of the above would be similar to the output of [item-accessories size select] if the ProductFiles table's size column contained the value "S, M, L, XL".  The difference is that the options in the loop emulation show the adjusted price in addition to the size within each option value.

Hash Lists (technical note)

As a technical note, some of the features of this tag work differently depending upon whether it was called with a $Vend::Interpolate::item hash reference.  For example, when called as [item-accessories] within an [item-list] container.

In this context, the tag will have access to ancillary data from the item (including, perhaps, a user's chosen item attribute value).  For example, if building a textarea widget within an [item-list], the widget will show the chosen item attribute value.  On the other hand, within an array list such as a [search-list] block in a [search-region], the widget would be empty.

If you really know what you're doing, you can pass an item hash reference, within a [perl] tag, like this:

Also see the Looping tags and sub-tags category for information about hash-context and array-context in looping tags.

Parameters

code

This is the primary key in the specified table (commonly named "sku" in a products table).  If no table is specified then this tag defaults to the table(s) defined with the ProductFiles local configuration directive which, in turn, defaults to "products".

You should not specify a code parameter when looping on [PREFIX-accessories], as it internally sets the "code" to the key for the current item in the loop.  See the outboard parameter.

arg

Deprecation notice The arg parameter was deprecated in Interchange 4.6.  Please do not make use of this parameter as it may be removed, without warning, at any time.

This parameter allows you to pass values for some of the more commonly used attributes, in the manner of the [PREFIX-accessories] tag, as a comma-delimited positional list.  For instance:

Whitespace within the list is optional.

If you leave out one or more of the above attributes, and are setting anything after it in the list, then be sure to keep the comma(s).  For instance:

The above example shows the attribute names for clarity.  You would probably want actually use the values, so the previous example might actually be something like the following:

Note Although you must use such a comma-delimited list to pass attributes to the [PREFIX-accessories] tag, please use named attributes instead for the [accessories] tag.

append

You can set a string to append to the returned output of the tag.  Note that this is not a list to append to the fetched attribute value list, which is treated within the tag.

attribute

You can set attributes for items in a table, usually the "products" table, with the UseModifier configuration directive.  Typical attributes are "size" and "colour".

This parameter selects the item attribute upon which this tag will operate.  Also see the column parameter, below.

cols

The tag will pass the number you choose through to the HTML "cols=X" parameter in HTML widgets that accept it.

See also rows, above.

column

This specifies the column in the table that contains an item's attribute values.  This tag will look for item attribute names and values in a comma-delimited list of "name=value" pairs, stored in this column of an item's row in the table.

The column, in the table, corresponding to the attribute will traditionally have the same name as the attribute.  That does not need to be the case, but you may find it to be confusing if you use different names.  If unspecified, the column name will default to the name specified with the attribute parameter.

For example, if an item in the "products" table has a "size" attribute, and each item's comma-delimited list of available sizes is stored in the "how_big" column, then you would need to specify "column=how_big" because the tag's default column choice (size) would be missing, or used for some other purpose.

contains

Requires type to be "radio" or "check".

This is used to determine whether a substring match of the value will cause a radio box or check box to be selected.  If true then the match will happen whether the value is on a word boundary or not.  If false then the value must be on a word boundary.  When we speak of a word boundary, it is in the Perl sense.  I.e. a word character ([A-Za-z0-9_]) followed by or preceded by a non-word character, or the beginning or the end of the string.

default

Sets the default attribute option in the widget returned by this tag.  This will override a default indicated with a trailing asterisk (*) in the database or a "passed" string.  This will also override the default of a user's previous selection when it would have otherwise been preserved.

For example the following selects "blue" by default, rather than "green" as it would otherwise have done.

which will generate:

Obscure technical note the tag will ignore the "default" parameter if it has an item hash reference.  See Hash Lists, above.

delimiter

The list of attribute values will be a delimited string.  This parameter allows you to specify an alternative delimiter if the list is not comma-delimited (the default).

empty

Requires type to be "links".

Setting this parameter true requests that this tag should include a hyperlink for the empty "--select--" option.  In the form example, above, if "empty=1" had been specified then three links would have been generated.

extra

The value of this parameter will be appended to the list of attributes attached to the widget's HTML tag.  The following example illustrates the append, extra and js parameters:

which will generate:

form

Requires type to be "links".

This sets the base value for the form in a "links widget.  The default is "mv_action=return", which will simply set the variable value in the link.

For example, to generate a series of links (one per item attribute value passed), that sets the variable "colour" to the corresponding passed value (blank, "blue", or "green"), do this:

This will generate something like the following:

If you want the empty "--select--" option to show up then pass an empty=1 parameter to this tag.

href

Requires type to be "links".

This sets the base href for the link in a links type.  The default is the current page.

joiner

Requires type to be "links".

With "type=links", this tag returns a link for each option.  This allows you to override the default string (<br>) that joins these links.  You can use Perl's meta-character escapes, such as "\n" for newline or "\t" for tab.

js

This parameter allows you to place JavaScript within the start tag of the widget's HTML output.

See the extra parameter for a usage example.

The "js" parameter has no default, except when "type=move_combo", where the default is: 

new

Requires type to be "combo" or "reverse_combo".

You can use this to set a value in place of the "New" or "Current" option in a combo box.  For example, if item "os28044" has "size" attribute values of "Sm=10oz, Med=15oz, Lg=20oz":

will generate:

Or, with the default "new" value:

will generate:

The default is no value with option text set to "<-- New" if type is "combo", or "Current -->" if type is "reverse_combo".

name

This sets the name of the form variable to use, if appropriate for the widget being built.  This defaults to "mv_order_attribute".  I.e. if the attribute is named "size" then the form variable will be named "mv_order_size".

If the variable is set in the user's session then the widget will retain its previous setting.  In other words, [value name] will contain the previous setting and the widget will use it as its default setting.  Also see the default parameter.

outboard

If you need to select from a database table who's primary key is different from the product's SKU code, then you can use this parameter to pass the key value that should can be used to find the accessory data.

This is especially useful when using [PREFIX-accessories], as that loop sub-tag cannot be passed a code parameter.

passed

You can use this to pass your own values to the widget built by this tag.  If you have set passed to a list of widget options, then this tag will simply build a widget, of the specified type, with your values - instead of fetching an attribute value list from the database.

For example, to generate a select widget with a blank option (perhaps forcing a select), the value of "blue" with a label of "Blue" and the value of "green" with a label of "Sea Green", use the following:

Which will generate:

prepend

You can set a string to prepend to the returned output of the tag.  Note that this is not a list to prepend to the fetched attribute value list, which is treated within the tag.

For example,

will generate:

price

When combined with the price_data parameter, this allows you to force prices for item attributes.  You probably do not want to use this;  Just let the tag pick up prices from your database, as appropriate.

If you're passing attribute values, you can use this parameter to control the displayed price in the widget, as follows:

which will generate:

price_data

rows

This tag will pass the number you choose through to the HTML "rows=Y" parameter in HTML widgets that accept it.

For some types, you can also define widget rows and columns within the string that sets the type.  For example, type="textarea_6_33_wrap=virtual" specifies a <textarea> widget with "rows=6", "cols=33" and "wrap=virtual".  You should resort to this only when you cannot use the named parameters, for example within the [PREFIX-accessories] tag.

The result of setting conflicting values in the type string and the "rows=Y" attribute is undefined.

See also cols, below.

secure

Requires type to be "links".

Setting this parameter true will cause the generated link(s) to point to your secure (HTTPS/SSL) Interchange URI.  See the SecureURL local configuration directive.

table

This is the database table containing the item's attribute values.  It defaults to the first of the ProductFiles tables, found to contain a matching SKU.

If you have configured your database so that the attributes are kept in a different table from other item data, then the primary key should be named "code" and contain product SKUs.  If you're using "[PREFIX-accessories]" and cannot Specify "code=key" then use the outboard parameter instead.

template

Requires type to be "links".

Allows you to override the standard Interchange template for a hyperlink.  You probably don't need to use this.  Grep the Interchange core code to grok it if you do (find the "build_accessory_links" subroutine in the core).

type

This parameter may be used to select a display widget from the following list:

Action	Description	Versions
select	Builds a drop-down <select> menu for the item attribute, with the default item attribute value selected.  The accessories tag builds a select widget by default if a type is not specified.	All
display	Shows the label text for only the selected option if called in hash list context, such as within an [item-list].  This parameter is ignored otherwise, and the tag will build the default <select> menu.	All
show	Returns the list of possible attributes for the item, without labels or a HTML widget.  For example, if SKU "os28044" is available in several sizes:  [accessories os28044 size,show] Sm=10oz, Med=15oz*, Lg=20oz	All
options	This shows the attribute options as a newline-delimited list:  [accessories os28044 size,options] Sm Med Lg	All
labels	This shows the attribute option labels:  [accessories os28044 size,options] 10oz 15oz* 20oz	All
radio	Builds a radio button group for the item, with spaces separating the elements.	All
radio_nbsp	Builds a radio box group for the item, with &nbsp; separating the elements.	All
radio_break	Builds a radio button group for the item, with <br> separating the radio button/label pairs from one another.	All
radio_left_n	Builds a radio button group for the item, inside a table, with the radio buttons on the left hand side.  If n is present, and is a digit from 2 through 9, then it will align the options in that many columns.  You can also set the font size like this:  type="radio left n fontsizeX" where X is in the range of -9 through 9.	All
radio_right_<i>n</n>	Builds a radio button group for the item, inside a table, with the checkbox on the right hand side.  If n is present, and is a digit from 2 through 9, then it will align the options in that many columns.  You can also set the font size like this:  type="radio right n fontsizeX" where X is in the range of -9 through 9.	All
check	Builds a checkbox group for the item, with spaces separating the elements.	All
check_nbsp	Builds a checkbox group for the item, with &nbsp; separating the checkbox/label pairs from one another.	All
check_break	Builds a checkbox group for the item, with <br> separating the checkbox/label pairs from one another.	All
check_left_n	Builds a checkbox group for the item, inside a table, with the checkbox on the left hand side.  If n is present, and is a digit from 2 through 9, then it will align the options in that many columns.  You can also set the font size like this:  type="check left n fontsizeX" where X is in the range of -9 through 9.	All
check_right_n	Builds a checkbox group for the item, inside a table, with the checkbox on the right hand side.  If "n" is present, and is a digit from 2 through 9, then it will align the options in that many columns.  You can also set the font size like this:  type="check right n fontsizeX" where X is in the range of -9 through 9.	All
textarea	Builds a textarea with the selected item attribute value if used in Hash List context, such as within an [item-list] tag.  the textarea will be built with 4 rows and 40 columns, unless you specify a rows or cols parameter.	All
textarea_Y_X	Builds a textarea with Y rows and X columns.  The textarea will contain the selected item attribute value if used in Hash List context, such as within an [item-list] tag.	All
text	Builds a text input widget.  The widget's value will be set to the selected item attribute value if used in Hash List context, such as within an [item-list] tag.  The text input widget will be built to be 60 characters wide unless you specify a cols parameter.	All
text_X	Builds a text input widget, X characters wide.  The widget's value will be set to the selected item attribute value if used in Hash List context, such as within an [item-list] tag.	All
combo	Special type, used with nullselect filter, for selecting from a list or inputting a new value.	All
reverse_combo	Special type, used with the last_non_null filter, for selecting from a list or inputting a new value.  This differs from combo in the order of presentation.	All
move_combo	Special type, used with null_to_space or null_to_comma filters, for selecting multiple non-ordered values from a list, or inputting into a textarea.	All
links	Produces a series of links based upon the option values.  The base form value is passed via the form parameter, just like in an [area] or [page] tag, and the value is named with the passed name attribute.	All
value	Returns the selected value if called in hash list context, such as within an [item-list] tag.  Otherwise it returns nothing at all.	All
hidden	Creates a hidden form field.  The hidden field's value will be set to the selected item attribute's value if used in hash list context, such as within an [item-list] tag.	All
password	A password input widget.  The widget's value will be set to the selected item attribute value if used in Hash List context, such as within an [item-list] tag.  The password input widget will be built to be 12 characters wide unless you specify a cols parameter.	All
password_X	A password input widget, X characters wide.  The widget's value will be set to the selected item attribute value if used in Hash List context, such as within an [item-list] tag.	All

The default is "select", which builds a HTML <select> form entry widget for the attribute.

Availability "All versions" refers to Interchange 5.0.0 and above, as 5.0.0 is the baseline for the documentation on this website.  Most of the parameters marked "All" were available long before version 5.0.0 was released.

Some types build widgets that use rows=Y, cols=X, or certain other HTML attributes.  For these, you can define widget rows and columns within the string that sets the type.  For example, type="textarea_6_33_wrap=virtual" specifies a <textarea> widget with "rows=6", "cols=33" and "wrap=virtual".  You should resort to this only when you cannot use the named parameters.  For example within an [PREFIX-accessories] tag.  Otherwise pass the rows=Y and cols=X parameters to this tag instead.

The result of setting conflicting values in the type string and the rows and cols attributes is undefined.

The following list shows syntax for type strings, where X is the number of columns and Y is the number of rows.

• text
  • textarea (default is 4 rows and 40 columns, like "textarea_4_40")
  • textarea_Y_X
  • text_cols
  • textarea rows=Y cols=X wrap=W value
• password
  • password (default is 12 columns, like "password_12")
  • password_X
• combo (similarly for reverse_combo and move_combo)
  • combo (default is 1 row and 16 columns, like 'combo_1_16')

In any of the option building types, you can append the string ranges and a special option processing will be done -- any option matching the pattern [A-Za-z0-0]..[A-Za-z0-0] will be expanded into a comma separated range between the bounds.  The same behaviour is accomplished by passing the accessories tag option ranges.  For example: 

and

will both output: