app-gelinkt-notuleren 3.0.0
Release information
Frontend
App
Editor
Plugins
Executive summary
Executive summary
Move to prosemirror for core editing logic
What do we mean with core logic? These are things like typing a character, backspace, delete, enter, copy/paste, undo, lists and basic table support.
What is prosemirror? https://prosemirror.net/ is a software framework for building wysiwyg text editors in javascript. It differs from editors like CK, tinyMCE, Froala, etc... in that it does not come as a complete product. There is no "prosemirror editor", only "editors built with prosemirror", much in the same way we use Ember for building frontends.
Switching to prosemirror meant adapting their way of modelling a text document, and working with their system for making edits to that document. We maintain full control over even the most internal and low-level of editing operations, should we need to. However prosemirror also ships with a bunch of useful tools for common things like lists and tables, which help immensely with development speed and stability, since their implementation has been tested by a large community of users. Even still, while we do use them as a base, we were able to easily adapt those tools to our needs. A concrete example: by default Prosemirror uses a different logic to answer the question "what styles are applied in this selection?", when the selected text contains a variety of bold, italic, and underlined parts. In this space, we see this question answered two ways: either we say that "all styles are active", meaning their toolbar buttons are lit up and clicking them would remove that style, or the opposite. Both are sensible, and we were easily able to change the logic to the choice we had made.
Big time gains were made especially in the areas of lists and tables, and the backspace/delete behavior in and around them. This has historically been a massive timesink because of its complexity and many, many edge cases.
In general, it is an absolute pleasure to work with as a dev and we're very excited to have more time to implement cool features relating to the "rdfa" part of the "rdfa-editor".
Open questions
First, two important points of conflict that weren't blocking, but require further discussion.
ctrl+aand drag-selecting all text are not the same thing https://binnenland.atlassian.net/browse/GN-3968current decision templates seem awkward in the light of features such as inserting structures and articles https://binnenland.atlassian.net/browse/GN-3969
User-facing changes
While our goal for this release has been to make the transition as seamless as possible, replacing the entire inner workings of the editor inevitably has quite a few noticeable effects on the editing experience. All the changes we know of can be considered either improvements, or "different but equally sensible", although we are aware users might percieve this differently and are ready to tweak things based on their feedback.
Here follows a list of noticeable changes to the core editing experience. This list is non-exhaustive, as it is impossible to analyze every possible interaction.
Lists
Behavior in and around lists has changed considerably, we believe entirely for the better. We have always considered list behavior to be a weak point, and a lot of concessions were made in the past to prevent devtime from spiralling out of control. Lists are inherently complex and don't lend themselves well for interactions with "normal" editing controls such as enter and backspace, because there is no "one obvious way" in which everything should behave. The idea the "industry" has adopted is to make sure that eventually, the user will be able to create the list they want, even if it might take a few more steps than strictly needed. This is a point where we believe we've made huge progress.
In general, users now have a more intuitive control over lists.
backspacing at the start of a list item first deletes the bullet point (making the item go "out" of the list), and on second press joins the line to the previous item
similar behavior with delete in the other direction
pressing the enter key continues the list (as before), but pressing it again on the newly created empty list item removes that item and makes a "real" newline, allowing users to end the list without having to use the toolbar
In lists, and in many other places,
shift+enterforces a new line without interrupting the document structure, allowing multi-line list items"unindenting" a list item at "level one", now takes that item out of the list. Previously we simply disallowed this.
Tables
arrow keys now work more intuitively, navigating the table cells correctly
same with the
tabkeycopying tables from other sources no longer inserts them as "uneditable" content. All tables are editable.
hitting tab in the last cell inserts a new row into the table
Placeholders Placeholders are the "fill in here" spaces with yellow background which are common in templates:
It is now much more obvious when a placeholder is selected:
A placeholder can only be either fully selected or not, making it clear that that entire section will get replaced when users start typing, or hit backspace/delete. A single click anywhere in the placeholder will select it, as will moving into it using the arrowkeys. Backspacing after/deleting in front of a placeholder will also fully remove it.
Other editing behavior
Using the control key in combination with Left/Right/Backspace/Delete moves the cursor/removes whole words at once, as is common in just about any input field. Similarly, shift+arrowkeys extends the selection in those directions, add control to extend by whole words.
The "undo" action no longer considers every single typed character to be a "step". Edits inside a certain timespan (around a second or so) are grouped, making it much less frustrating to go back longer distances, while still maintaining adequate granularity.
ctrl+yis mapped to "redo", which is the counterpart of the "undo" action, which itself is mapped toctrl+zThe redo action is an entirely new feature.
Plugins
Paradoxically, the most noticeable impact of the new core is outside that core, in the plugins. This is mainly due to the introduction of the concept of a document "schema", which is a fundamental Prosemirror concept. The schema rigidly describes the structure of the document. E.g.: what types of headers are available, whether certain sections are mandatory or not, the definition of things like placeholder nodes, list items, etc.
For plugins, the fact that a document is now much more structured and well-defined opens up a world of possibilities. But, inevitably, added structure means a certain rigidity in the way some ux patterns "should" be implemented. This is the area where we've had to discover how Prosemirror likes to do things, and has caused us to re-evaluate design choices made in the past, when there were different limitations.
As in the core editing experience, feature parity was the main goal, and a "seamless transition" a close second. But even as we release this version, we're discovering new ways to present information to the user, which may be more intuitive.
Below is a list of the most important changes to plugins, which we kept due to a mix of "we think it's better" and "doing it the old way is a bit difficult now"
Variables
The variable feature has received the biggest rework, but the behavior has actually not changed all that much. A variable looks like this now:
Clicking inside it now makes it very clear it is selected, and the value selector in the sidebar pops up as before:
Contrary to a placeholder, users can freely type inside variables, and any placeholders that were included in the variable value work as expected:
This means it is now very clear when you are typing "in" the variable, and when you're typing outside of it. This is actually extremely important, as the variables are actually sections of rdfa-annotated text, so any content in them can have an impact on processing down the line. We consider this new ux pattern a massive breakthrough in the work towards annotations and making rdfa-data more visible and accessible to the user. While we've kept it simple to ease the transition, the possibilities of this pattern are endless.
As an aside: on a technical level, there is a separate editor "inside" the variable block! This is made transparent to users as the transition is seamless, but it opens up a lot of options for customizing the behavior inside these kinds of blocks. It has little impact on perfomance, since only one "inner" editor is active at any time, so even in documents with many variables the performance stays optimal.
Things to note
you can't go "in" or "out" of a variable section with the arrow keys, it requires a mouse click. We believe this communicates the idea of an autonomous "unit" and as such kept this default behavior.
similarly, when backspacing/deleting into a variable section, the whole section gets removed at once, which is also consistent with placeholders.
Dates
While the variables claim the most profound technical changes, the date plugin probably has the most noticeable UI changes.
It is now no longer possible to type inside a date block. The date can only be adjusted using the card in the sidebar. This was done to make sure that inserted dates are always correct (so mistakes like "30th of februrary" are avoided), and in a format that the computer can actually understand.
With that said, we did recognize the need for users to express dates in a variety of formats. To this end, we've included options for a "long" and "short" format, as well as a way to express custom formats. Documentation for how these custom formats works will follow in another document.
Other plugins
The "insert title" action is now shown as a warning card, which makes it clear that a title is required and should be inserted. It's only a warning, and doesn't block the user from saving the document.
when selecting everything with the
ctrl+ashortcut, the user can replace the current template should they wishthe "insert article" action now inserts the article after the one the cursor is in instead of always at the end
The "structure actions" menu in the sidebar now has a toggle for deleting a structure with its content or without it.
Deploy guide
set up the maintenance frontend in docker-compose.override.yml
optional: create a backup of the database with
/data/useful-scripts/virtuoso-backup.sh ${name-of-container}bring down everything with docker-compose down
bring up just the maintenance frontend with
docker-compose up -d editorgit fetch && git checkout v3.0.0production only: make sure to bump the version of controle-editor to the correct frontend version (3.0.0)
start the database and migrations service with
docker-compose up -d virtuoso migrationsverify the migrations have completed successfully
remove (comment out) maintenance frontend from docker-compose.override.yml
start the stack
docker-compose up -dverify it's up
Deployments
Last updated
