Overview
This feature has been developed over a period of time to enable our users to create and manage forms to drive the personalisation experience in MegaEdit. Under the hood it is a MegaEdit script that, through a series of field tags, lets you dynamically control the form that is displayed to users based on what content is being shown on the canvas.
The configured form can control the following aspects of your product:
- Field (per field control)
- Image field
- Image Upload with image position controls
- Clipart Select
- Mask Select
- Text field
- Single line input with Font, Size, Bold and Italic options
- Multi line input with Font, Size, Bold and Italic options
- Dropdown text select for predefined text
- Alternative background selector which allows the dynamic changing of text color for all text fields.
- Custom field (Barcode)
- Single line input for entering the custom data value (ex: barcode nr). Currently there is no validation.
- Page
- Layout (per page control)
- Background (per page control)
- Canvas
- Size (global control, affects all pages)
Below we talk through the steps in order to set this up and start using it on your products right away.
Please note: All fields should be controlled using the form for the product. We do not advise use of some form fields and some standard fields. This could cause data replacement issues
Setup
Step 1 - Enabling the script
Firstly you need to enable the Dynamic Script 'Dynamic Form Builder', you should find this in your list of scripts against the dynamic products where you assign canvas, stock, clipart assets etc. If it is not showing then please contact the helpdesk to get this enabled on your storefront or platform.
This is done within Catalogue > Product Types > MegaEdit > MegaEdit Products > Edit > Scripts tab.
Step 2 - Setting up the tags and script config to build up your form
Deciding on where to display the form
Form can be displayed on the right side in it's own are or as a tab along with the gallery / cliparts / layouts. By default the script will load on the right side of the canvas in its own dedicated area. (This form works best with the Arone theme in place)
| Script option | Default Value | Possible Values | Usage |
| RenderFormInCustomTab | false | true / false | Setting this to true will generate the form as a custom tab along with the gallery / cliparts / layouts. |
Field Tags:
The script works by tagging fields with specific values, below is a list of the available tags and how they should be used.
To add a field tag, simply add the field to the canvas and then open the Text or Image options dialogue. As an admin you should see a 'Details' tab where you can configure your field restrictions and exact coordinates, scroll down until you see the 'Tags' property under the 'General' header.
NOTE: When adding multiple tags, please do not add any spaces but delimit the different tags using a pipe delimiter '|'
| Field | Tag value | Info | Usage |
| Image | ImageField | This will create an image control, allowing users to upload images and then edit and control them | For all image fields |
| Image | ClipartField | This will create a clipart selection when tag is enabled but on certain fields you may want to restrict the clipart ui, allowing users to select a predefined image from a clipart category. | For all image fields |
| Image | ClipartAlbums_XXXX | Restrict access to the defined Clipart albums. Replace XXXX with the album name. Ex: You have Album1, Album2, Album3 and you want to limit the shown cliparts to Album1 you would add "ClipartAlbum_Album1". If you want to give access to multiple albums the album names are delimited by the ; character. "ClipartAlbum_Album1;Album3" | For image fields with the ClipartField tag. |
| Image | MaskField | This will create a mask select ui, allowing users to select a predefined mask from a mask category. | For all image fields |
| Image | MaskCategories_XXXX | Restrict access to the defined Mask categories. Replace XXXX with the category name. Ex: You have Category1, Category2, Category3 and you want to limit the shown cliparts to Category1 you would add "MaskCategories_Category1". If you want to give access to multiple albums the album names are delimited by the ; character. "MaskCategories_Category1;Category3" | For image fields with the ClipartField tag. |
| Image | NoOptions | Restricts image position options being shown for specific text fields. | When useImageOptions is enabled but on certain fields you want to restrict this |
| Text | TextField | Generates a simple text input, single line only | When you want to collect simple information, like 'Firstname', 'Lastname' etc. |
| Text | TextArea | Generates a multi line text area input that will allow your users to enter in paragraphs of text with carriage returns | When you want to capture larger amounts of text. |
| Text | PredefinedText | This will generate a drop down list of pre-defined content | See Advanced configuration section below |
| Text | BackgroundColor | Generates a colour swatch which lets the user select the background colour of all the fields tagged with TextField, TextArea, PredefinedText. Supports CMYK: #hexcodeSwatchColor,Background C 1-100:Background M 1-100:Background Y 1-100:Background K 1-100,Text C 1-100:Text M 1-100:Text Y -100:Text K 1-100 BackgroundColor|#ffffff,0:0:0:0,0:0:0:100|#000000,0:0:0:100,0:0:0:0 Supports RGB: #hexcodeBackgroundColor,#hexcodeTextColor BackgroundColor|#ffffff,#000000|#000000,#ffffff | Can be used as a full canvas spanning text field that sits in the background to allow a background colour change easily. |
| Text | NoOptions | Restricts advanced text options being shown for specific text fields. | When useTextOptions is enabled but on certain fields you want to restrict this |
Field related script config:
| Script option | Default Value | Possible Values | Usage |
| useImageOptions | true | true / false | Setting this to false will disable image controls for all fields. Please use NoOptions field tag if you need to disable it for only specific fields. |
| useTextOptions | false | true / false | Setting this to true will enable the text options: Font Select / Font Size select / Bold / Italic. Please make sure that your fonts support both bold and italic options. Font size select will not show up if "Fit to box" under advances text options of fields is enabled. Please use NoOptions field tag if you need to disable it for only specific fields. |
| predefinedText | [] | User controlled objects, please see instructions under Advanced configuration further down the article. | Configure predefined text options. Value and label shown in the dropdown. |
Page Tags:
The script works by tagging pages with specific values, below is a list of the available tags and how they should be used.
To add a page tag, simply go to the product menu and select edit page data. Once page tags have been added please save as product default.
NOTE: When adding multiple tags, please do not add any spaces but delimit the different tags using a pipe delimiter '|'
| Tag value | Info | Usage |
| AllowLayoutSelect | This will create a layout select button | Allow layout selection for the specific page |
| LayoutCategories_XXXX | Restrict access to the defined Layout categories. Replace XXXX with the category name. Ex: You have Category1, Category2, Category3 and you want to limit the shown Layouts to Category1 you would add "LayoutCategories_Category1". If you want to give access to multiple albums the album names are delimited by the ; character. "LayoutCategories_Category1;Category3" | |
| AllowBackgroundSelect | This will create a background select button | For all image fields |
| BackgroundCategories_XXXX | Restrict access to the defined Background categories. Replace XXXX with the category name. Ex: You have Category1, Category2, Category3 and you want to limit the shown cliparts to Category1 you would add "BackgroundCategories_Category1". If you want to give access to multiple albums the album names are delimited by the ; character. "BackgroundCategories_Category1;Category3" | |
Page related script config:
| Script option | Default Value | Possible Values | Usage |
| AllowCanvasSizeSelect | false | true / false | Setting this to true will create a dropdown allowing the users to select the canvas. This is a global setting so on change it will update the size of all pages. |
| SizeControlAttribute | false | false / "AttributeName" | Ex: If you have a product attribute called Product size (this is the name, not the friendly name) and you wish to control the canvas via this attribute, you will need to set the config to: SizeControlAttribute : "Product size" In this attribute the values have to be the same as the Canvas Size name (not Canvas name). How to configure canvas size name: Once a canvas is created in admin, access it and under the sizes tab you will have all the availiable sizes. Scroll to the riigh side of the table click edit and change the value in the first column to define the Canvas Size name (named Default by default) |
Step 3 - Controlling your form inputs friendly labels
Fields:
Set the text that is shown as the label for each field in the UI by adding the text to the fields Name input. (Similar to how you input the tags, just as the field name)
Page layout and background:
The labels for these are controlled via language string and are shared across all products that use the script.
dynamicui.layoutselecttitle
dynamicui.backgroundselecttitle
Canvas size:
The label for this is controlled via language string and are shared across all products that use the script.
dynamicui.canvasselecttitle
All language strings relating to the form builder contain: dynamicui
Step 4 - Control the order in which your form elements are presented
If you want to be able to decide on the order in which the field controls appear within the form then you can use the Sequence number property.
(Similar to how you have been inputting the tags and names, just look for the Sequence number setting and add your numbers going low to high here)
At this point you have all the simple steps in place in order to start using this functionality. However, if you want to see and control more about how the script works then read on for more advanced configuration options.
Step 5 - Controlling the content
Using the Form Builder script means that you are controlling the content of fields via the form. Therefore it is important to ensure that certain field properties are set when building your products.
- Do Not Select - This is something we suggest you assign to all your fields and should most definitely be used when you have a fixed layout and do not want the users to be able to move or resize the fields. This way all the control and content is handled by the form.
- Fixed Text - If you want to allow users to be able to move and resize the fields then we recommend ensuring the field property Fixed Text is enabled against the field. This means that they are not able to enter text into the Text Field directly and it is controlled by the form.
Step 6 - Advanced configuration
Every MegaEdit script has a configuration that can be assigned to it, generally if nothing is set against the product then it will use whatever default configuration is pre-defined in the script.
Below we talk through all the possible advanced configuration options you have available and how you can use them.
Field Zooming - Enabling this will make it so that when you are entering information into a form field the editor will zoom into the specific field you are editing.
Default: disabled
zoomEnabled: false
Enable/Disable Image gallery usage - Allow for the gallery to be used and displayed as part of the form for image controls. When disabled it will not be visible and users will have to upload an image from an image source each time.
useGallery: true
Layout handling feature - Will create a new 'Select Layout' button in the top bar that when clicked can provide layout support based on additional configuration (below). When clicked a popup will appear with layout options.
useLayoutQuickSelect: true
Create a layout mapping as an array to control what options are presented to the user, if they should be driven by an attribute selection on the product landing page, and then what layout should be used once ready.
layoutMapping: [{
name: 'Design 1', // Name shown in the UI when selecting
attributeValue: 'Yes', // This needs to be defined only if we map it to a product attribute value
pages: [{
nr: 1, // page number (not index)
layout: 'Design 1 page 1' // Layout name to be applied
}],
thumbnailUrl: '/-383467866/Handler/CSSOverride/GetImage/3/layout_thumb_logo.jpg' // allows to have a css override image shown for the layout selection
}]
To enable the Layout selection popup to appear when the editor loads you can set the below configuration
startOnLoadLayoutQuickSelect: true
Enable multi language support - Create your own language strings to be used on the form field titles (languagestrings start with: me2k.editor.)
Example: me2k.editor.{customprefix}_{fieldname} - me2k.editor.rickysstore_firstname
In this scenario we recommend adding a prefix to ensure it is unique and then the field name should read exactly as 'rickysstore_firstname'.
useLanguageStringsForFieldTitles: true
Field Groups - Allows you to group fields by name to then generate a single form input for all in that group.
fieldGroups: true
Pre-defined Text configuration - As mentioned in the table above you can offer a drop down list form input with pre-defined selections.
You can create multiple mappings with multiple options depending on how you want to use it.
This example below is for a text field with the following tags "TextArea|PredefinedText|Predef1" and using field Name "My Selections".
It will add a dropdown form element in the editor with a label of "My Selections" and will have 3 options (Dropdown option name 1, Dropdown option name 2, Custom)
Dropdown option name 1 will populate the field on the canvas with the contents of an editable content area called 'PredefinedText_Option1'. This is a custom editable content block created in admin.
Dropdown option name 2 will populate the field on the canvas with the text 'This is the simple predefined text for option 2'
Custom will create a free type text box (TextArea or TextField tag needs to be added to the text field) In the form for the user to add their own text'. Only the title Custom works here - any other name will not allow a textarea field.
predefinedText: [{
customTargetTag: 'Predef1', //Define the unique tag for the field you want to use this on
options: [{
title: 'Dropdown option name 1', // Option name, to be shown in the dropdown
isEditableContent: true, // Define if the options source is editable content.
editableContent: 'PredefinedText_Option1', // Define the name of the editable content
value: '' // You can use this if you dont wish to use editable content as you have a non formated string that should be added to the text field.
}, {
title: 'Dropdown option name 2',
isEditableContent: false,
editableContent: '',
value: 'This is the simple predefined text for option 2'
}, {
title: 'Custom', //Use this name only to create a custom freetext area
isEditableContent: false,
editableContent: '',
value: 'Add your own'
}]
}]
Step 7 - Loading data from attributes:
The script has the ability to load the following based on attributes:
Setting canvas size:
Configured via script config: SizeControlAttribute
- Default value: false
- Possible values: false / "AttributeName"
Ex: If you have a product attribute called Product size (this is the name, not the friendly name) and you wish to control the canvas via this attribute, you will need to set the config to: SizeControlAttribute : "Product size"
In this attribute the values have to be the same as the Canvas Size name (not Canvas name).
How to configure canvas size name:
Once a canvas is created in admin, access it and under the sizes tab you will have all the available sizes. Scroll to the right side of the table click edit and change the value in the first column to define the Canvas Size name (named Default by default)
Setting page and field data:
Configured via tag: LoadFromAttribute_AttributeName~PropertyTarget;AttributeName~PropertyTarget
- Tag starts with: LoadFromAttribute_
- AttributeName is the attribute from which the value should be pulled.
- ~ character separates the attribute name from the property target
- PropertyTarget is what defines what the attributes value should be used for
- PropertyTarget can be set for pages as:
- Layout
- Attribute value needs to be LayoutCategoryName:LayoutName and in case this has to apply to a spread the layout needs to be saved as a spread.
- Ex tag: LoadFromAttribute_AttributeName~Layout
- Background
- Attribute value needs to be BackgroundCategoryName:BackgroundName and in case this has to apply to a spread the layout needs to be saved as a spread.
- Ex tag: LoadFromAttribute_My background Attribute~Background
- PropertyTarget can be set for
- all fields as:
- image fields as:
- text fields as:
- You can set multiple aspects for a field or page by using the ; character to delimit them
- ex: LoadFromAttribute_My Clipart Attribute~Clipart;My Mask Attribute~Mask;My Tint Attribute~Tint
Step 7 - Saving data to attributes:
Example of full script config:
{
RenderFormInCustomTab: false,
ShowFieldsAllPages: false,
AllowCanvasSizeSelect: false,
SizeControlAttribute: false,
IgnoreMegaEditLayoutHandling: true,
SaveFieldsToAttributes: false,
fieldGroups: false,
paddingFactor: 0.0,
zoomEnabled: false,
useGallery: true,
useTextOptions: false,
useImageOptions: true,
useLayoutQuickSelect: false,
useLanguageStringsForFieldTitles: false,
layoutCategoryFilter: 'Layout',
startOnLoadLayoutQuickSelect: false,
layoutSelectTitle: 'Select Layout',
syncLayoutWithAttribute: false,
syncLayoutWithAttributename: 'Design',
layoutMapping: [{
name: 'Design 1',
attributeValue: 'Design 1 Option',
pages: [{
nr: 1,
layout: 'Design 1 page 1',
}, {
nr: 2,
layout: 'Design 1 page 2',
}
],
thumbnailUrl: ''
}, {
name: 'Design 2',
attributeValue: 'Design 2 Option',
pages: [{
nr: 1,
layout: 'Design 2 page 1',
}, {
nr: 2,
layout: 'Design 2 page 2',
}
],
thumbnailUrl: ''
}
],
predefinedText: [{
customTargetTag: 'Predef1',
options: [{
title: 'Dropdown option name 1',
isEditableContent: true,
editableContent: 'PredefinedText_Option1',
value: ''
}, {
title: 'Dropdown option name 2',
isEditableContent: true,
editableContent: '',
value: 'This is the simple predefined text for option 2'
}, {
title: 'Dropdown option name 3',
isEditableContent: true,
editableContent: 'PredefinedText_Option3',
value: ''
}, {
title: 'Dropdown option name 4',
isEditableContent: true,
editableContent: 'PredefinedText_Option4',
value: ''
}
]
}
]
}
Script default config:
{
textAreaTag: "TextArea",
textFieldTag: "TextField",
customAreaTag: "CustomArea",
customFieldTag: "CustomField",
imageFieldTag: "ImageField",
clipartFieldTag: "ClipartField",
maskFieldTag: "MaskField",
predefTextTag: "PredefinedText",
backgroundColorTag: "BackgroundColor",
RenderFormInCustomTab: false,
ShowFieldsAllPages: false,
AllowCanvasSizeSelect: false,
SizeControlAttribute: false,
IgnoreMegaEditLayoutHandling: true,
SaveFieldsToAttributes: false,
fieldGroups: false,
paddingFactor: 0.0,
zoomEnabled: false,
useGallery: true,
useTextOptions: false,
useImageOptions: true,
useLayoutQuickSelect: false,
useLanguageStringsForFieldTitles: false,
layoutCategoryFilter: 'Layout',
startOnLoadLayoutQuickSelect: false,
layoutSelectTitle: 'Select Layout',
layoutMapping: [],
syncLayoutWithAttribute: false,
syncLayoutWithAttributename: 'Design',
predefinedText: []
}