@themarioga/grid-editor 6.0.0-beta.3 → 6.0.0-beta.4

package/docs/plugins.md

@@ -14,15 +14,18 @@ the one to read first if you are about to write your own.
 <script src="dist/plugins/grideditor.elements.min.js"></script>
 ```
 
-There are four kinds. A **container plugin** builds a type of container — it
+There are three kinds. A **container plugin** builds a type of container — it
 registers under `$.fn.gridEditor.containers`, and the toolbar offers a button
 for it. A **utility plugin** declares families of Bootstrap's responsive
 utility classes — `$.fn.gridEditor.utilities` — and the editor edits them per
-breakpoint. A **text editor plugin** edits content areas with a rich text
-editor — `$.fn.gridEditor.texts`, one per editor: tinyMCE, CKEditor,
-summernote. A **feature plugin** is anything else the editor can do —
+breakpoint. A **feature plugin** is anything else the editor can do —
 `$.fn.gridEditor.features`, hooks into the canvas, and may contribute methods.
-All four are factories called once per editor with the same handle.
+All three are factories called once per editor with the same handle.
+
+Text is a feature plugin too. The core knows the grid and the host's *plain
+content* - the markup it found that is not the grid's - and nothing of text:
+the text editors, tinyMCE, CKEditor and summernote, are plugins, and so is an
+editor a host writes itself. See [Text](#text).
 
 The `plugins` setting names which of the loaded ones to use:
 
@@ -60,6 +63,7 @@ $.fn.gridEditor.containers.carousel = function(ge) {
 
     return {
         labelKey: 'container.add_carousel',   // the toolbar button's label
+        iconClass: 'bi bi-images',            // optional: the button shows it in place of the label
         addPaneKey: 'container.add_slide',    // the drawer's add pane tool
         paneKind: 'slide',                    // the kind its panes report
 
@@ -77,6 +81,9 @@ $.fn.gridEditor.containers.carousel = function(ge) {
 })(jQuery);
 ```
 
+- **`iconClass`**, when given, is the toolbar button's face: the icon alone,
+  with the label as its title. Without one the button shows a plus and the
+  label.
 - **`create(options)`** returns a detached container. It must carry
   `data-ge-container="<type>"`: that attribute, and never a class, is how the
   editor recognises one.
@@ -129,6 +136,9 @@ not change without a major version.
 | `ge.rowFromLayout(layout)` | A detached row from a layout: `[8, 4]`, `['auto', 'equal']` or `{ row_cols, columns }` |
 | `ge.drawerOf(node)` | A node's drawer: its first child, or for a content area the one beside it in its text block |
 | `ge.textReady(block)` | A text editor has rewritten a content area: whatever the editor and its plugins put in there goes back in |
+| `ge.attachPicker(tool, open)` | Hold a tool, or rest the pointer on it, and `open` is called: how a tool offers a choice |
+| `ge.openPicker(anchor, choices, className?)` | The choice itself, as a strip under `anchor`: one button per `{ label, title, attributes, choose }` |
+| `ge.closePicker()` | Close it; true when one was open, which is also a click's answer |
 | `ge.nodeHtml(node)` | One node's markup as `getHtml` would give it. The canvas leaves editing to read it and comes back, as it does for `getHtml` |
 | `ge.toolbarItems(name)` | The toolbar buttons the feature plugin `name` declared, for showing and hiding them |
 | `ge.bareStyle(node, family, property)` | A css property's value on the node with none of the family's classes: what a preview shows when no class applies and that is not a constant |
