Embeddable Editor: test scenarios

Context

ABB/LBLOD has developed an embeddable version of it’s RDFA-Editor (based on html+rdfa, prosemirror, and ember.js).

This embeddable version should be easily implementable in various applications or websites, and unlock the world of annotating text with rdfa to our stakeholders.

Several software vendors have shown interest already and will start implementing the RDFA-editor in a first test environment this autumn. We expect this to be an important jump-off point for wider reuse of LBLOD document templates and other technologies.

To be sure that all will adopt smoothly, we are looking for test implementations to learn any possible pitfalls and gaps in the documentation, so we can tackle them before Autumn 2023.

General testing concerns

As we mentioned above, our goal is a smooth integration process, with clear and complete documentation. If at any point something is not clear, make note of it, that's exactly what we're hoping to improve.

For each scenario, please keep track of the following elements:

• Your process and technical tools you used.

• Any difficulties encountered in the integration process

• What did you have to adapt in order to make it work?

• Any problems you identify regarding UX/UI

• Other remarks or suggestions

Test scenarios

Level 1: Basic implementation: hosted bundle

For this test, take an empty HTML page and introduce the editor to it, following the process outlined in the readme. Use the hosted sources.

To see if everything works, you can compare it with the reference implementation at https://embeddable.gelinkt-notuleren.lblod.info/.

Level 2: Basic implementation: self-hosted bundle

Repeat the first test, but this time host the relevant files yourself. (At this point you will likely need a simple HTTP server to host the static files for testing. Use any you like.)

We expect that this is the setup most 3rd party implementers will prefer, as they will likely want to control the domain the scripts are hosted from (to avoid issues with VPNs, restrictive firewalls, etc).

Level 3: real-world test: self-hosted bundle

Implement the editor in an existing web application. Use any at your disposal. The more complicated the application, the better.

Any and all tech stacks are of interest, including low-code platforms such as Wordpress, Microsoft Dynamics, and the like. If it hosts an HTML page, it should be able to integrate the editor.

Additionally, take a first stab at controlling the editor with javascript:

• get out HTML content

• store it (can be in memory, but the more "realistic", the better)

• load the stored content back into the editor

From our experience, this is the single most important process for 3rd parties, so any hiccups or doubts are of particular interest.

Level 4: real-world test: citation plugin

Keep the setup(s) you had in the previous test, but this time we will focus on configuring and using the various plugins that are bundled with the embeddable editor.

Citation plugin

The citation plugin is the most important plugin by quite a margin. It allows users to reference the Flemish legal code in their documents. It does this by integrating with de vlaamse codex.

For this test:

• check the information in the readme about the citation plugin

• using that information, see if you can use it to insert a few citations. Note: there are 2 ways to trigger the plugin, verify both work as explained.

Level 5: real-world test: templates

This is the final stage. Let's start with a short overview of how we ultimately expect 3rd party applications to use our services:

• the application provides the framework for storing, managing and publishing documents.

• for creating documents, or parts of documents, the application provides an in-browser editing environment, using our editor and its plugins.

• For most documents, users will not start from scratch, but rather load a template from one of ABB's endpoints (which we call "registries"). These templates ensure consistent wording for complex legal constructions, and together with the plugins, they allow the user to create a document that not only has the correct textual content, but also has important details annotated with RDFA.

• This will allow an automated parser to understand the document, and will allow collection of data. It will also help in reducing mistakes, through validation and connection with official datasources.

• once the content is created, the application can take the annotated HTML document and continue its process. No matter how or where the document ends up being hosted, our scrapers (which we call harvesters) can collect it and extract the data from it.

For this test, we ask you to simulate this flow on a nominal level.

Note: the integration process of acquiring the templates will (even in its final form) assume a working knowledge of SPARQL, which will not be explained in the documentation. Additionally, the data-model that templates follow has not been finalized, and is not yet documented. As such, we will use a simple manual approach. The focus of the test remains on the editor.

In this test:

• fetch a template from https://dev.reglementairebijlagen.lblod.info (details below). This is a template that requires the editor to be in 'regulatoryStatement' mode.

• load the template into the editor

• verify the following plugins work as expected:

  • article-structure-plugin

  • template-variable-plugin

  • table-of-contents-plugin

Getting a template

The process we will describe is a bit manual, but it is the easiest to explain, and requires no sparql knowledge or network request code, ensuring it will work in whatever environment your chosen test app is running in.

• log in to the test environment at https://dev.reglementairebijlagen.lblod.info/mock-login (it will ask you to select an account, select the only option.)

• select the first menu item "Regulatory attachments"

• browse the list and select one you like, or create a new one. This is a test environment, so you can go wild.

• on the edit page of your chosen regulation, open the console and type the following: __PC.htmlContent

• your console will print out the template as a string.

Contact

We are happy to organize a technical introduction meeting to give some context where needed.

Questions can be asked via [e-mail]