The following documentation provides all necessary information to set up your own assistant and will guide you through its creation step by step.
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.
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.
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.
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
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 of the wizard model which are translated:
In addition to that, the following properties of the DynamicFormElements need to be translated:
Structure of a key: "FILENAME.KEY", e.g Assistant.text1
NAMESPACE is mandatory.
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
The overall structure contains basic information about the assistant, options and form elements.
Basic information and classes
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.
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
]
]
],
It is now possible to show a maximum of 3 options on each assistant’s card. The order of the options in the table determines which ones will actually be shown. Thus, the first 3 options from the table are displayed on the respective card and will be listed below each other.
All other options can be found in the table view.
...of any form element
key:string => TerraFormFieldInterface {
This form element has no special options.
Example:
"userClass" => [
"type" => "select",
"options" => [
"name" => "User classes",
"listBoxValues" => [
[
"caption" => "Admin",
"value" => 1
],
[
"caption" => "Variable user",
"value" => 2
],
[
"caption" => "Blog",
"value" => 3
]
]
]
]
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.
This form element has no special 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
]
],
]
]
This form element has no special options.
It is possible to group form fields using one of the following form field types. However, this transforms the value of your form field to an object that contains the values of all children form fields.
When using a vertical group, all children form fields are positioned one below the other.
When using a horizontal group, all children form fields are positioned next to each other.
"collapseBox" => [
"type" => "vertical",
"options" => [
"name" => "Widget.collapseBoxLabel"
],
"children" => [
"headline" => [
"type" => "text",
"required" => true,
"defaultValue" => "",
"options" => [
"name" => "Widget.collapseBoxHeadlineLabel"
]
],
"text" => [
"type" => "codeEditor",
"required" => true,
"defaultValue" => "",
"options" => [
"name" => "Widget.collapseBoxTextareaLabel"
]
]
]
],
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.
We distinguish between the following types of dependencies:
Working example:
namespace Plenty\Modules\Wizard\Wizards\TestWizard\DynamicLoaders\TestDynamicLoader;
In your assistant's structure, add the following:
In a module
In a plugin
In your assistant's structure, add the following to the corresponding form field.
If you want to overwrite a value you can use the following attribute in your dependency:
Working example:
namespace Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard
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.
Working example:
namespace Plenty\Modules\Wizard\Wizards\TestWizard\Modifiers\TestWizardStepDataModifier;
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.
Working example:
namespace Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard;
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.
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:
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
Working example:
Plenty\Modules\Wizard\Wizards\TestWizard\Validators\TestWizardDataValidator used in Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard’s first step
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.
Working example:
namespace
Plenty\Modules\Wizard\Wizards\TestWizard\SettingsHandlers\TestWizardSettingsHandler;
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.
Working example:
namespace Plenty\Modules\Wizard\Wizards\TestWizard\TestWizard;
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.
In your assistant's structure use the following:
In a plugin
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
Before you start developing your data source, there are some features already developed to ease your work.
The data source will already have:
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.
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.
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.
Groups are optional for assistants. The purpose of groups is to group assistants by topic.
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:
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
For more details on how translations work please have a look at the Assistant translations section.