`. Now it is wrapped with no type, as the
host's plain content: a block to move and delete, edited in the source, and
a click with a text editor loaded makes it a text, through
`before-convert` and `after-convert`. Markup 5.x saved, with its content
areas typed, loads as texts, as before. What to do: nothing, unless you
read the saved markup expecting every content area to carry a type.
* __New columns are empty.__ A column the add column tool, a row button,
`createRow` or `createColumn` makes - and a new container's or pane's
region - has no content area in it. Add a text with the toolbar's *Text*
button, clicked or dragged into the column, or `createText`. `createColumn(size, {
content })` still holds its content: as a text of the first editor
offered, or as plain content with none.
* __`content_types` defaults to every text editor loaded__, in the order the
page loaded them, where it was `['tinymce']`. A page that loads one editor
needs no `content_types`; one that loads several and wants one names it.
* __`text_tools`, `text_classes` and `createText` are the text editors'.__
They work as before with any of the shipped editors loaded; with none,
`createText` warns and returns null.
* __An integration of your own under `$.fn.gridEditor.RTEs`__ is ignored,
with a warning, and so is one under `$.fn.gridEditor.texts` on a page
that loads none of the shipped editors: `texts` is their own registry. An
editor of your own is a feature plugin that declares its type with
`textTypes`; [docs/plugins.md](docs/plugins.md#text) has the contract, and
[example/text-editors.html](example/text-editors.html?editor=simpletext) has one in full.
* __No *Add text* tool in the columns' drawers.__ 5.3 put one there; a text
is added with the toolbar's *Text* button, dragged into the column, or
`createText`. The `tool.add_text` and `tool.add_text_type` locale keys are
gone with it.
* __The source button can be left out__ with `edit_source: false`. A page
that hid `.gm-edit-mode` with css of its own can drop that css.
* __A code editor of your own over the source textarea__ - CodeMirror, Ace,
started on `.ge-html-output` when the source button is clicked - can be the
codemirror plugin instead, which edits the source view in CodeMirror 5, or a
feature plugin with `onSourceOpen(textarea)` and `onSourceClose(textarea)`:
the editor goes over the textarea on open, and puts its value back in it on
close, which is what the canvas is made of. See
[docs/plugins.md](docs/plugins.md). The codemirror-inline plugin edits one
block's html at a time, in place, from a tool in its drawer.
* __`destroy` with the source view open__ leaves the canvas with the html
being written in it. It left the canvas hidden, holding the html it had
before the source opened.
* __A page that names its plugins__ in the `plugins` setting names
`codemirror` and `codemirror-inline` there too, as any feature plugin, to use
them.
Upgrading from grid-editor `4.*` to `5.*`
=========================================
One change makes it a major: **the all view writes one class.** Everything
else in 5.0 is new, and a page that uses none of it edits as it did.
* __A size or an offset set in the all view is the class with no breakpoint.__
Up to 4.x the all view wrote all six breakpoints; 5.0 writes the base class
and takes the breakpoints' own sizes or offsets off, as the utilities have
done since 4.1. The markup means the same on the page and is shorter:
```html
```
Reading has not changed: markup with the six classes written out is read as
before, and the first change made in the all view simplifies it. What to do:
nothing, unless you compare or post-process the html the editor saves and
expect six classes. A breakpoint view still writes its own breakpoint alone.
* __Resize and indent payloads carry `cleared` in the all view__, with what the
write took off each breakpoint: `[{ breakpoint: 'lg', value: 6 }]`. A
listener that checks the payload's keys exactly will see one more.
* __A resize's `from` and `to` can be `'equal'` or `'auto'`__ - Bootstrap's
`col` and `col-auto` - and `from` is `null` for a column its row sizes with
`row-cols`. `source` can be `panel`, for a width chosen in a column's
settings panel. A listener that does arithmetic on them should check
`typeof size === 'number'` first. These only happen on columns that use the
new sizes.
* __`valid_col_sizes` has two more values by default__, `'equal'` and `'auto'`,
which the add column picker and the width field offer. A host that sets its
own list keeps it; one that wants the 4.x picker sets
`valid_col_sizes: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]`.
* __Every column's settings panel has a Width field, and every row's a Columns
per row field__, in the Responsive section, which is folded until the user
opens it. `row_cols: false` takes the row field away.
* __Columns with `col`, `col-auto`, or in a row with `row-cols-*` are no longer
given a `col-12`.__ In 4.x a column with only `col` was not a column at all,
and one with `col-auto` got a `col-12` that overrode it; both now edit as
Bootstrap renders them. A page that relied on the `col-12` gets the layout
its classes describe instead.
New and opt-in, so nothing to do: the `sections` plugin for Bootstrap's
containers, and the feature hooks it is built on (`blocks`, `regions`,
`accepts`, `toolbar`). See the [CHANGELOG](CHANGELOG.md) for the full list.
Upgrading from grid-editor `3.*` to `4.*`
=========================================
One change, and it is worth the major: jQuery UI is gone. The editor is 51 kB
lighter on the page and works from a touchscreen, which it never did. Four
things to do:
* __A plugin's `onSortable` takes a function, not an options object.__ It used
to receive the editor's shared jQuery UI options and call `.sortable()`
itself; it now receives `sortable(lists, { draggable, group })` and describes
the list instead. See [docs/plugins.md](docs/plugins.md). Nothing else in the
plugin handle changed.
```javascript
// 3.x
onSortable: function(shared) {
ge.canvas.find('.ge-content').sortable($.extend({
items: '> .ge-element',
connectWith: '.ge-canvas .ge-content',
}, shared, ge.settings.sortable_options));
}
// 4.x
onSortable: function(sortable) {
sortable(ge.canvas.find('.ge-content'), {
draggable: '> .ge-element',
group: 'element',
});
}
```
* __`sortable_options` and `resizable_options` are gone.__ They existed to hand
you the drag library's own options, and 4.0 stops promising there is one: the
group names, the handle, the filter and the callbacks are the editor's, and
overwriting them breaks the canvas rather than tuning it. What they were used
for is now `drag` — `delay`, `touch_delay`, `threshold`, `animation`,
`scroll` — and the `resize` block you already have. Passing either warns once
and names the replacement.
* __jQuery UI is not a dependency.__ Drop its `
```
Classes you may have styled:
| 3.x | 4.0 |
| --- | --- |
| `.ui-sortable-helper` | `.ge-drag-helper` |
| `.ui-sortable-placeholder` | `.ge-drag-placeholder` |
| `.ui-resizable-handle` | `.ge-resize-handle` |
| `.ui-resizable-e`, `.ui-resizable-w` | `.ge-resize-e`, `.ge-resize-w` |
| `.ui-resizable-resizing` | `.ge-resizing` |
| `.ui-draggable` on a toolbar button | `.ge-palette-button` |
* __A whole container can be dragged now.__ Its move tool was a handle for a
list that did not accept containers, so in 3.x dragging one did nothing. It
moves like a row does, and fires the same `before-move`/`after-move` with the
container's kind.
* __Two editors on one page no longer drag into each other.__ Lists were
connected by selector — `.ge-canvas .row` matches every canvas on the page —
so a column could be dragged from one editor into another, carrying the first
editor's furniture and firing its events in the wrong place. Lists are now
connected per instance. If you were relying on that, you were relying on a
bug.
Upgrading from grid-editor `2.*` to `3.*`
=========================================
Both are for bootstrap 5, and most of 3.x is additive: the settings you pass
today keep working, `getHtml` still returns your markup, and the rich text
editor integrations are unchanged. Four things do change.
* __Layout modes went from three to seven.__ `changeView` takes a breakpoint
key now — `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'xxl'` or `'all'` — and
`getView` gives one back. The 2.x numeric indexes still work (`0` desktop,
`1` tablet, `2` phone) and log a deprecation warning once. The dropdown has
seven entries; pass `layout_modes: ['all', 'lg', 'sm', 'xs']` for something
closer to the old feel.
* __The editor starts in the `all` view__, where a size or indent change is
written to every breakpoint at once. Pass `default_view: 'lg'` for the old
behaviour of editing one tier at a time.
* __The canvas layout classes are named after the breakpoints.__
`ge-layout-desktop`, `ge-layout-tablet` and `ge-layout-phone` are now
`ge-layout-lg`, `ge-layout-sm` and `ge-layout-xs`, with `ge-layout-md`,
`-xl`, `-xxl` and `-all` alongside them. If you styled against those class
names, rename them.
* __Columns are no longer seeded with a class per breakpoint.__ 2.x wrote
`col-lg-*`, `col-sm-*` and `col-*` onto every column whether or not you
asked; 3.x leaves a column that carries any size class exactly as authored,
and gives a column with none a single `col-12`. Your existing markup is
unaffected — it already has those classes — but new columns are leaner, and
a column sized only for `lg` now renders as bootstrap renders it below `lg`.
* __Tabs, accordions, popups and the element level controls are plugin
files.__ They are not in the main bundle: load
`dist/plugins/grideditor.tabs.js` and its neighbours beside the editor for
the ones your pages use. Nothing to change for a 2.x page, which had none of
them; a page that wants them loads two files instead of one.
* __`row_classes` and `col_classes` are empty by default.__ 2.x shipped a
single `Example class` toggle in every settings panel; if you were relying on
it, pass the classes you actually want. The panel now has a css class field
of its own, so a host needs the preset buttons only for the classes it wants
one click away.
Deprecated, and still working:
* `remove` is now `destroy`. `remove` remains as an alias and warns once per
instance.
New, and worth knowing about before you write glue code for it:
* `callbacks` and the `grideditor:*` events, so your application is told about
every add, delete, move, resize and indent, and can cancel any of them. This
replaces reaching into the editor's DOM to find out what happened. See
[docs/events.md](/docs/events.md).
* `confirm_delete`, which replaces the hardcoded "Delete row?" confirm, and
`locale`/`locale_strings`/`setLocale` for the interface language.
* Column offsets, drag resize, element level controls, and tabs, accordions
and popups. All off unless you use them; the containers and elements are
detected from `data-ge-container` and `data-ge-element`, which your existing
markup does not have.
Upgrading from grid-editor `1.*` to `2.*`
=========================================
Grid-editor `1.*` is for bootstrap __4__, `2.*` for bootstrap __5__.
The grid classes grid-editor generates (`col-lg-*`, `col-sm-*`, `col-*`) are
valid in both bootstrap 4 and 5, so __no changes to your generated HTML are
needed__. What changes is what you load on the page:
* Load __bootstrap 5__ instead of bootstrap 4. The layout mode dropdown now
uses `data-bs-toggle` instead of `data-toggle`, which only bootstrap 5
understands.
* Load [bootstrap icons](https://icons.getbootstrap.com/) instead of font
awesome. Every built-in tool icon moved from a `fa fa-*` class to its
`bi bi-*` equivalent.
* If you pass custom `row_tools` or `col_tools`, their default `iconClass` is
now `bi bi-wrench`. Any `iconClass` you pass explicitly as `fa fa-*` must be
changed to a bootstrap icons class.
* If you use `content_types: ['tinymce']`, load __tinyMCE 6__ and stop loading
the `jquery.tinymce.js` integration plugin. TinyMCE dropped that plugin after
5.x, so the integration now calls `tinymce.init()` directly. A
`tinymce.config.oninit` callback keeps working, and `init_instance_callback`
is honoured as well.
Upgrading from grid-editor `0.*` to `1.*`
=========================================
Grid-editor `0.*` is for bootstrap __3__, `1.*` for bootstrap __4__.
Since the breakpoints for the gridsystem have changed from 3 to 4, all the HTML that was generated using grid-editor `0.*` must be adjusted.
Change all the classes in the HTML from `col-md` to `col-lg`. No other changes to the HTML are needed.