Grid Editors

Gives editors a grid layout editor which allows them to insert different types of content in a predefined layout.

What are grid layouts?

To understand how the grid layout editor works, we must first understand the structure of the grid layouts.

Grid layouts consists of two main areas that need to be configured, grid layout area and grid rows.

Grid Layout

The layout area is where the overall page layout is defined. Layout areas are divided in to layout sections e.g. a sidebar section and content section. The size of the layout sections is defined in columns. For a full-width content area use max number of columns (12 for Bootstrap 3). Each layout section contains one or more rows.

Grid Rows

Grid rows is where the actual content goes. Each row is divided into cells that contain the property editors. The size of the cells is defined in columns. Unlike the layouts sections it is possible to add more cells than the max number of columns - they will stack as they should in a grid system.

Configuring the Grid Layout data type

A grid layout contains multiple configuration options to allow developers to tailor the grid to a very specific site design. Configuring the layout can be divided into 2 overall parts:

Layouts

A layout is the general grid "container", it contains one or more sections which content editors can use to insert preconfigured rows. There are 2 main usage scenarios of layouts:

  1. A single column layout which to the content editor will act like a full page canvas to insert elements on
  2. A multiple column layout with a main content body, and one or more sidebar columns to insert lists or other sidebar widgets on.

You can however configure as many layouts and layout sections as you wish, each section in the layout must be given a width in columns, so editors gets an accurate preview of their layout.

Row configurations

A row in the grid editor contains one or more cells, which divide the row into areas where editors can enter content. So a row is merely a container of areas to insert content into. When you add a new row, you are asked to give it a name, then define cells inside the row by clicking the "+" icon. Each cell has a default width set to 4, but by clicking the inserted cell you can control its width.

It is possible to setup configurable attributes(class, rel, href) and inline styling on rows.

You can add as many cells as you like. If they overflow the total width of the row, they will be arranged after each other horizontally as you'd expect in a grid system.

Each cell can by default contain any type of editor such as textstring editors, imagespicker, embedded media or Externable macros. To override this behavior, uncheck the allow all editors option and you can specify which editors will be available for the row.

Settings and styling

A grid layout can also expose custom settings - such as data-attributes or styling options - on each cell or row. This allows editors to use a friendly UI to add configuration values to grid elements. When custom settings and styles are applied, they will by default be included in the grid html as either html attributes or inline styles.

Grid layouts

These settings and styles must be configured by developers when setting up the grid layout data type.

Configuring a custom setting or style

To add a setting, click the edit settings link. This will expand a dialog showing you the raw configuration data. This data is in the JSON format and will only save if it's valid JSON.

The settings data could look like this, with an object for each setting:

[
  {
    "label": "Class",
    "description": "Set a css class",
    "key": "class",
    "view": "textstring",
    "modifier": "col-sm-{0}",
    "applyTo": "row|cell"
  }
]

The different values are:

  • label : Field name displayed in the content editor UI
  • description : Descriptive text displayed in the content editor UI to guide the user
  • key : The key the entered setting value will be stored under.
  • view : The editor used to enter a setting value with.
  • prevalues : For views that need predefined values, e.g. the radiobuttonlist view.
  • modifier (optional) : A string formatter to modify the output of the editor to prepend or append extra values.
  • applyTo (optional) : States whether the setting can be used on a cell or a row. If either not present or empty, the setting will be shown both on Rows and Cells.

label and description are straight-forward.

key defines the alias the configuration is stored under and by default the alias of the attribute will also be the attribute on the rendered html element. In the example above any value entered in this settings editor will be rendered in the grid html as:

<div **class**="VALUE-ENTERED"></div>

By changing the key of the setting you can modify the <div> element's attributes like class, title, id or custom data-* attributes.

view the view defines the editor used to enter a value. By default Externable comes with a collection of prevalue editors:

  • textstring
  • textarea
  • radiobuttonlist
  • mediapicker
  • imagepicker
  • boolean
  • treepicker
  • treesource
  • number
  • multivalues

