Create widget

When setting up your Geins CMS, you have the option to use the pre-configured widgets that come with the CMS, or to create your own custom widgets that corresponds to your wireframes and design. This page will explain everything you need to know about the Create widget function.

Getting started

Geins Merchant Center offers a way to create custom widget editors. You can do so by selecting Create widget in the top left corner when adding a widget through the Select widget panel.

Start by writing or pasting the JSON structure you want the CMS to return through the API in the JSON editor tab. Your JSON will immediately be converted into a user-friendly editor in the Editor tab, with fields and options that are easy to use when later managing the content of your widget.

tip

If you are starting out with mock data in your wireframe project, it is a good idea to paste that JSON here to instantly get an editor that matches your JSON structure.

Working with templates

After getting started with creating your own custom widget editors, you will probably notice that you are creating a lot of similar editors. To make it easier to create these similar editors, you can save them as templates.

You will find all your saved templates in the Templates tab. From here you can edit, remove and change the order of your templates.

Creating a template

Suppose you want to create a widget editor where you can add a title and then a list of cards, each with some properties. Your JSON could look something like this:

{
  "title": "",
  "cards": [
    {
      "image": "",
      "buttonText": "",
      "buttonColor": "",
      "product": []
    }
  ]
}

To create a template from this JSON:

Enter this in the JSON editor tab.
Click the Save as template button.
Fill in the options for your template:
- Template name - The name of your template. This will be used in the sidebar of the Select widget panel, if you choose to show your template as a widget.
- Template icon - This field is optional. You can add a custom icon for your template if you want to. This field expects a Materials Icons code point. You can find a list of all the available icons and their code points here: Material Icons.
- Show as widget - If you turn this on, your template will appear as a widget in the sidebar of the Select widget panel, above the "Create your own" widget.
Click Save template, then reload the page to see your template in the Templates tab and sidebar of the Select widget panel (if applicable).

Editing a saved template

Select the template in the Templates tab.
Make changes in the JSON editor tab and click Save as template
You will now see the same options as when you created the template. If you change the name of the template in this stage, the template will be saved as a new template, and the old one will still exist.
Click Save template to save your changes.

Removing a template

Navigate to the Templates tab and hover over the template you wish to remove. Click the delete icon (‘x’) that appears and confirm your decision to remove the template.

Changing the order of templates

In the Templates tab, hover over the "handle" (two horizontal lines) of the template you want to move. Click and hold, then drag the template to a new position. Release to save the new order automatically. Reload the page to view the updated order in the sidebar of the Select widget panel.

Using a template

To use a template, select it from sidebar of the Select widget panel or select Create widget and choose your template from the Templates tab. The editor for your template will then appear in the Editor tab.

Settings

In the Settings tab, you will find another JSON code editor with global input settings for all your templates. Use these settings to override default behavior or to specify custom input types and input rules for your editor.

The settings for input types is an array called inputTypes and the settings for rules is an array called inputRules. In this section we will go through how to use them.

Default behavior

Here follows a specification on when some input types will be used by default.

Input type	When it will be used by default
`text`	If the value is a `String`
`checkbox`	If the value is a `Boolean`
`number`	If the value is a `Number`
`textarea`	If the value is a `String` that are longer than 100 characters
`image`	If your key includes 'image', for example `headerImage` or just `image`
`color`	If your key includes 'color', for example `buttonColor` or just `color`
`product`	If your key includes 'product', for example `products` or `product`

Input types

If you want to override default behavior or specify the input types to be used in your templates, you can do so by adding an array called inputTypes to your settings JSON. Here is an example of how it could look:

Settings
{
  "inputTypes": [
    {
      "key": "component",
      "type": "hidden"
    },
    {
      "keyIncludes": "img",
      "type": "image"
    },
    {
      "key": "textAlign",
      "type": "radio",
      "options": [
        {
          "label": "Left",
          "value": "left"
        },
        {
          "label": "Center",
          "value": "center"
        },
        {
          "label": "Right",
          "value": "right"
        }
      ]
    },
    {
      "key": "darkMode",
      "type": "switch"
    }
  ]
}

`key / keyIncludes`

Every object in the array has either a key or a keyIncludes property. The key property is used to specify a specific key in your JSON. The keyIncludes property is used to specify a string that should be included in the key. If you use keyIncludes, the input type will be applied to all keys that includes the specified string. For example, if you use keyIncludes with the string "img", the input type will be applied to all keys that includes the string "img", like "img", "mobileImg", "headerImg" etc.

