Dynamic Attributes

New in 0.2: Attribute definitions can specify which v10 artifact (Document, DocumentRevision) the definition is refering to. That definition will appear in that artifact.

New in 0.3 Attribute defining artifacts can specify which v10 artifacts the definition refers to (see above) as well as a field value pair that the attribute is made available in (e.g.: when using artifact field status_id = Status::IN_ELABORATION)

Frontend

You must define the view for this particular form (that is create the .html file corresponding to the view model where the attributes are to be defined). Inside the view you must include the administration generic component for adding / removing attribute definitions to the model (via compose):

<compose view-model="wemake-modules/administration/attributes/reusable-components/attribute-definitions/index" model.bind="model"></compose>

The reusable component may bind a model or an object like so:

{
    model: model_variable,
        attributable_fqcn
:
    'WeMake\\Sgi\\Modules\\Plans\\Models\\PlanTypeDefinition'
}

Note that the attributable_fqcn parameter defines the artifact that defines the attributes. In this example plan type definition can define attributes for plans and plan actions (we'll see how to set this up in the backend). If your definer of attributes only defines attributes for a single artifact just leave this out (or bind the model direcly to reusable components / attribute definitions).

The frontend model must define a variable named attributes initialized with an empty array.

Backend

The model that will contain the definitions for the dynamic attributes must have the HasAttributeDefinitions trait and implement the AttributeDefinitionsContract.

Attributes sent by the frontend may be saved like so:

// Save the attribute definitions
// Note: just send the definitions into this function
$model->saveAttributeDefinitionsFromFrontend($request->clean('attribute_definitions'));

The $model variable must be a model with the HasAttributeDefinitions trait, the $attributes variable contains the attribute definition list send by the frontend (see frontend tab for more information).

If the model is expected to define attributes for multiple artifacts, then you need to also implement the AttributeDefinitionsContract. This contract asks you to implement 2 new functions on your model:

    /**
     * This function returns a collection of valid attribute value artifact targets
     * for use in attaching the values of a given definiton to an artifact target
     * Note: you may also return (optionally) a list of target fields and allowed values for each 
     * target field that will make the attribute appear only when field = value
     */
    public static function getAllowableAttributeValueArtifactTargets() {
        return collect([
            [
                'id'   => Plan::class,
                'name' => trans('form.title.plan'),
                'target_fields' => [
                    [
                        'name' => trans('form.field.status'),
                        'id'   => 'status_id',
                        'allowed_values' => [
                            [
                                'name' => trans('form.field.in-elaboration'),
                                'id'   => 1
                            ]
                        ]
                    ]
                ]
            ],[
                'id'   => PlanAction::class,
                'name' => trans('form.title.action')
            ]
        ])->values();
    }

    /**
     * This function returns the default attribute value artifact target for this
     * attribute definition (for creating new definitions for this artifact or interpreting existing
     * definitions whose value artifact target column is null)
     */
    public static function getDefaultAttributeValueArtifactTarget() {
        return Plan::class;
    }

The first function provides a list (to be used in a combo) of valid artifacts for this model as a definer of attributes, as well as potential target fields and their acceptable values if you want to make an attribute appear only when that field equals the selected value. The second function indicates the default artifact as a value target for previously (before this change) created attributes.

Compose the attribute values form component like so:

<compose view-model="wemake-modules/administration/attributes/reusable-components/attribute-values-form/index" model.bind="dynamicAttributeOptions"></compose>

After the frontend has obtained the attributes define the model for the compose above like so:

this.dynamicAttributeOptions = {
    // Model to which the values are to be attached
    attributable_fqcn_filter: 'WeMake\\Sgi\\Modules\\Plans\\Models\\Plan',

    // If a target filter has been defined, enter it here
    artifact_field_filter: null,

    // If a target value has been defined, enter it here
    artifact_field_value_filter: null,

    // List of attributes as sent from the backend
    attribute_definitions: attributes,

    // Model instance
    model: this.model,

    // Place within the model where the attribute values are stored
    // (Optional, used if a single model stores multiple attribute value 
    // groups for multiple backend models)
    attribute_model_override: 'plan_attributes'
};

Note: if the definer of these attributes can target multiple artifacts, you must set the attributable_fqcn_filter to the artifact being created / edited.

The values entered in the attribute fields will be transmited to the server allong with everything else when the user submits the information.

The model that will contain the values for the defined attributes must have the HasAttributes trait.

In the requests StoreRequest and UpdateRequest for the model that contains the attribute values, you may validate the values for each attribute by using the function the HasAttributeDefinitions trait adds to the defining artifact like so:

/* rules function (Request class) */
public function rules()
{
    /* other code */

    // Dynamic attribute rules
    $attributeRules = $definingArtifact->generateRequestRules(
        // Using Artifact fqcn
        Occurrence::class,

        // Target field (optional)
        'status_id',

        // Target field value (optional, required if target field in use)
        Stage::REGISTRATION
    );

    // Merge the artifact rules with the existing rules
    $rules = collect($rules)
            ->merge($attributeRules)
            ->toArray();

    /* ... */
    return $rules;
}

public function attributes()
{
    /* other code */

    // Dynamic attribute names
    $stageAttributes = $definingArtifact->generateAttributeListForRequest(
        // Using Artifact fqcn
        Occurrence::class,

        // Target field (optional)
        'status_id',

        // Target field value (optional, required if target field in use)
        Stage::REGISTRATION
    );

    // Merge the artifact rules with the existing attributes
    $attributes = collect($attributes)
        ->merge($stageAttributes)
        ->merge($genericCodeAttributes)
        ->toArray();

    /* ... */
    return $attributes;
}

In the controller just add the following code after the model has been saved (the model must be saved before this):

$document->saveAttributeValues(
    $request, // pass the request (function will extract attribute values from here)
    Family::class, // pass the fqcn of the model that defines the attributes
    $request->clean('doc_family_id') // pass the id of the model that defines the attributes for this particular set of attribute values
);

And that is it. Both the definitions and attributes have been saved correctly.