Datamanager 2 m:n membership management type.

This subclass provides specialized I/O procedures which allow implicit management of m:n object mappings. For example this can cover the person member assignments of a midgard_group. The mapping class used is configurable, thus it should be adaptable to any standard m:n relationship.

The member objects used to construct this mapping must be fully qualified DBA objects where the user owning the master object has full control, so that the objects can be updated accordingly. It is recommended to make the member objects children of the master objects. In addition, edit, delete and create rights should always go together.

To work properly, this class needs various information: First, there is the name of the member class used to do the mapping. In addition to this, two fieldnames of that class must be supplied, one for the GUID of the master object, the other for the identifier of the membership.

Optionally, you can set the class to use the master object ID in case of the GUID, this is there for legacy code ("midgard_members") which do not use GUIDs for linking yet. The linked object ("membership") is always referenced by the key selected in the corresponding widget.

An additional option allows you to limit the "visible" member key space: You specify query constraints. When updating members, only member records matching these constraints will be taken into account. This is quite useful in case you want to split up a single selection into multiple "categories" for better usability. The constraints are taken into account even when saving new keys so that all load and save stays symmetrical. If you use this feature to separate multiple key namespaces from each other, make sure that the various types do not overlap, otherwise one type will overwrite the assignments of the other.

When starting up, the type will only validate the existence of the mapping class. The members specified will not be checked for performance reasons. In case something wrong is specified there, it will surface during runtime, as invalid mapping entries will be silently ignored (and thus saving won't work).

This type should be set to a null storage location

Available configuration options:

string mapping_class_name: Mandatory option. Holds the name of the DBA class used for the mapping code. The class must satisfy the above rules.
string master_fieldname: Mandatory option. Holds the fieldname containing the (GU)ID of the master object in the mapping table.
string member_fieldname: Mandatory option. Holds the fieldname containing the membership keys in the mapping table.
boolean master_is_id: Set this to true if you want the ID instead of the GUID to be used for mapping purposes. Defaults to false.
array constraints: These constraints limit the number of valid member keys if set (see above). It defaults to null meaning no limit.
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 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.
boolean sortable: Switch for determining if the order selected by the widget should be stored to the metadata object
string sortable_sort_order: Direction that metadata.score should go. If this is set to ASC, lower scores will be displayed first. If this is set to DESC, higher scores will be displayed first. DESC is default, since then new member objects will be left at the end of the line rather than appearing first. This field is not case sensitive and string can be extended e.g. to ascend.
array additional_fields: Additional fields that should be set on the mnrelation object

(These list is complete, including all allowed options from the base type. Base type options not listed here may not be used.)

Option Callback class

See base type.

Implementation notes

This class essentially extends the select type, rewriting its I/O code to suite the needs of a member management type.

Therefore, we force-override a few settings to ensure operability: allow_other will always be false, while allow_multiple always be true.

package	midcom.helper.datamanager2

Methods

_on_initialize ()

Initialize the class, if necessary, create a callback instance, otherwise validate that an option array is present.

convert_from_storage ($source)

Reads all entries from the mapping table.

This overrides the base types I/O code completely.

var

Parameters

$source

convert_to_csv ()

convert_to_raw ()

convert_to_storage ()

Updates the mapping table to match the current selection.

Returns

\Returnsnull.

_get_master_foreign_key ()

Returns the foreign key of the master object.

This is either the ID or the GUID of the master object, depending on the $master_is_id member.

var	Foreign key for the master field in the mapping table.

_get_new_membership_objects ($existing_members)

Parameters

$existing_members

_load_membership_objects ()

Loads all membership records from the database.

May only be called if a storage object is defined.

Properties

Array $additional_fields

Additional fields to set on the object

boolean $allow_multiple

This flag controls whether multiple selections are allowed, or not.

array $constraints

Array of constraints, always AND

Example:

    'constraints' => array
    (
        array
        (
            'field' => 'username',
            'op' => '<>',
            'value' => '',
        ),
    ),

string $mapping_class_name

Mandatory option.

Holds the name of the DBA class used for the mapping code

string $master_fieldname

Mandatory option.

Holds the fieldname containing the (GU)ID of the master object in the mapping table.

boolean $master_is_id

Set this to true if you want the ID instead of the GUID to be used for mapping purposes.

string $member_fieldname

Mandatory option.

Holds the fieldname containing the membership keys in the mapping table.

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.

This is false by default for mn relations, since by its nature this is intended for dynamic searches.

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,

string $sortable_sort_order

Sort order.

Which direction should metadata.score force the results. This should be either ASC or DESC

Array $sorted_order

Sorted order, which is returned by the widget.

Array $_membership_objects

This is a QB resultset of all membership objects currently constructed.

It is indexed by membership record guid. It will be populated during startup, when the stored data is loaded. During save, this list will be used to determine the objects that have to be deleted.

Only objects matching the constraints will be memorized.