`type`

Every object also has a type property. This is used to specify what input type you want to use. You can find all available input types in the table below.

`options`

Some objects also requires an options property. This is used to specify the options for the input type. For example, if you use the radio input type, you need to specify the options for the radio buttons. The options property is an array of objects with a label and a value property. The label property is used to specify the label for the option, and the value property is used to specify the value that will be saved to your JSON when the option is selected.

tip

Use the keyIncludes property if you want to use the same input type for multiple keys. For eg. if you want to use the switch input type for all keys that includes "active", you can use keyIncludes with the string "active" instead of specifying every key individually.

Available input types

Input type	Description	Output value	Options required
`text`	A simple text input	`String`	-
`checkbox`	A checkbox input	`Boolean`	-
`number`	A number input	`Number`	-
`textarea`	A textarea input	`String`	-
`select`	A select input	`String`	Yes
`radio`	A radio button input	`String`	Yes
`hidden`	A hidden input	`String`	-
`date`	A date picker input	`String`	-
`time`	A time picker input	`String`	-
`color`	A color picker input to select a hex color	`String`	-
`image`	An image uploader	`String`	-
`product`	A product search to select one or more products	`[Object]`	-
`multi`	A group of checkboxes	`[String]`	Yes
`switch`	An on/off switcher	`Boolean`	-

Input rules

If you want to add display rules for your inputs, you can do so by adding an array called inputRules to your settings JSON. Here follows an example of how you could use it.

Settings
{
  "inputRules": [
    {
      "key": "cards",
      "rules": {
        "itemsPerRow": 2,
        "staticItemsQuantity": true,
        "customLabel": "Product display cards",
        "description": "Add cards to show in grid"
      }
    },
    {
      "key": "title",
      "rules": {
        "hideLabel": true,
        "placeholder": "Enter the title of your list"
      } 
    },
    {
      "key": "product",
      "rules": {
        "productQuantityLimit": 1,
        "description": "Select the product to display"
      }
    },
    {
      "key": "textAlign",
      "rules": {
        "defaultValue": "center",
      }
    },
    {
      "key": "darkMode",
      "customLabels": {
        "true": "Active",
        "false": "Inactive"
      }
    }
  ]
}

The inputRules array contains objects with a key property and a rules property. The key property is used to specify a specific key in your JSON. Like with inputRules, you can use keyIncludes instead of key if you want to. The rules property is used to specify the rules for the input. You can find all available rules in the table below.

Available input rules

Rule	Description	Works with	Default value	Type
`customLabel`	Specify a custom label for the input	All input types	For example `textAlign` becomes Text align	`String`
`hideLabel`	Hide the label	All input types	`false`	`Boolean`
`description`	Add a description for the input. For `Array` and `Object` values this will be shown under the label, otherwise it will be shown under the input.	All input types	-	`String`
`placeholder`	Add a placeholder for the input	Input types `text`, `number`, `textarea` & `select`	-	`String`
`defaultValue`	Specify a default value for the input. Set this for the editor to be resetted correctly when user clicks Clear all data in the editor.	All input types	`String`: `''` `Number`: `0` `Boolean`: `false`	Any
`itemsPerRow`	Specify how many items should be displayed per row in the editor. Recommended to not exceed 4 in a row for UX reasons.	`Array` values	3	`Number`
`staticItemsQuantity`	Specify if the quantity of items should be static or not. If set to `true`, the user will not be able to add or remove items to the array through the editor.	`Array` values	`false`	`Boolean`
`productQuantityLimit`	Specify the maximum quantity of products that can be added	Input type `product`	No limit	`Number`
`customLabels`	Specify custom labels for the `switch` input type. The `customLabels` property is an object with two properties, `true` and `false`.	Input type `switch`	`true`: `'On'` `false`: `'Off'`	`Object`

tip

Use the itemsPerRow and staticItemsQuantity rules to make sure that the editor for your array values looks good and is easy to use for admins.

Create widget

Getting started​

Working with templates​

Creating a template​

Editing a saved template​

Removing a template​

Changing the order of templates​

Using a template​

Settings​

Default behavior​

Input types​

key / keyIncludes​

type​

options​

Available input types​

Input rules​

Available input rules​