Inserting galleries in the visual editor

Gallery3x adds an “Insert from gallery” button to the MODX visual editor. It opens a window for choosing images of the current resource and inserts a ready snippet call (or an <img> tag) with the IDs of the selected images into the text. Depending on the chosen “output view”, different chunks go into the call — a Fancybox grid, a carousel, simple thumbnails and so on.

Supported editors

• CKEditor — the ckeditor 1.4.x extra (CKEditor 4);
• TinyMCE RTE — the tinymcerte 3.x extra (TinyMCE 6).

The adapter is chosen automatically: Gallery3x scripts detect which editor is loaded on the page and silently switch off if “their” editor is not there. You do not need to change the settings of the CKEditor / TinyMCE RTE extras — the button is registered programmatically.

Enabling and settings

All settings are in the MODX system settings, namespace gallery3x, area “Visual editor (RTE)”.

After enabling the setting, open a resource with the visual editor — the button appears in the toolbar (in CKEditor as a separate group at the end, in TinyMCE at the end of the first row). If there is no button, reload the manager page with the browser cache cleared (Ctrl+F5).

Image selection window

Clicking the button opens a window with all images of the current resource:

• Group filter — top left; the “Reset” button brings back all images;
• Thumbnails — a click selects/deselects an image (no Ctrl needed); selection also works across pagination pages;
• The click order is remembered — images are output on the page in exactly the order you selected them;
• The “Selected: N” counter and the “Clear selection” button — top right;
• at the bottom — insert options (see the next section) and the “Insert” / “Cancel” buttons.

Insert modes

The “Uncached call” checkbox (on by default) inserts the tag as [[!Gallery3x?...]]. For single images the call is always cached — this is safe and faster.

Output views

The “output view” defines which pair of chunks goes into the snippet call. The standard set:

Custom output views (gallery3x.rte_views)

The set of views is a JSON array in the gallery3x.rte_views setting. Each element is one item of the “Output view” drop-down in the insert window.

Good to know before configuring:

• The setting replaces the whole set rather than adding to it. If you need the standard views, include them in your JSON too (a ready block is in example 1).
• The order of elements in JSON = the order in the drop-down; the first one is selected by default. The “Single image (img tag)” view is always added to the end of the list automatically.
• The view is “baked” into the tag on insert. Changing gallery3x.rte_views affects only future inserts — tags already in the content do not change (but you can edit them by hand right in the text).
• After changing the setting, reload the resource edit page — the config is read when it opens.
• Quotes inside JSON values are escaped as \" (see example 4).

Example 1. Standard set + a custom view

The most common case: keep everything as it was and add one view of your own. Below is the full JSON of the standard set with a “My grid” view on your own chunks added at the end:

