This is a proposal to improve the user experience of Neos.
The Ui of Neos has roughly been the same since the beginning and after the rewrite in react in 2014 from the first looks of it not too many things changed.
Granted behind the scenes a lot of things were improved over the years and also some visual elements were moved here and there and enhanced.
But for the redactor the editing of nodes in the content frame has been almost unchanged and Neos is still successful with this.
For the next version of Neos - the 9.1 release - we commited us to yet improve what we have.
(1) Improve the inline editing, move the toolbar closer to edited content
The toolbar is known to appear during inline editing in the upper side above the content frame. This behavior can still be seen in tools like photoshop or word but other tools nowadays favour inline options.
We want to improve the editing and formatting under the following aspects:
- Reduce the mouse travel time to the toolbar (which is currently located at the top)
- formatting a text bold or inserting a link should be more imminent
- the argument for use of shortcuts (strg+b, strg+k) is to be neglected as we don’t expect our editors to know them by heart, also some options require interaction
- using a table in ckeditor is currently unbearable as every interaction, creating a new column or row has to be done by a complex menu in the top toolbar
- The toolbar is sometimes hard to spot with only few options available and only being shown when clicking on text
- a long known bug increases this problem as the toolbar i have known to disappear
- The toolbar having limited horizontal width - which is reduced on small laptops - can overflow with to many options or plugins enabled and grows unusably large and breaks the Ui layout
- The support of CKEditors undo and redo should visible to the user but should not hint at a full neos node wide undo functionality (currently only its only available via shortcuts like strg+z)
(2) Introduce drag and drop of content nodes
To allow faster and more flexible content editing we want to simplify moving content nodes. Currently, nodes can be moved via the inline toolbars cut (scissor button) and paste them at the desired place.
Working with drag and drop should greatly improve rearranging nodes especially when using nested contents in columns. This is currently also possible by drag and drop via the content tree but for that the technical structure must be understood by the redactor and the content tree is hidden by default.
(3) Improve content node creation
The inline node toolbar allows for node creation (plus button) which opens the node creation dialog to select from all possible nodes to be inserted. The redactor has to choose a relative location to the selected node e.g. insert into, after or before and select or search from all the node types which are here put in groups and enriched with label and sometimes even help text and custom icon.
While this process offers the most information and most flexibility its also still tedious and not especially fast for repeated creations. For creating certain documents a repeating structure of semantic nodes is required. We should be able to predict or configure the node types to be inserted along and likely the current node type might as well be the option for the next one say in an accordion column.
To reduce the complexity here the plus button could appear instead at the top or bottom of the element - according to the mouse position - and upon clicking would show already 3 or more predetermined node types with an option to view all via the node creation dialog.
This is partly inspired by Gutenbergs block creation process and allows for easy and fast determination of where (e.g. into, after, before) and what. If a node does not require the node creation dialog this would result in almost direct node creation with little distraction to the redactor.
(4) Technical Goal: Rely more on CKEditor’s build in features to our benefit
The text editing of nodes is currently powered by CKEditor in Neos. Initially this was just an implementation detail the UI supported even custom editing engines, and it was switched multiple times from aloha to ckeditor 4 and later to 5. Just lately we updated to the latest 5’er version.
This was mostly possible in the past by having a relatively small coupling with the actual editor engine. Neos archived this by shipping a self written toolbar at the static location on the top. The toolbar consists of our Neos buttons and dropdowns which then send events to the given editor implementation.
That design did allow for technical flexibility as we are not dependent on CSS styling of the editor and also strictly define which functions exist and at which location. Over the last years the coupling to CKEditor did increase a lot. This was partly by removing support to implement a custom editor (which was just theoretical after all) and because many plugins exist today which exactly depend on ckeditor - sometimes even a certain version.
We basically moved closer now to CKEditor over the years and will likely stay with that forever. The question begs itself, why dont we want to increase coupling just a little bit and thus allow for more features that are would be build in. Namely that is the ballon editor (popup next to the selected text to style that), various plugins for ckeditor like insert images and also features to improve editing like markdown support for example.
On the technical side we could get rid of most of our CKEditor plugins which mimic their core behavior, remove our self written ui components and also simplify or remove the complex and bug pruned formatting under cursor handling.
(5) Introduce new professional link editor - the Archeopteryx
Neos provides a link editor for inline editing which resides in the upper toolbar and opens a dropdown dialog to define link and possibly title, anchor, target-blank and rel-no-follow.
The link itself can target a node or asset as well as be a regular http link - the determination of this is made while providing or searching a link target: If the entered text matches a node title the node can be selected as target, if it’s an asset title the asset can be selected, and for text starting with http or who look like a regular url it will be processed as http link.
Choosing the correct target as a redactor can be cumbersome because of this hidden complexity and too simple interface. The target search box assumes the title of the target node is already known which is even harder when linking to assets. Also, possible target results are often mixed between assets and nodes - we can assume the redactor knows beforehand what type to link and streamline the process.
The third party neos package Sitegeist.Archeopteryx provides a new link editor as sophisticated replacement. Upon insertion of a link the button opens a whole dialog - hiding all other parts of the ui. The dialog helps step by step to find the correct target. Each target group has a dedicated tab: Document, Asset, Website, Phone and Mail with possibility for extension.
These tabs are each dedicated for choosing a target of that type. For document nodes a full node tree (like the document tree) is shown which enables already known search, filtering and a hierarchy to find a target. While for assets the media browser is shown in which all sorting features like categories, date, name allow easy localisation. Other use cases like plain web. phone and mail links are also supported to create according links with additional input validation and formatting.
While this plugin works really well as drop in replacement, we know that often Neos is viewed as a product with only the features that come shipped. To ensure everyone is gifted with this link editor we want to make the dialog based editor the default.
Technical implications: Merging the archaeopteryx into the Neos.Neos.Ui package
The Archaeopteryx has grown into a full-fledged self-contained plugin
The plugin includes both for client (js) and server (php) opinionated framework code which is not yet part of our react code base or flow respectively.
Aside from the way the plugin is written (using these framework supporting code) its relatively complex and big for a plugin. For example the client code is well-structured and spans 7 js-packages while the whole ui is structured in only 30.
The server code grew with a late decision tremendously and now contains in the application layer 4 endpoints with each a dedicated route, policy, query and query result value object and query handler, flow controller as well as shared value objects and behavior tests.
These endpoints are required for presenting the document tree in the dialog. Their secondary use is to demonstrate how the Neos Ui can borrow this architecture to render its own document tree on the side. The Neos Ui code has grown to be hard maintainable and obscure in that regard and works by having a lot of complexity on the server as well as the client who interchange untyped arrays via a single can-do-it-all endpoint.
As the Neos Ui does not show any concrete modular reusable structure in the regard of building a document tree, the Archaeopteryx has fully reimplemented this with the regular search and filtering as well as custom link specific features.
The Neos team does not agree fully on how the Neos Ui should recover from its growing technical debt which can be seen in many regards but especially in the document tree.
A solution will likely be to move logic back to the server. This has opened some concerns of responsiveness due to more http requests, and also we have to fully agreed on a way to exchange data. Currently, we transfer untyped arrays or XML via a thousand controller actions this is hard to refactor, work with and prone to bugs.
In discussion there have been endpoints with typed client code generated from the php code, or endpoints fully defined by OpenApi to ensure type safety, or GraphQl as it’s used in the new media ui.
The endpoints of the Archaeopteryx are made of self written php and js code. With that they set the way into the direction of the first two options, though we can also be adjusted to use any other kind of protocol.
As long as we agree to move the complexity to the server, we might as well neglect the way how we do it as long as its understandable and comes without new dependencies at first and is easy to maintain.
It’s a lot of work to similize the code from Archaeopteryx to Neos Ui to not make it foreign matter. This step is the right choice so we contribute new patterns back to the Neos Ui and eventually show how to replace the NodeTree with server Queries.
The client code can be reduced from 3 of the original 7 js-packages by tying the Neos Ui and the new LinkEditor well together. This opens new ways how we write components as functional ones without using @neos and @connect as decorator.
In other regards the Archaeopteryx uses new patterns and new dependencies which are from today’s perspective questionable and don’t fit well together with the Neos Ui. The additional dependencies like rx-js, react-final-form, styled-components and react-error-boundary must be replaced in favour of using and extending our code or using native react or observable patterns.