Alternatively you can also pass in a path to a custom view like "/App_Plugins/grid/editors/view.html"

prevalues is for views that need predefined values, e.g. the radiobuttonlist view. Prevalues are defined as strings in an array:

"prevalues": [
    "value_1",
    "value_2",
    "value_3"
]

and will translate in to three different options where each string will become a radiobutton. The strings represent the value of the options.

Prevalues can also be defined as an object of label/value allowing to have a displayed label instead of showing the actual underlying value. You can even mix and match these and use both label/value prevalues and string prevalues in the same configuration:

"prevalues": [
    {
        "label": "Value one",
        "value": "value_1"
    },
    {
        "label": "Value two",
        "value": "value_2"
    },
    "value_3"
]

modifier is a basic way to prepend, append or wrap the value from the editor in a string. This is especially useful when working with custom styles which often requires additional values to function. For instance if you want to set a background image you can get an image path from the image picker view. But in order for it to work with css it has to be wrapped in url(). In that case you set the modifier to url('{0}') which means that {0} is replaced with the editor value.

applyTo defines what this setting can be applied to. It should be either row or cell as a string.

JSON object can also be used if you need a more specific configuration. A JSON configuration could look like this:

"applyTo": {
    "row": "Headline,Article",
    "cell": "4,8,6"
}

This would ensure the setting can only be used on rows named Article or Headline, or on cells sized: 4, 8 or 6. If it should only apply to cells you can remove the row property. If it should apply to all rows you can specify it by having the row property with null or an empty string as value.

Sample settings

There are many ways to combine these, here are some samples:

Set a background image style

{
    "label": "Background image",
    "description": "Choose an image",
    "key": "background-image",
    "view": "imagepicker",
    "modifier": "url('{0}')"
}

Set a title setting

{
    "label": "Title",
    "description": "Set a title on this element",
    "key": "title",
    "view": "textstring"
}

Set a data-custom setting

{
    "label": "Custom data",
    "description": "Set the custom data on this element",
    "key": "data-custom",
    "view": "radiobuttonlist",
    "prevalues": [
        "value_1",
        "value_2",
        "value_3"
    ]
}

Multiple settings and styles

You can add multiple settings and styles configurations on a data type. This is done by creating a new setting or style object. Remember to separate the objects with a comma.

Adding multiple settings

[
    {
        "label": "Class",
        "description": "Set a class on this element",
        "key": "class",
        "view": "textstring"
    },
    {
        "label": "Title",
        "description": "Set a title on this element",
        "key": "title",
        "view": "textstring"
    },
    {
        "label": "Custom data",
        "description": "Set the custom data on this element",
        "key": "data-custom",
        "view": "textstring"
    }
]

Full-width settings and styles

It is possible to use settings and styles to add full-width background-images, background-colors and so forth. Make sure the surrounding section is full-width (12 columns by default) and the rows inside it will automatically become full-width.

Render grid in template

Using @Html.GetGridHtml

To render a property based on the grid inside a template you should use the HtmlHelper extension:

@Html.GetGridHtml(Model, "propertyAlias")

This will render the grid item with alias "propertyAlias" from the current page models' content.

This will by default use the view /views/partials/grid/bootstrap3.cshtml you can also use other provided grid template rendering files - for example the built-in bootstrap2.cshtml view by overloading this helper:

@Html.GetGridHtml(Model, "propertyAlias", "bootstrap2")

You can create your own custom grid rendering files e.g for your favourite or custom grid framework implementation. Tip: copy one of the existing files as a starting point. By convention, if you create your "mycustomrenderer.cshtml" file in /views/partials/grid you can render the grid property like so:

@Html.GetGridHtml(Model, "propertyAlias", "mycustomrenderer")

or alternatively you can provide the path to where the file resides:

@Html.GetGridHtml(Model, "propertyAlias", "/views/mycustomrenderer.cshtml")
← Property EditorsMacros →