Datamanager 2 simple select type.

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.

package midcom.helper.datamanager2

 Methods

_convert_multiple_from_storage (mixed $source)

Converts the selected options according to the multiple_storagemode setting.

Parameters

$source

mixedThe stored data.

Returns

arrayThe stored data converted back to an array.

_convert_multiple_to_storage ()

Converts the selected options according to the multiple_storagemode setting.

Returns

mixedThe 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

stringThe 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

booleanIndicating validity.

combine_values ()

convert_from_csv ($source)

CSV conversion works from the storage representation, converting the arrays into simple text lists.

Parameters

$source

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.

Parameters

$source

convert_to_csv ()

CSV conversion works from the storage representation, converting the arrays into simple text lists.

convert_to_html ()

convert_to_storage ()

Merges selection and others arrays, the validation cycle ensures that they are right.

Returns

arrayThe 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

stringThe key index to look up.

Returns

stringThe 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

stringThe key index to look up.

Returns

booleanTrue if the key is known, false otherwise.

list_all ()

Returns the full listing of all available key/value pairs.

Returns

arrayListing 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.

see \get_all_options()
 

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,