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 wizard 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 wizard 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 wizard
  • key:string required and unique
  • iconPath:string optional; an icon that will be displayed alongside with the title of the wizard
  • shortDescription:string|key Describes the purpose of the wizard.
  • 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.
  • 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 a wizard can be run multiple times
  • steps:key => Step required and unique for the wizard

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 folder 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

  • 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;

Is this article helpful?

 

Thank you for your Feedback

you can close this field now!