This is the release notes for Cristal.

This release brings three improvements. First, authentication is now supported for the Nextcloud backend (with oauth2 or basic authentication modes). Then, it is possible to configure when the pages are stored on the Nextcloud and File System backends. Finally, we introduced a new editor based on Blocknote. This new editor currently not considered stable and is provided as test only.

New and Noteworthy (since Cristal 0.15)

Full list of issues fixed and Dashboard for 0.16.

For Users

Authentication support for Nextcloud backend

 
Authentication for the Nextcloud backend is now supported, both through basic authentication and OAuth2 authentication. Please refer to the Nextcloud backend documentation to find the complete setup process.

Blocknote editor

 
Blocknote is now an alternative to Tiptap to edit pages. See the Admin section for more details on how to switch the editor to Blocknote.

The main benefits are:

• better block editing experience
• improved editing of tables

For Admins

• Configurable editor: A new editor is now available on the configuration. When undefined, the value falls back to the default editor, which is currently tiptap.

• Configurable root location for FileSystem: The FileSystem backend now allows an admin to set the root location where the documents will be managed on Cristal. Please refer to the specific documentation for more information.

• Configurable root location for Nextcloud: The Nextcloud backend now allows an admin to set the root location where the documents will be managed on Cristal. Please refer to the specific documentation for more information.

For Developers

Reactivue

ReactiVue is a library that enables seamless integration of React components inside of Vue. Although it should be compatible with Vue 2, it is mainly designed to support Vue 3.

The reason this library exists is because Cristal is written in Vue 3, and BlockNote is written in React. To integrate them seamlessly without using BlockNote's headless version - which does not contain any UI element - we decided to test various solutions.

We tried various existing libraries to integrate React inside Vue, but none ended up working properly. So we decided to make a small proof-of-concept on our own to see if we could make it work by ourselves, and we ended up succeeding!

The library is very small (< 500 LoC), and works by wrapping a provided React component inside a Vue component. The latter then sets up a React application, and renders the former inside it. Custom properties can be provided.

Some features include:

• Full support for typing (TypeScript)
• Support for Vue's slots, including types and bindings
• Dynamic properties update - if the provided properties change, they are updated in the mounted component dynamically
• Nesting - you can put a Vue component inside a React component as well! And you can also have multiple levels of nesting
• All types, including complex types (nested records, keys remapping, etc.) are supported
• Customize Vue app when mounting slots

Children provided to React components are mounted as Vue slots, each within their own Vue app. This app can be customized to e.g. add plugins.

Emphasis has been made on keeping the library as simple as possible, and providing robust type safety. It only has two dependencies: Vue and React. No other runtime dependencies are present. Also, no "hack" is used here, we only use tools provided by both Vue and React to make it work. Some "hacks" are used for typing though, as typing dynamic Vue components is not possible otherwise.

Note that, as of 0.16, this library has not been battle-tested. This means some bugs may arise when using this library, even if our own testing didn't show any shortcoming of our current approach.

Universal AST

UniAst, for Universal Abstract Syntax Tree, is a system designed to provide a universal representation of a XWiki document. It exists as a standalone package in Cristal, and is planned to be integrated into XWiki in future versions.

The base operation is the following:

• You take the document's source (markdown, HTML, etc.)
• That code is parsed using UniAst's provided converters
• The AST is then converted to the current editor's internal structure

So to sum up:

• As input: XWiki document => UniAst => any editor
• As output: any editor => UniAst => XWiki document

This structure enables seamless integration of various formats and editors together.

As of 0.16, the current UniAst implementation only provides support for Markdown, in the form of a Markdown => UniAst as well as a UniAst => Markdown converter.

The BlockNote editor contains a UniAst => BlockNote and a BlockNote => UniAst converter. The upside of this system is that any new editor will only have to implement a two-way converter like this to support any other format like Markdown or HTML, both as input and output, without any feature loss.

The UniAst format is not stable yet, and may never be. It will be modified in future releases, so expect breaking changes. Also, it may be superseded by using XWiki's own DOM format (the one used by macros) instead, in order to integrate more seamlessly between the frontend and the backend.

No guarantee is made as to how the UniAst system is going to work, but the general idea of having an intermediary reprensetation is the one we strive for in the foreseeable future (XWiki document => IR => UniAst).

The converters are usually pretty small files, 200~300 lines long, as the format is designed to be very simple and easy to manipulate and extract informations from/into.

Upgrades

Security Issues

Security issues are not listed in issue lists or dashboards to avoid disclosing ways to use them, but they will appear automatically in them once they're disclosed. See the XWiki Security Policy for more details.

Known issues

• Bugs we know about

Credits