Assistant documentation

The following documentation provides all necessary information to set up your own assistant and will guide you through its creation step by step.

Further reading

1. Assistant registration

Assistant structure

  1. Create a class that extends “WizardProvider” (use Plenty\Modules\Wizard\Services\WizardProvider)
  2. Your class must contain a method named “structure” (protected function structure()) that returns an array. Working example: namespace Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard

Assistant registration

  • In a module, in its ModuleServiceProvider use Plenty\Modules\Wizard\Contracts\WizardContainerContract; use \YourWizard; In boot() method: boot(WizardContainerContract $wizardContainerContract) wizardContainerContract->register(‘wizardKey', YourWizard::class);
  • In a plugin, in its PluginServiceProvider use Plenty\Modules\Wizard\Contracts\WizardContainerContract; use \YourWizard; In boot() method: pluginApp(WizardContainerContract::class)->register('wizardKey', PluginWizard::class);

How to check if your assistant was registered

GET on “/rest/wizards” will return a list of all registered wizard classes. GET on “/rest/wizards/wizardKey” will return the wizard registered with that key.

2. Assistant translations

Purpose

Texts which are displayed in the assistant UI must be provided in different languages (at least German and English). Depending on the selected language of the backend user, the corresponding translations of the texts are shown.

Architecture

Translation is done on the server side. When the UI requests the structure of a specific assistant represented by its WizardProvider, the file is parsed and all the keys stated under translatable properties will be replaced by their actual translation.

Files

The translations for each language will be stored in a separate file. In modules/packages and plugins, the files are stored in /resources/lang/{lang}/filename.{extension}

Extension is

  • .php in modules
  • .properties in plugins

Assistants should be provided only by modules/packages and plugins. The WizardProvider must not include any plain texts. Texts are replaced by translation keys which refer to the actual translated texts in the translation files.

Properties

Properties of the wizard model which are translated:

  • title (assistant, step, section)
  • shortDescription (assistant)
  • description (step, section)
  • createOptionIdTitle
  • createOptionIdCardLabel

In addition to that, the following properties of the DynamicFormElements need to be translated:

  • label
  • caption
  • tooltip
  • name
  • placeholder

Keys

Structure of a key: "FILENAME.KEY", e.g Assistant.text1 NAMESPACE is mandatory.

Step-by-step

  1. Create your translation files (/resources/lang/{lang}/FileName.{extension}). Extension is
    • .php in modules
    • .properties in plugins
  2. Make sure your translations are loaded. a. In plugins they are loaded automatically. b. In modules you need to load them in “boot()” method of your ServiceProvider. Example: $this->loadTranslationsFrom(__DIR__.'/../resources/lang', 'module_wizard');
  3. In order for translations to work, the assistant’s structure must have the key “translationNamespace”. Example: "translationNamespace" => "module_wizard"
  4. Assign the translatable properties to keys that are set in your translation files. Example: "title" => "FileName.wizardTitle"

Check out the TestWizard’s structure inside the wizards module for a working example. The step “stepTranslationExample” is translated as well. namespace Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard

3. Assistant structure

3.1 Overall structure

The overall structure contains basic information about the assistant, options and form elements.

Basic information and classes

  • title:string|key required; overall title of the assistant
  • key:string required and unique
  • iconPath:string optional; an icon that will be displayed alongside with the title of the assistant
  • shortDescription:string|key Describes the purpose of the assistant. It is displayed as info on the assistant card.
  • reloadStructure:boolean optional; Default false; If set to true, the assistant’s structure will be reloaded whenever a user enters the assistant.
  • settingsHandlerClass:string required; refers to the server-side class which executes all necessary functionality for transferring dedicated data from DynamoDB to the plentymarkets DB and for configuring the plentymarkets user system.
  • actionHandlerClass:class
  • dependencyClass:string
  • topics:string[] // [‘multichannel.amazon’, ‘Amazon Vendor’] required; must contain one topic which describes the domain of the settings in plentymarkets system; can contain additional topics
  • options:key => DynamicFormElement optional; contains a list of form elements to enable the user to compose an optionId (unique identifier for a combination of options); states whether an assistant can be run multiple times
  • relatedWizards:string[] optional; A list of related assistants identified by their key. These related assistants will be presented after the assistant has been finalised - in the order determined by the developer.
  • priority:number defines the position of the assistant in the sorted assistants overview; number between 0 (low priority) and 499 (high priority)
  • steps:key => Step required and unique for the assistant
  • relevance:string[] optional; Default optional; If set to essential, the assistant will be marked as such and shown in the recommended assistants overlay.
  • tableColumns:string[] optional; Default options (if set); If set, the according options or form elements will be shown as table columns.
  • cardRows:string[] optional; Default options (if set); If set, the according options or form elements will be shown on the cards of the assistant option browser’s view.

Priority and order of assistants in overview

Depending on its priority, you can position your assistant between 0 (low priority) and 499 (high priority). The higher the priority, the further up it is displayed in the assistants overview.

3.2 Assistant options

Options can be used to run an assistant multiple times with different configurations. Just like the form elements in the steps, options are displayed via form fields. These fields are rendered in the overlay and users have to select beforehand, for which configuration they want to run the assistant. If no form elements are specified (such as the id in the example), no overlay is displayed.

If you want to generate the optionId after specific form elements from the steps have been filled by the user. You can add them on the same level as an array with the keys. The optionId is automatically generated from those specified elements. We recommend to designate the array as “data” and it has to be unique. In the example below, the optionId would consist of iban, mambo, phoneNumber and id.

    "options" => [
       "data" => [
           "iban",
           "mambo",
           "phoneNumber"
       ],
       "id" => [
           "type" => 'text',
           "options" => [
               "name" => 'ID',
               "required" => true
           ]
       ]
    ],
  

3.3 Form elements

General properties and form elements

...of any form element

key:string => {

  • type:string; Type of the form element. See section Type dependent options for a list of all available types.
  • isVisible?:boolean | string; Determines whether the form element is visible. A boolean value or a JSCondition as string is accepted.
  • defaultValue?:any; If no value is set, this is the default value of the element.
  • options?:{ [key:string]:any }
    • name:string Name of the form element (not the key).
    • isDisabled:boolean // not available for note- and codeEditor Determines whether the form element is disabled.
    • required:boolean Validator. If true, any value must be entered into this form element.
    • minLength:number Validator. The entered text must equal or exceed the given number of chars.
    • maxLength:number Validator. The entered text must not exceed the given number of chars.
    • minValue:number Validator. The entered value must equal or exceed the given value.
    • maxValue:number Validator. The entered value must not exceed the given value.
    • email:boolean Validator. If true, the entered value is checked to be a valid email address.
    • pattern:RegExp | string Validator. If given, the entered value will be checked to match the given pattern.

Type dependent options

checkbox

  • icon:string Set an icon (e.g. icon-save).

date

  • openCalendarTop:boolean If true, the calendar will be opened on top. Default false.
  • displayDateFormat:string Set the date format. Default 'dd.mm.yyyy'.

file

  • showPreview:boolean If true, a preview for image files is shown.
  • allowedExtensions:string[] List of allowed file extensions
  • allowFolders:boolean If true, a group can be selected.

text

  • isPassword:boolean If true, the type of input will be 'password'.
  • isIban:boolean If true, the input will check whether the input is a valid iban.
  • isReadonly:boolean If true, the value cannot be changed.

textarea

  • hasFixedHeight:boolean If true, the text area is not resizeable. Default false.
  • maxRows:number A unique string identifier for the specific input instance.

number

This form element has no special options.

double

  • isPriceInput:boolean If true, the value will be right-aligned.
  • decimalCount:number Set the decimal count. Default is 2. (0.01)

select

  • openOnTop:boolean If true, the dropdown with options opens on top of the window.
  • decimalCount:number listBoxValues:TerraSelectBoxValueInterface[] List of possible options.

Example:

    "userClass" => [
 "type" => "select",
 "options" => [
     "name" => "User classes",
     "listBoxValues" => [
         [
             "caption" => "Admin",
             "value" => 1
         ],
         [
             "caption" => "Variable user",
             "value" => 2
         ],
         [
             "caption" => "Blog",
             "value" => 3
         ]
     ]
 ]
]

button

If an action is given, state a class containing the requested method at the assistant structure’s actionHandlerClass property. The actionHandlerClass must implement the WizardActionHandler interface.

  • icon:string Set an icon (e.g. icon-save).
  • name:string Set the caption of the button where the link will be opened.
  • action:string The name of the method of the corresponding actionHandlerClass that should be executed when the button is clicked.
  • link:object Specify the link.
    • fromAction:boolean States whether the given action returns a URL that should be used as a link.
    • newWindow:boolean Specify whether the link should be opened in a new window or in the current browser tab.
    • url:string A static URL which will serve as a link.

category

  • displayResetButton:boolean If true, the reset button is shown.
  • displaySearch:boolean If true, an input to search for any category is shown.
  • showFullSelectionPath:boolean ...

color

This form element has no special options.

slider

  • min:number lower limit of the slider
  • max:number upper limit of the slider
  • interval:number step size of the slider
  • precision:number amount of digits that will be shown when displaying any values (current value, lower limit, upper limit, ticks) in the slider.
  • showMinMax:boolean If set to true, the upper and lower limits will be displayed.
  • showTicks:boolean If set to true, the ticks' label will be displayed.

checkboxGroup

  • collapsed:boolean Set the initial collapsed state. Default false
  • checkboxValues:{caption:string, value:any}[] List of possible options

Example:

    "userRoles" => [
       "type" => "checkboxGroup",
       "isVisible" => "userClass !== 1",
       "defaultValue" => [2],
       "options" => [
           "name" => "User roles",
           "checkboxValues" => [
           [
               "caption" => "Role 1",
               "value" => 1
           ],
           [
               "caption" => "Role 2",
               "value" => 2
           ],
           [
               "caption" => "Role 3",
               "value" => 3
           ]
           ],
       ]
    ]
  

radioGroup

  • radioValues:{caption:string, value:any}[] List of radio buttons that may be selected

toggle

This form element has no special options.

noteEditor & codeEditor

  • placeholder:string Text which is shown until anything is entered.
  • fixedHeight:string Height of the area where content can be added.
  • minHeight:string Minimum height of the text area where content can be added.

4. Assistant dynamic form fields

Dynamic form fields are optional for any assistant. Using dynamic form fields, you can dynamically create a form field structure in the UI.

The dynamic form field structure is built when a dependency key has a value set. Its purpose is to provide dynamically built form fields while a step is in progress.

How to create a dynamic loader

  1. Create a class that implements “WizardDynamicLoader”. <use Plenty\Modules\Wizard\Contracts\WizardDynamicLoader; >
  2. Create a public function methodName(array $parameters) and add your functionality to it. This method should return the form field structure!

Working example: namespace Plenty\Modules\Wizard\Wizards\TestWizard\DynamicLoaders\TestDynamicLoader;

How to use a dynamic loader in a form field

In your assistant's structure, add the following:

In a module

  • "dependencyClass" => YourDynamicLoader::class, Make sure you use \YourDynamicLoader;

In a plugin

  • "dependencyClass" => “\YourDynamicLoader”,

In your assistant's structure, add the following to the corresponding form.

  • "dependencies" => [‘anotherFormKey’],
  • "dependencyMethod" => “methodName”,

Working example: namespace Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard

5. Assistant data modifiers

Modifiers are optional for any assistant. Using modifiers, you can change or add any property to the data object.

The data modification is performed when a step is saved, before validation. Its purpose is to provide additional PHP functionality.

How to create a modifier

  1. Create a class that implements “WizardDataModifier”. < use Plenty\Modules\Wizard\Contracts\WizardDataModifier; >
  2. Create a public function modify(array $data) and add your functionality to it.
  3. Make sure you return the $data after you modify it!

Working example: namespace Plenty\Modules\Wizard\Wizards\TestWizard\Modifiers\TestWizardStepDataModifier;

How to use a modifier

In your assistant’s structure, add the following to the corresponding step. The configuration is slightly different depending if your assistant is in a module or in a plugin.

  • In a module: "modifierClass" => YourWizardStepDataModifier::class Make sure you use \YourWizardStepDataModifier;
  • In a plugin: "modifierClass" => "\YourWizardStepDataModifier"

Working example: namespace Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard;

6. Assistant data validation

Validation is optional for any assistant. Its purpose is to prevent faulty setup and guarantee that only valid values are stored in DynamoDB. Provided that any validator is registered, before data is actually written to the DB, validation will be performed when a step is saved.

Client side

For simple validations, client side validation should be preferred over server side validation since it gives immediate feedback. Client side validators can be registered using the following options on any form field in the assistant’s structure:

  • required:boolean
  • minLength:number
  • maxLength:number
  • minValue:number
  • maxValue:number
  • isIban:boolean
  • pattern:RegExp|string

Server side

More complex validations – exceeding the possibilities of client side validation – must be performed on the server side.

You can either use existing validators of the PL repo or create your own validation class. All these classes must extend Plenty\Validation\Validator.

How to

  1. Create a validator. a. Create a new PHP class. b. Use Plenty\Validation\Validator and extend it. c. Define validation options using Plenty\Validation\Contracts\AttributeHelperContract functionality.
  2. Register the validator for a step a. In your assistant’s structure, add the following to the corresponding step i. "validationClass" => ::class if your assistant is placed in a module ii. "validationClass" => if your assistant is placed in a plugin

Working example: Plenty\Modules\Wizard\Wizards\TestWizard\Validators\TestWizardDataValidator used in Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard’s first step

7. Assistant settings handler

The assistant settings handler is required for any assistant. Using the settings handler, you can save all data created during the assistant process.

The settings handler is called after the last step is mutated and validated. Its purpose is to provide PHP functionality for saving the entered data on the system’s database.

How to create a settings handler

  1. Create a class that implements “WizardSettingsHandler”. < use Plenty\Modules\Wizard\Contracts\WizardSettingsHandler; >
  2. Create a public function handle(array $data) and add your functionality to it.

Working example: namespace Plenty\Modules\Wizard\Wizards\TestWizard\SettingsHandlers\TestWizardSettingsHandler;

How to use a settings handler

In your assistant’s structure, add the following. The configuration is slightly different depending if your assistant is in a module or in a plugin.

  • In a module: "settingsHandlerClass" => YourWizardSettingsHandler::class Make sure you use \YourWizardSettingsHandler;
  • In a plugin: "settingsHandlerClass" => "\YourWizardSettingsHandler"

Working example: namespace Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard;

8. Assistant data source

Data sources are optional for any assistant. Using data sources you can load data from any source (mySQL tables for example) and store data back on that source.

Its purpose is to provide the ability to create, edit or delete data from SQL tables, but it's not limited to SQL.

How to create a data source

  1. Create a class that extends “BaseWizardDataSource”. < use Plenty\Modules\Wizard\Services\DataSources\BaseWizardDataSource; >
  2. Create a public function getIdentifiers() and add your functionality to it. This method should return an array of option identifiers.

How to use a data source

In your assistant's structure use the following:
In a plugin

  • "dataSource" => “\YourDataSource”,

Getting started with data sources

In a plugin:
updateDataOption() method's $data parameter must be of the type array even though it's not enforced in BaseWizardDataSource. This will be fixed in a future release.

Before you start developing your own data source please make sure you have a look at the example and understand what is the purpose of each method.

To see the example assistant in the UI you need to register it. Uncomment the registration of “custom-data-source” in WizardServiceProvider.php

What happens in the background

Before you start developing your data source, there are some features already developed to ease your work.

The data source will already have:

  • a string property $wizardKey which will have the value set to your assistant’s key
  • an array property $dataStructure which will have the ‘wizardKey’ and ‘data’ keys predefined

wizardKey: your assistant’s key
data: the data object which you will build. By default it’s empty.

On updateDataOption() the data is already modified and validated according to your step settings.

How data should be built before returning it

The $dataStructure’s data property is built differently depending on what you need to display.

You can use the class property $dataStructure in order to prefill. Keep in mind that [‘data’] MUST be an object, because the UI handles it this way.

  $dataStructure = $this->dataStructure;

  $dataStructure['data']->{optionId} = [
  	'formKey' => 'value',
        'formKey2' => 'value'
  ];
  

Or, because in plugins you can’t use dynamic variables.

    $dataStructure['data'] = (object)[
    	'optionId' => [
    'formKey' => 'value',
          		'formKey2' => 'value'
    ],...
    ];
    

With the methods create, get, update and delete you manipulate the entire data for all options.

delete should not return anything.

For this reason, the returned $dataStructure should look like this:

    $dataStructure = [
         'wizardKey' => 'your-wizard-key', // Added automatically
         'data' => (object)[
             'optionId' => [
                 'formKey' => 'value',
                 'formKey2' => 'value'
             ],
             'optionId2' => [
                 'formKey' => 'value',
                 'formKey2' => 'value'
             ]
         ]
    ];
    

An assistant without options will still have a default option with the key "default".

    $dataStructure = [
         'wizardKey' => 'your-wizard-key', // Added automatically
         'data' => (object)[
             'default' => [
                 'formKey' => 'value',
                 'formKey2' => 'value'
             ]
         ]
    ];
    

With the methods createDataOption, getByOptionId, updateDataOption and deleteDataOption you manipulate the data for a single option. deleteDataOption should not return anything.
This is why the returned $dataStructure should look like this:

    $dataStructure = [
         'wizardKey' => 'your-wizard-key', // Added automatically
         'data' => (object)[
             'formKey' => 'value',
             'formKey2' => 'value'
         ]
    ];
    

The method getIdentifiers should return an array of optionIds [‘optionId’, ‘optionId2’, ‘optionId3’,... ]
The method finalize should not return anything. It’s called right before the settings handler.

Screen by screen guide

For more information about what each method should return, see above.

When you access System → Assistants: getIdentifiers is called.

When you enter an assistant to see its options: get is called.

When you click on the menu of an option and delete it: deleteDataOption is called.

When you enter an option or an assistant without options to access the form: getByOptionId is called.

When you click on “Next”: The data is modified and validated according to the step settings
updateDataOption is called.

When you click on “Finalise”: The data is modified and validated according to the step settings.
updateDataOption is called.
finalize is called.
The data is then passed to the assistant’s settings handler.

9. Assistant groups

Groups are optional for assistants. The purpose of groups is to group assistants by topic.

How to create groups

  1. Create a class that extends “WizardFolderProvider”.
    < use Plenty\Modules\Wizard\Services\WizardFolderProvider; >
  2. Create a protected function folders() and add your functionality to it. This method should return an associative array.

Example:

    [
   'chicken-coup' => [
       'name' => 'Chicken coup',
   ],
   'hen' => [
       'name' => 'Hen',
       'parent' => 'chicken-coup'
   ],
   'egg-1' => [
       'name' => 'Egg #1',
       'parent' => 'hen'
   ],
   'egg-2' => [
       'name' => 'Egg #2',
       'parent' => 'hen'
   ]
];

Explanation:

  • ‘Egg #1’ and ‘Egg #2’ are children to ‘Hen’
  • ‘Hen’ is a child to ‘Chicken coup’

This will create a hierarchy that looks like this
Chicken coup
=> Hen
=> Egg #1
=> Egg #2

Working example:
namespace Plenty\Modules\Wizard\Wizards\CustomDataSourceExample\Folders\CustomDataSourceFolders

How to register groups

  • In a module, in its ModuleServiceProvider
    use Plenty\Modules\Wizard\Contracts\WizardContainerContract;
    use \YourFolderClass;
    In boot() method:
    boot(WizardContainerContract $wizardContainerContract)
    $wizardContainerContract->registerFolders(YourFolderClass::class);
  • In a plugin, in its PluginServiceProvider
    use Plenty\Modules\Wizard\Contracts\WizardContainerContract;
    use \YourFolderClass;
    In boot() method:
    pluginApp(WizardContainerContract::class)->registerFolders(YourFolderClass::class);

How to translate groups

  1. In order for translations to work, the group must have the key “translationNamespace”.
    Example:
    "translationNamespace" => "module_wizard
  2. Assign the translatable properties to keys that are set in your translation files.
    Example:
    "name" => "FileName.folderName",
    "shortDescription" => "FileName.folderDescription",

For more details about how translations work please have a look at the Assistant translations section.

Is this article helpful?

 

Thank you for your Feedback

you can close this field now!