This allows the selection of one or more values
from a given list. It is possible to enable adding "unreferenced" items in a "others"
listing, but those are outside the normal processing.
Available configuration options:
- array options: The allowed option listing, a key/value map. Only the keys
are stored in the storage location, using serialized storage. If you set this to
null, option_callback has to be defined instead. You may not define both
options.
- string option_callback: This must be the name of an available class which
handles the actual option listing. See below how such a class has to look like.
If you set this to null, options has to be defined instead. You may not
define both options.
- mixed option_callback_arg: An additional argument passed to the constructor
of the option callback, defaulting to null.
- boolean allow_other: If this flag is set, the system allows the addition of
values not in the option list. All unknown values will be merged into a single
comma separated listing of unknown options during loading, which will be kept in
that simple string representation. Otherwise, unknown keys will be forbidden, on
validations they cause a validation error, on loading they are dropped silently.
This option is set to false by default.
- boolean allow_multiple: If this flag is set, you may select more then one
option. This is disabled by default. If this feature is disabled, the loader
code will drop all matches beyond the first match.
- boolean csv_export_key: If this flag is set, the CSV export will store the
field key instead of its value. This is only useful if the foreign tables referenced
are available at the site of import. This flag is not set by default. Note, that
this does not affect import, which is only available with keys, not values.
- string multiple_storagemode: Controls how multiple options are stored in
a single field. See below "multiselect storagemodes". Defaults to "serialized".
- boolean sortable: Switch for determining if the order selected by the widget
should be stored to the metadata object
Keys should be alphanumeric only.
Multiselect storage modes
This type knows three ways of storing multiselect data:
- 'serialized' will just store a serialized array
- 'imploded' will implode the keys using '|' as a separator
- 'imploded_wrapped' behaves like 'imploded' except that it will wrap the saved
string again in '|'s thus yielding something like |1|2|3|...|. This is useful
if you want to use like queries to look up values in such fields.
Naturally, both 'imploded' storage modes don't allow a '|' being part of a key.
This is only checked during storage (due to performance reasons); if an invalid
element is found there, it will be skipped and logged. No error will be shown
on-site.
Option Callback class
These classes must implement midcom_helper_datamanager2_interface
The class is loaded using require_once by translating it to a path relative to midcom_root
prior to instantiation. If the class cannot be loaded from the filesystem but from a
snippet, you need to include that snippet previously, an auto-load from there is not
yet possible.
Methods
_convert_multiple_from_storage (mixed $source)
Converts the selected options according to the multiple_storagemode setting.
Parameters
$source
mixed
The stored data.
Returns
array
The stored data converted back to an array.
_convert_multiple_to_storage ()
Converts the selected options according to the multiple_storagemode setting.
Returns
mixed
The data converted to the final data storage.
_get_imploded_options ()
Prepares the imploded storage string.
All entries containing the pipe char (used as glue)
will be logged and skipped silently.
Returns
string
The imploded data string.
_on_initialize ()
Initialize the class, if necessary, create a callback instance, otherwise
validate that an option array is present.
_on_validate ()
The validation callback ensures that we don't have an array or an object
as a value, which would be wrong.
Returns
boolean
Indicating validity.
convert_from_csv ($source)
CSV conversion works from the storage representation, converting the arrays
into simple text lists.
convert_from_storage ($source)
Converts storage format to live format, all invalid keys are dropped, and basic validation
is done to ensure constraints like allow_multiple are met.
convert_to_csv ()
CSV conversion works from the storage representation, converting the arrays
into simple text lists.
convert_to_storage ()
Merges selection and others arrays, the validation cycle ensures that they are
right.
Returns
array
The storage information.
get_name_for_key (string $key)
Returns the full name for a given key.
This value is not localized in any way.
Parameters
$key
string
The key index to look up.
Returns
string
The name of the key in clear-text, or null, if the key was not found.
key_exists (string $key)
Checks whether the given key is known.
Parameters
$key
string
The key index to look up.
Returns
boolean
True if the key is known, false otherwise.
list_all ()
Returns the full listing of all available key/value pairs.
Returns
array
Listing of all keys, as an associative array.
Properties
string $_callback
In case the options are returned by a callback, this member holds the callback
instance.
boolean $allow_multiple
This flag controls whether multiple selections are allowed, or not.
boolean $allow_other
Set this to true if you want to allow selection of values not part of the regular
selection list.
In this case you'll find the other options collected in the $others
member.
boolean $csv_export_key
Set this to true if you want the keys to be exported to the csv dump instead of the
values.
Note, that this does not affect import, which is only available with keys, not
values.
string $multiple_separator
Glue that will be used for separating the keys
string $multiple_storagemode
The storage mode used when multiselect is enabled, see the class' introduction for
details.
string $option_callback
In case the options are returned by a callback, this member holds the name of the
class.
mixed $option_callback_arg
The argument to pass to the option callback constructor.
array $options
The options available to the client.
You should not access this variable directly,
as this information may be loaded on demand, depending on the types configuration.
string $others
This member contains the other key, in case it is set.
In case of multiselects,
the full list of unknown keys is collected here, in case of single select, this value
takes precedence from the standard selection.
This is only valid if the allow_other flag is set.
boolean $require_corresponding_option
Set this to false to use with chooser, this skips making sure the key exists in option list
Mainly used to avoid unnecessary seeks to load all a ton of objects to the options list.
array $selection
A list of the currently selected keys.
This is an array even for single select
types, in which case the validation limits it to one item. The values array
consists only of the object keys, use the resolver function to get the corresponding
values.
boolean $sortable
Should the sorting feature be enabled.
This will affect the way chooser widget will act
and how the results will be presented. If the sorting feature is enabled,