@giancosta86/jardinero-frontend

Jardinero - Frontend

Pluggable, React-based frontend for Jardinero

Jardinero - in both its TypeScript edition for NodeJS and its Flask-based Python edition - is a web stack devoted to linguistic analysis, whose pluggable frontend is provided by this project.

The main reasons for having a dedicated frontend package are:

• clarity and separation of concerns: Jardinero - which already consists of a fairly sophisticated stack - can now focus just on the underlying backend

• abstraction - because the backend can handle frontend communication by using strongly-typed APIs, which hide low-level details via the FrontendWebSocketServer class

• reusability: whatever the current backend technology, the frontend remains the very same - communicating via websockets

jardinero-frontend is actually a triple package, because it contains:

• the ready-made website, that can be installed as a set of static files into another project

• a TypeScript library - containing for the TypeScript-based backend

• utility scripts to easily plug the frontend into existing tech stacks

Installation

npm install @giancosta86/jardinero-frontend

or

yarn add @giancosta86/jardinero-frontend

The public API entirely resides in the root package index, so you shouldn't reference specific modules.

Basic usage

Starting the development server

To run the frontend development server - for example, on port 3000 - you may want to add the following line to your scripts section in package.json:

"scripts": {
  "start-frontend": "jardinero-start-frontend 3000"
}

or, to be more sophisticated:

"scripts": {
  "start-frontend": "concurrently \"jardinero-start-frontend 3000\" \"wait-on --delay 2000 --interval 1000 http://localhost:3000/\""
}

Consequently, your start script will probably become:

"scripts": {
  "start": "concurrently \"yarn start-backend\" \"yarn start-frontend\"",
}

In your backend code, you'll need to:

• redirect to the frontend development server when in development mode

• serve the actual frontend files, from a directory of static files, when in production mode. To copy the frontend files to the aforementioned directory, please consider using the jardinero-copy-frontend script

Development redirection

When in development mode, you should redirect the traffic to the frontend development server.

Additionally, please remember to activate CORS for websockets when in development mode.

Communication protocol

Query parameters

The query parameter that should be passed to the frontend is:

• backend-port: used only in development mode - when the frontend runs on a dedicated port on localhost; it contains the port of the backend server, used for websocket communication

WebSocket messages - From frontend to backend

The backend must handle a few websocket messages - directly or via the FrontendWebSocket class, which hides most of the internal details:

• dictionary_status_request - requests the current status of the dictionary - including whether a pipeline is running

• start_pipeline - tries to start the pipeline for creating a new copy of the dictionary

• cancel_pipeline - tries to cancel a running pipeline, if any

• run_command(command: string) - runs a command (usually, a SQL string) on the plugin loaded by the backend

WebSocket messages - From backend to frontend

These are messages that the backend can (and should) send to the frontend - again, if possible, via the FrontendWebSocket class:

• initialize_frontend: initializes the frontend with details such as the plugin name and the initial query within the editor. It must contain a payload of type InitializationMessage

• dictionary_status_response: returns the current status of the backend dictionary - including the status of the pipeline. It must contain a payload of type DictionaryStatus

  This message can be sent after a dictionary_status_request, or in broadcast - upon specific background events such as dictionary updates

• command_response - sent as a response to run_command. It must contain a payload of type CommandResponse

Available bin scripts

• start-jardinero-frontend [<port>]

  Starts the development server, listening to the given <port>, defaulting to 8080 - the very same port opened by Webpack upon yarn start

  Please, note: you can alternatively start the Webpack dev server - listening on port 8080 - just by running the project's start script:

  yarn start

  However, that requires access to the project's source directory - which is why the ready-made script is usually more convenient.

• copy-jardinero-frontend <target directory>

  Copies all the distributable files to the given <target directory> - creating it as needed.

Special thanks

• Rainbow loader from Preloaders.net