@cwrc/leafwriter

v3.5.0

Published

8 months ago

intuitive document editing with xml and rdf

Downloads

180

0High
0Medium
0Low

canadian-writing-research-collaboratory

lucaju

ajmacdonald

xml rdf editor annotation

LEAF-Writer

NPM npm type definitions

The XML & RDF online editor of the Linked Editing Academic Framework

Partial Documentation - Working in progress

LEAF-Writer

Overview

The Linked Editing Academic Framework (LEAF) has developed an in-browser text markup editor (LEAF-Writer, previously known as CWRC-Writer) for use by individual scholars and collaborative scholarly editing projects that require a light-weight online editing environment. This package is the base code that builds the editor as a React component to be embedded in any website.

A default version of the LEAF-Writer powers LEAF-Writer Commons (https://leaf-writer.leaf-vre.org), a public and free-to-use enviroment to edit XML documents, tagging named-entities, create Web Annotations, and generate open linked data.

Use

Install

LEAF-Writer is developed in JavaScript and is partially typed (work in progress). It is designed as a React component (work in progress), but can be also used in valilla js. It is available on NPM and CDN services.

Caveat: Due to LEAF-Writer legacy code, it cannot yet be used as a ES6 module. You will need to copy the necessary files to the public folder on the server and set up the base url if necessary.

NPM

npm install @cwrc/leafwriter

CDN Direct link

https://unpkg.com/browse/@cwrc/[email protected]/

Basic Setup

Copy necesary files

Copy the content of dist folder to a folder named leafwriter in the public folder on the server.

cp -R ./node_modules/@cwrc/leafwriter/dist/* ./public/leafwriter

Load main dependencies in the html file

<html>
  <head>
    ...
    <script type="text/javascript" src=“https://unpkg.com/browse/@cwrc/leafwriter/dist/index.min.js”></script>
    <link href="./leafwriter/css/index.css" rel="stylesheet"  type="text/css" />
    ...
  </head>
  <body>
    <script src="./leafwriter/index.min.js"></script>
    ...
  </body>
</html>

Instantiate and initialize

import type { Leafwriter } from '@cwrc/leafwriter'; //Add LEAF-Writer types for intellisense

//* This only tells typescript that Leafwriter exists on the global scope (Window) */
declare global {
  interface Window {
    Leafwriter: any;
  }
}

const container = document.getElementById('#leaf-writer');
const editor = new Leafwriter.Leafwriter(container); //it must be an HTML ELEMENT (i.e., a div)

editor.init({
  document: {
    xml: '<xml ...>', // Required (string)},
  },
  settings: {
    //! Important: Tell LW where its dependencies (extra CSS, images, web worker) are located.
    // In the example, we add the files to the folder `leafwriter` in the public folder.
    // The default is '.'
    baseUrl: './leafwriter',
  },
});

You must pass a div container to a new LEAF-Writer instance. LEAF-Write will render itself in this container.

Then you initiate it by passing a Config Object. Note: To use LEAF-writer to create Web Annotations, you should pass the user name and URI in the config object.

Get current content from the editor

Using async/await

//Assuming the instance is named `editor`

const currentContent = await editor.getContent();
console.log(currentContent);

// Or as a Promise
editor.getContent().then((currentContent) => {
  console.log(currentContent);
});

Config Object

The config objects takes 4 objects:

Document (Required)
User (Optional)
Settings (Optional)
Preferences (Optional)

Document

The document object has 2 properties:

| Name | Type | Default | Description | | ----- | -------- | ------- | ---------------------------------------------------------------------------------- | | xml* | string | | (Required) The XML document to be rendered on LEAF-Writer | | url | string | | The Document's URL. It is used as an IRI on Web Annotations created on LEAF-Writer |

User

The user object has three properties, exclusively used to assign a creator to Web Annotations created on LEAF-Writer

| Name | Type | Default | Description | | ------ | -------- | ------- | ------------------------------------------------------------------ | | name* | string | | User's name. | | uri* | string | | (Required) URI pointing to the user info page, profile, or account | | email | string | | user's email |

Settings

The settings object has three main properties used to set up and customize LEAF-Writer. (more to come).

| Name | Type | Default | Description | | ----------------- | --------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | authorityServices | (AuthorityService | string)[] | | An list of authority services or their id's seting up the authority services. If you pass a string, it will enable the corresponding authority service. Use the object AuthorityService to fine tune the set up. | | baseUrl | string | . | Important: By default, LEAF-Writer will load its dependencies (web workers, on-demand modules, extra CSS files) from the root folder. If these files are not on the root, you should define the path to these dependencies here. For instance, set this property to /path/to/project/addons/ if you put LEAF-Writer dependencies in this folder. | | readonly | boolean | false | Set LEAF-Writer readonly (prevent editing functionalities) | | schemas | Schema[] | | An array of schemas to be included as supported by default. |

AuthorityService

Configures authorities services used to run entity lookups. LEAF-Writer includes 6 authority services supporing 5 types of entities:

DBPedia: Person, Place, Organization, Title, and Thing.
Geonames: Place.
- Note: Disabled by default because the Geonames endpoint needs authentication.
  - To use Geonames, you must define your own username.
Getty: Person and Place.
LGPN: Person (Greek names).
- Note: Disabled by default since it is not frequently used.
VIAF: Person, Place, Organization, Title (book), and Thing.
Wikipedia: Person.

Individual users can turn each authority on and off, as well enable and disabled specific entities in each authority depending on their preferences.

All properties are optional, except for the id.

| Name | Type | Default | Description | | -------- | -------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id* | dbpedia | geonames | getty | lgpn | viaf | wikidata | | The authority's id. Other values will be ignored. | | enabled | boolean | | Enable / Disable Authority. Note: the user can manually enable the authority in the settings panel. | | entities | NamedEntitySettings | | An obeject with namedEntity property with boolean values. This object not only defines the entities avialable for the authority, but also if they are enabled or didabled by default. | | settings | Object: { username: string } | | An arbitrary object with a username property. Used to pass a username to Geonames |

NamedEntitySettings

| Name | Type | Default | Description | | ------------ | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | person | boolean | | The authority's id | | place | boolean | | Enable / Disable Authority. Note: the user can manually enable the authority in the settings panel. | | organization | boolean | | An array of tuples containing the Entity Name and a boolean. Enable / Disable a specific entity lookup. Note: the user can manually enable the entity in the settings panel. | | title | boolean | | An arbitrary object with a username property. Used to pass a username to Geonames | | rs | boolean | | An arbitrary object with a username property. Used to pass a username to Geonames |

Example:

Let’s say you want to enable LGPN and Geonames, disable Getty, and disable lookups for organization, title, and thing on wikidata.

[
  'lgpn',
  { id: 'geonames', settings: { username: 'geonamesUsername' } }
  { id: 'getty', enabled: false }
  { id: 'wikidata', entities: { organization: false, title: false, thing: false }}
]

Schemas

Out-of-the-box, LEAF-Writer supports the following schemas:

There are two ways to use LEAF-Writer with other schemas.

On-demand: By opening a document with an unsupported schema and adding it as a custom schema. This will save the schema information on the Browser's localstorage and it will be available locally as long the user remains logged in.
Permanently: By passing a list of supported schemas on LEAF-Writer initialization config

The schema object as five properties:

| Name | Type | Default | Description | | --------- | ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id* | string | | Unique id | | name* | string | | A human-readable name to be displayed to the user | | mapping* | tei | teiLite | orlando | cwrcEntry | | Define how to parse tag names and map schema-specific functionalities. LEAF-Writer supports these four mappings, which are bound to the document's root element (except for teiLite, which is a TEI variation and uses the TEI root element) | | rng* | string[] | | A collection of URI pointing to the schema. It must be RNG schemas. LEAF-writer will get the first option unless the connection is not available. In this case, it will try to load the schema from the other options in order. Loading alternative routes to the schema will not change the document definitions. | | css* | string[] | | Similar to the rng property. A collection of URI pointing to the schema's CSS. LEAF-writer will get the first option unless the connection is not available. In this case, it will try to load the CSS from the other options in order. Loading alternative routes to the CSS will not change the document definitions. |