@@ -150,7 +160,10 @@ $.fn.gridEditor.features.elements = function(ge) {
         kindOf: function(node) { … },    // what an event calls this node
         onInit: function() { … },        // every init: put the furniture in
         onDeinit: function() { … },      // every deinit: take it out again
+        onBeforeDeinit: function() { … },  // every deinit, before the drawers come off: close what you opened
         onContentReady: function(area) { … },  // a rich text editor just took over, or rewrote a text
+        textTypes: function() { … },      // the text types this plugin edits, see "Text"
+
         cuts: '[data-my-block]',          // what cuts a text: a block of the column, never part of a text
         onSortable: function(sortable) { … },  // declare your own sortable lists
         blocks: '.ge-section',            // more blocks the canvas and the columns move
@@ -211,10 +224,17 @@ animation for rows, columns, containers and elements, kept in a
 
 A node's drawer is built again on every `init`, so a tool reads the node
 rather than remembering anything about it.
-- A **`toolbar`** item can also have an `iconClass`, `bi bi-plus` otherwise,
+- A **`toolbar`** item can also have an `iconClass`, which it shows alone,
+  with the label as its title, where one without shows a plus and the label;
   and a `source` for the add events, `tool` or `dragdrop` otherwise. With
   `align: 'end'` it goes on the right of the toolbar, beside the source and
-  preview buttons, as its icon alone, with the label as its title.
+  preview buttons, always as an icon - `bi bi-plus` when it has none.
+  `label`, a string or a function called whenever the toolbar is built, stands
+  in for `labelKey` when the label takes parameters; `className` goes on the
+  button. With `inColumn: true` what it makes belongs in a column, as a
+  container or a text does: a click puts it in a row and a column of its own
+  at the end of the canvas, and a drop anywhere but in a column does the
+  same where it was dropped.
 
 - **`onSortable(sortable)`** is handed the function the editor makes all of its
   own lists with. A plugin describes a list; it never touches the drag toolkit
@@ -257,53 +277,96 @@ plugin knows which of its parts move: the tabs plugin makes its strip sortable
 and puts the panes back in strip order in `afterPaneMove`.
 
 
-Text editor plugins
--------------------
+Text
+----
+
+### Plain content
+
+What the editor finds in a column that is not the grid's - loose markup, the
+page it was started on before it had a row - it wraps in a content area with
+no type: the host's **plain content**, `<div class="ge-content">`. While
+editing it is a block with a drawer of two tools, move and delete, and no
+gear; it is edited in the source, with the toolbar's code button, and nothing
+in the editor makes a new one. `getHtml` saves it as it is, and it is plain
+content again when the page comes back. Events call it `kind: 'plain'`.
 
-A text editor plugin edits content areas with a rich text editor. It is
-registered under the content type it edits - the name `content_types` uses -
-and the three that ship, `grideditor.tinymce.js`, `grideditor.ckeditor.js` and
-`grideditor.summernote.js`, are the ones to read:
+A text is a content area with a type on it - `data-ge-content-type` and the
+class `ge-content-type-<type>` - and belongs to the plugin that declares the
+type. A text whose type no plugin declares is a block to move and delete, and
+its drawer says no editor for it is loaded.
+
+### textTypes
+
+A feature plugin that edits text declares its types, and that is all the
+core asks of it:
 
 ```javascript
-$.fn.gridEditor.texts.mytext = function(ge) {
+$.fn.gridEditor.features.mytext = function(ge) {
     return {
-        labelKey: 'text.mytext',               // its name, in the toolbar and the drawer, optional
-        initialContent: '<p>Write here</p>',   // what a new text holds
-        missingKey: 'error.mytext_missing',    // the error when the library is not loaded, optional
-        available: function() { return !!window.MyText; },   // optional, true otherwise
-
-        start: function(block) { … },   // open the editor on this content area
-        stop: function(block) { … },    // close it, and leave the content area as it was
+        textTypes: function() {
+            return [{
+                type: 'mytext',                  // what data-ge-content-type says
+                label: 'My text',                // what the choice of editor shows
+                available: function() { … },     // optional: false, and missingKey is logged instead
+                missingKey: 'error.mytext_missing',  // optional
+                offered: true,                   // optional: false owns the type without offering it
+                edit: function(block) { … },     // the type is on it: take it over, open the editor
+            }];
+        },
     };
 };
 ```
 
-- **`start(block)`** is called when the user clicks a content area of this
-  type. The editor marks it `ge-rte-active` first, and does not call `start`
-  again until it has been stopped. Once the library has taken the content
-  area over, call **`ge.textReady(block)`**: it rewrote what was inside, and
-  the editor and its plugins put their own furniture back - an element's
-  drawer, for one. Call it again whenever the library rewrites the content
-  area again, as tinyMCE's undo does.
-- **`stop(block)`** is called for every content area of this type on each
-  `deinit`, which `getHtml` runs: a content area whose editor never started is
-  the plugin's to ignore. Whatever the library and `start` added - classes,
-  `contenteditable`, inline styles, ids - comes off here.
-- **`available()`** false and the editor logs `missingKey`'s message and
-  starts nothing, without marking the content area, so a later click tries
-  again once the library is there.
-
-A text editor is chosen by `content_types`, never by the `plugins` setting: a
-page that names its containers there has named no editor.
-
-Up to 5.x the main bundle carried a copy of the three shipped ones; since 6.0
-a page loads the plugin of the editor it uses, as it loads any other.
-
-5.x's `$.fn.gridEditor.RTEs.mytext = { init, deinit, initialContent }` still
-works: `init(settings, contentAreas)` and `deinit(settings, contentAreas)` are
-wrapped as `start` and `stop`, with a warning that `RTEs` is deprecated. It goes
-in 7.0.
+The core uses them three ways:
+
+- **Whose a text is.** A content area of a type declared here is the plugin's:
+  the core wraps it in a `.ge-text-block` while editing, as it does plain
+  content, and leaves the drawer to the plugin - put one in on `onInit`. Two
+  plugins declaring one type: the first one registered has it, and the second
+  is warned about once.
+- **What plain content can become.** A click on plain content, with one type
+  offered, makes it a text of that type; with several, it offers them, in the
+  order the plugins were registered. The core fires `before-convert`, which
+  can cancel it, puts the type on the content area - nothing else about it
+  changes - takes its plain drawer off, fires `after-convert` and calls
+  `edit(block)`. See [events.md](events.md).
+- **What `createColumn(size, { content })` holds.** A text of the first type
+  offered, or plain content when there is none.
+
+A plugin opens its editor on a click on its own texts - the core only handles
+clicks on plain content - and closes it in `onBeforeDeinit`, which every
+`deinit` runs while the drawers and the text blocks are still there, before
+`getHtml` reads the markup. Whatever the editor put on the content area comes
+off there.
+
+### The shipped text editors
+
+`grideditor.tinymce.js`, `grideditor.ckeditor.js` and
+`grideditor.summernote.js` each carry what text is to the editor - the text
+block's drawer, the *Text* buttons in the toolbar and the *Add text* tool in
+each column, `createText`, opening an editor on a click and closing it with
+the host's attributes put back, and `textTypes` - from
+`src/js/text/grideditor.text.js`, which the build puts at the top of each.
+However many a page loads, that is installed once.
+
+The editors offered are `content_types`, every one loaded by default, in the
+order the page loaded them; the `plugins` setting does not choose them. A
+text of an editor that is loaded but not offered is still edited.
+
+### A text editor of your own
+
+A feature plugin with `textTypes`, a drawer for its texts, a toolbar item
+with `inColumn: true` if it makes new ones, a click handler that opens its
+editor, and `onBeforeDeinit` to close it.
+[example/custom_editor.html](../example/custom_editor.html) is one, in full,
+on the browser's `contenteditable`, on a page that loads none of the shipped
+editors.
+
+Up to 5.x an editor of a host's own registered under
+`$.fn.gridEditor.RTEs`, and in 5.x and the 6.0 betas under
+`$.fn.gridEditor.texts`. 6.0 removes the first - what is registered there is
+ignored, with a warning - and `texts` is the shipped editors' own registry,
+not a contract.
 
 
 Utility plugins

package/example/custom_editor.html

@@ -0,0 +1,193 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+
+    <!-- CSS dependencies -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.13.1/font/bootstrap-icons.css">
+
+    <!-- Javascript dependencies -->
+    <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js" integrity="sha384-FKyoEForCGlyvwx9Hj09JcYn3nv7wiPVlz7YYwJrWVcXK/BmnVDxM+D2scQbITxI" crossorigin="anonymous"></script>
+
+    <!-- Grid editor CSS -->
+    <link rel="stylesheet" type="text/css" href="../dist/grideditor.css" />
+
+    <!-- The editor, and no text editor of the shipped ones: the one this page
+         edits text with is written below -->
+    <script src="https://cdn.jsdelivr.net/npm/sortablejs@1.15.6/Sortable.min.js"></script>
+    <script src="../dist/jquery.grideditor.min.js"></script>
+
+    <!-- A text editor of the page's own. It is a feature plugin like any
+         other: the core knows nothing of text, and asks the plugins through
+         textTypes which types there are. This one edits with the browser's
+         own contenteditable. -->
+    <script id="simpletext-plugin">
+        (function($) {
+
+            $.extend($.fn.gridEditor.locales.en, {
+                'simpletext.label': 'Simple text',
+                'simpletext.add': 'Simple text',
+            });
+
+            var TYPE = 'simpletext';
+
+            $.fn.gridEditor.features.simpletext = function(ge) {
+
+                /** A content area of this plugin's: its type is on it. */
+                function isOurs(area) {
+                    return area.attr('data-ge-content-type') === TYPE;
+                }
+
+                function start(area) {
+                    if (area.hasClass('ge-rte-active')) { return; }
+
+                    area.addClass('ge-rte-active').attr('contenteditable', 'true').trigger('focus');
+                }
+
+                // Whatever start put on the content area comes off: what is
+                // left is what getHtml saves
+                function stop(area) {
+                    area.removeClass('ge-rte-active').removeAttr('contenteditable');
+                }
+
+                /**
+                 * A text's drawer. The editor wraps each content area of a
+                 * column in a .ge-text-block while editing, and leaves the
+                 * drawer of a type a plugin declares to that plugin.
+                 */
+                function createDrawer(textBlock) {
+                    var area = textBlock.children('.ge-content');
+                    var drawer = $('<div class="ge-tools-drawer ge-text-drawer" />').prependTo(textBlock);
+
+                    ge.createMoveTool(drawer);
+                    ge.createTool(drawer, ge.t('tool.delete_text'), 'ge-delete-text', 'bi bi-trash', function() {
+                        ge.deleteNode('text', area, ge.t('confirm.delete_text'), function(removed) {
+                            stop(area);
+                            textBlock.slideUp(function() {
+                                textBlock.remove();
+                                removed();
+                            });
+                        });
+                    });
+                }
+
+                function onClick() {
+                    if (isOurs($(this))) { start($(this)); }
+                }
+
+                return {
+                    // The types this plugin edits. The core uses them to know
+                    // whose a content area is, and to offer them when the
+                    // host's plain content is clicked: edit() is handed the
+                    // content area once the core has written the type on it
+                    textTypes: function() {
+                        return [{
+                            type: TYPE,
+                            label: ge.t('simpletext.label'),
+                            edit: function(area) {
+                                var textBlock = area.parent('.ge-text-block');
+                                if (textBlock.length && !textBlock.children('.ge-tools-drawer').length) {
+                                    createDrawer(textBlock);
+                                }
+
+                                start(area);
+                            },
+                        }];
+                    },
+
+                    // A button to make a new text, in a row of its own or
+                    // where it is dropped in a column
+                    toolbar: [{
+                        labelKey: 'simpletext.add',
+                        iconClass: 'bi bi-fonts',
+                        kind: 'text',
+                        inColumn: true,
+                        create: function() {
+                            return $('<div class="ge-content" />')
+                                .addClass('ge-content-type-' + TYPE)
+                                .attr('data-ge-content-type', TYPE)
+                                .html('<p>Write here</p>');
+                        },
+                    }],
+
+                    onInit: function() {
+                        ge.canvas.find('.ge-text-block').each(function() {
+                            var textBlock = $(this);
+                            if (textBlock.children('.ge-tools-drawer').length) { return; }
+                            if (isOurs(textBlock.children('.ge-content'))) { createDrawer(textBlock); }
+                        });
+
+                        ge.canvas.off('click.simpletext').on('click.simpletext', '.ge-content', onClick);
+                    },
+
+                    // Before the drawers and the text blocks come off
+                    onBeforeDeinit: function() {
+                        ge.canvas.find('.ge-content').each(function() {
+                            if (isOurs($(this))) { stop($(this)); }
+                        });
+                    },
+
+                    onDeinit: function() {
+                        ge.canvas.off('click.simpletext');
+                    },
+                };
+            };
+
+        })(jQuery);
+    </script>
+
+    <script>
+        $(function() {
+            $('#myGrid').gridEditor({
+                new_row_layouts: [[12], [6, 6], [4, 4, 4]],
+            });
+
+            $('#output').on('click', function() {
+                $('#html').text($('#myGrid').gridEditor('getHtml'));
+            });
+        });
+    </script>
+
+    <title>Grid Editor example - a text editor of your own</title>
+</head>
+<body>
+    <!-- Back to the demo index -->
+    <div class="container pt-3">
+        <a class="link-secondary" href="index.html"><i class="bi bi-arrow-left"></i> All demos</a>
+    </div>
+
+    <div class="container py-3">
+        <h2>A text editor of your own</h2>
+        <p class="text-body-secondary">
+            No tinyMCE, CKEditor or summernote on this page: its text editor is
+            the plugin in the page's source, a few dozen lines on the browser's
+            <code>contenteditable</code>. The markup below had no text editor's
+            type on it, so the editor took it for the host's <em>plain
+            content</em>: it can be moved and deleted, and a click makes it a
+            text of this editor. The second column was saved as one already.
+            See <a href="../docs/plugins.md">docs/plugins.md</a>.
+        </p>
+
+        <div id="myGrid">
+            <div class="row">
+                <div class="col-lg-6">
+                    <h3>Plain content</h3>
+                    <p>Loose markup of the page's own. Click it and it is a simple text.</p>
+                </div>
+                <div class="col-lg-6">
+                    <div class="ge-content ge-content-type-simpletext" data-ge-content-type="simpletext">
+                        <p>A simple text, saved as one: a click edits it.</p>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <p class="mt-4">
+            <button type="button" class="btn btn-outline-primary btn-sm" id="output">Show getHtml</button>
+        </p>
+        <pre class="bg-body-tertiary border rounded p-3 small"><code id="html"></code></pre>
+    </div>
+</body>
+</html>

package/example/index.html

@@ -61,6 +61,14 @@
                 <span class="text-body-secondary">The plugin model, with a container plugin written in the page itself</span>
             </a>
 
+            <a class="list-group-item list-group-item-action" href="custom_editor.html">
+                <div class="d-flex justify-content-between">
+                    <strong>A text editor of your own</strong>
+                    <code class="text-body-secondary">custom_editor.html</code>
+                </div>
+                <span class="text-body-secondary">No shipped text editor: one written in the page as a plugin, on the textTypes hook</span>
+            </a>
+
             <a class="list-group-item list-group-item-action" href="attributes.html">
                 <div class="d-flex justify-content-between">
                     <strong>A plugin with a modal</strong>

package/example/wrap_content.html

@@ -63,9 +63,11 @@
             <code>.col-*</code> anywhere. Grid editor does not refuse it: it
             wraps all of it into one row with a single
             <code>col-lg-12</code> column, and from there it is an ordinary
-            grid. Add rows, split the column, edit the text, then press
-            <em>Refresh</em> to see the html that comes out: as
-            <code>getHtml</code> returns it, to save and edit again, and as
+            grid. What was in there is the page's <em>plain content</em>: a
+            block to move and delete, edited in the source, until a click
+            makes it a text of tinyMCE's. Add rows, split the column, edit the
+            text, then press <em>Refresh</em> to see the html that comes out:
+            as <code>getHtml</code> returns it, to save and edit again, and as
             <code>getPlainHtml</code> returns it, to publish.
         </p>
 

package/package.json

@@ -34,7 +34,7 @@
     "comment": "A scoped package publishes restricted unless it is told otherwise.",
     "access": "public"
   },
-  "version": "6.0.0-beta.3",
+  "version": "6.0.0-beta.4",
   "main": "dist/jquery.grideditor.js",
   "files": [
     "dist",