[
  {"key": "fancybox_grid", "label": "Fancybox: grid", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem"},
  {"key": "fancybox", "label": "Fancybox: image + thumbnails", "tplOuter": "tpl.Gallery3x.Fancybox.outer", "tplThumb": "tpl.Gallery3x.Fancybox.thumbItem"},
  {"key": "carousel", "label": "Carousel (lightGallery)", "tplOuter": "tpl.Gallery3x.carousel.outer", "tplThumb": "tpl.Gallery3x.carousel.item"},
  {"key": "static", "label": "Simple thumbnails", "tplOuter": "tpl.Gallery3x.static_thumbnails.outer", "tplThumb": "tpl.Gallery3x.static_thumbnails"},
  {"key": "my_grid", "label": "My grid", "tplOuter": "tpl.My.GridOuter", "tplThumb": "tpl.My.GridItem"}
]

Choosing “My grid” and three images inserts:

[[!Gallery3x? &ids=`17,5,42` &tplOuter=`tpl.My.GridOuter` &tplThumb=`tpl.My.GridItem`]]

Example 2. Fenom views on the component's ready chunks

Gallery3x already includes Fenom versions of the Fancybox chunks — they can be added as separate views (pdoTools required):

[
  {"key": "fancybox_grid", "label": "Fancybox: grid", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem"},
  {"key": "fb_grid_fenom", "label": "Fancybox: grid (Fenom)", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter.fenom", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem.fenom", "fenom": true}
]

What gets inserted:

[[!Gallery3x? &ids=`17,5,42` &tplOuter=`tpl.Gallery3x.Fancybox.GridOuter.fenom` &tplThumb=`tpl.Gallery3x.Fancybox.GridItem.fenom` &fenom=`1`]]

Example 3. Extra parameters via extra: limit and sorting

The extra field is an extension point: any Gallery3x snippet parameters are appended to the end of the call. A “Latest 6 images” view (handy with the “Whole group” / “All resource images” modes — the limit and sorting apply to the dynamic selection):

[
  {"key": "last6", "label": "Latest 6 images", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem", "extra": "&limit=`6` &sortby=`createdon` &sortdir=`DESC`"}
]

What gets inserted (“All resource images” mode):

[[!Gallery3x? &resource=`12` &tplOuter=`tpl.Gallery3x.Fancybox.GridOuter` &tplThumb=`tpl.Gallery3x.Fancybox.GridItem` &limit=`6` &sortby=`createdon` &sortdir=`DESC`]]

Example 4. Filtering by fields with &where (escaping quotes)

The &where parameter takes JSON — inside the setting value its quotes must be escaped with a backslash: \". A “Special images only” view (the special field, the star in the gallery):

[
  {"key": "special", "label": "Special images only", "tplOuter": "tpl.Gallery3x.Fancybox.GridOuter", "tplThumb": "tpl.Gallery3x.Fancybox.GridItem", "extra": "&where=`{\"special\":1}`"}
]

In the same way you can filter by any image field: {\"extra_num\":2024}, {\"description:!=\":\"\"} and so on.

Example 5. Your own snippet instead of Gallery3x

If you have a wrapper snippet with its own logic (its own defaults, caching, processing), put it in the snippet field — the button will insert a call to it, passing the same parameters (&ids / &group / &resource and chunks):

[
  {"key": "my_slider", "label": "Slider (custom snippet)", "snippet": "MySlider", "tplOuter": "tpl.MySlider.outer", "tplThumb": "tpl.MySlider.item", "extra": "&autoplay=`1` &interval=`5000`"}
]

What gets inserted:

[[!MySlider? &ids=`17,5,42` &tplOuter=`tpl.MySlider.outer` &tplThumb=`tpl.MySlider.item` &autoplay=`1` &interval=`5000`]]

Example 6. An @INLINE template without a separate chunk (advanced, pdoTools required)

With "fenom": true the wrapper can be given right as an @INLINE string — without creating a chunk. Inside, the $files array is available (all image fields + URLs of all sizes: small_url, medium_url, large_url, original_url). tplThumb is not needed in this case:

[
  {"key": "inline_row", "label": "Thumbnail row (inline)", "fenom": true, "tplOuter": "@INLINE {foreach $files as $f}<a href=\"{$f.original_url}\"><img src=\"{$f.small_url}\" alt=\"{$f.alt}\"></a>{/foreach}"}
]

Such a view is handy for small utility inserts when creating a chunk is overkill. For anything more than a couple of lines, it is still better to create a chunk — it is easier to edit and reuse.

Common mistakes

• Forgot to include the standard views in your JSON — only yours remain in the list (not a bug, but often a surprise).
• Invalid JSON (an extra comma, unescaped quotes) — the component falls back to the standard set and writes a warning to the MODX error log (Manage → Error log).
• A typo in a chunk name — the call is inserted, but the gallery is not output on the page; check the names in the “Elements” tree.
• A Fenom chunk without "fenom": true (or without pdoTools installed) — the page shows raw template text instead of the gallery.

Snippet changes

Gallery3x: the &ids parameter

&ids=`17,5,42` — output specific images by their IDs (this is the parameter used by the “Selected images” mode).

• An image ID is unique across the site and identifies the image unambiguously, so resource selection parameters (&resource / &resources / &parents) are not needed and are ignored in a call with &ids. Otherwise an image attached to another resource would silently disappear from the output.
• The output order equals the order of the listed IDs; it can be overridden with the usual &sortby.
• The active filter (active = 1), as well as &where, &limit, &showInactive, work as usual.
• Fully backward compatible: calls without &ids are not affected — the previous resource-based selection code runs.

g3xGetImage: the original size

[[g3xGetImage? &input=`17` &options=`original`]] now returns the URL of the original file (previously only thumbnail sizes were available).

Possible problems and solutions

Technical reference

• core/components/gallery3x/elements/plugins/plugin.gallery3x_rte.php — MODX plugin (OnDocFormPrerender event): checks the settings and the template, passes the config to JS, includes scripts and styles;
• assets/components/gallery3x/js/mgr/rte/gallery3x.rte.picker.js — the selection window (ExtJS), an editor-independent core: Gallery3x.rte.openPicker(callback);
• assets/components/gallery3x/js/mgr/rte/gallery3x.rte.ckeditor.js — CKEditor 4 adapter: registers the plugin and button via CKEDITOR.plugins.add + the instanceCreated/configLoaded event;
• assets/components/gallery3x/js/mgr/rte/gallery3x.rte.tinymce.js — TinyMCE 6 adapter: registers the plugin via tinymce.PluginManager.add and adds gallery3x to plugins/toolbar1 of the TinyMCERTE.editorConfig object before tinymce.init() is called;
• assets/components/gallery3x/css/mgr/rte.picker.css — window styles and the CKEditor button icon;
• assets/components/gallery3x/gallery3x-icon.svg — the Gallery3x icon (master copy).

The window gets its data through the component's regular connector (connector.php, the File\GetList processor and the groups processor from gallery3x.groups_processor) — it works only in the manager context with an active session.

To support another editor, write a new adapter that calls Gallery3x.rte.openPicker(function (html) { /* insert html into the editor */ }) on its own event.