@logilab/cwelements

cwelements

CWElements is a library of reusable React components for building web application with CubciWeb. It relies on @logilab/cwclientlibjs to query a CubicWeb instance.

To know what's in CWElements, read Description of the main components.

To use a component with monaco-editor, which is needed for the syntaxic colouring, read Using monaco-editor-based components.

For details about the components architecture, read Library architecture.

Description of the main components

Entity Form

The EntityForm displays a detailed description of a CubicWeb instance entity, entity type, relation or attribute referenced by an EID. For the concerned EID, a list of its attributes is displayed using EntityAttribute (and its subclasses: FloatEntityAttribute, IntegerEntityAttribute, etc.); followed by a list of its relations grouped by relation name (MergedEntityRelationsGroup).

Entity Browser

The EntityBrowser allows browsing a CubicWeb schema with an EID search bar. An EntityForm of the entity, entity type, relation or attribute designated by the EID is displayed. The entities, entity types, relations or attributes in an EntityBrowser can also be browsed by clicking on the links displayed in an EntityForm.

Schema Navigator

The SchemaNavigator loads and displays a CubicWeb schema. When instanciating a SchemaNavigator, you can decide to show or hide the CubicWeb Metamodel entities. It is composed of three columns: the first displays the schema's CWETypes, the second one the CWRelations and CWAttributes and the third one CWETypes based on the selected CWRelation. The user can filter the column lists based on the items' name with a search bar. The user can click on the items to select them and filter the other columns based on the constraints between them. For example, if a user selects "Comment" in the first column, the second column is updated to show only the relations and attributes which apply to "Comment" and the third column only shows the entity types which can be linked to "Comment".

RQL Querier

The RQL Querier is a component to query a CubicWeb instance. A standalone version is available (StandaloneRqlQuerier). The basic components of a RQL Querier are a query input field, an execute button and a query results element. Different versions of these components are available: QueryInputText and QueryMonacoEditorTextInput (in QueryInput) for the query input field, JSONQueryResults, TableQueryResults and TabbedQueryResults (in QueryResults).

RQL Browser

The RqlBrowser is a tool to help write RQL queries. It instanciates a Schema Navigator and a RqlQuerier.

A Show Metamodel option can show CubicWeb metamodel entities and relations in the Schema Navigator.

A Auto-help option can change filter the Schema Navigator columns based on the cursor position in the QueryEditor.

A Clear selection button can reset the Schema Navigator state (clear search bars and selection).

Using monaco-editor-based components

The QueryMonacoEditorTextInput, included in RqlBrowser and RqlBrowserQuerier is based on monaco-editor for syntaxic colouring, cursor tracking, etc.

To make it work, you need to install monaco-editor in your own project:

npm install monaco-editor

Library architecture

Historic global component architecture

For now, most components follow an architecture in which an interface or a class(e.g., EntityBrowser) is defined using its own props and state interfaces (e.g., EntityBrowserProps and EntityBrowserState).

Then a component (e.g., DefaultEntityBrowser) implements this interface using default props defined in a constant (e.g., ENTITY_BROWSER_DEFAULT_PROPS).

The props include rendering functions and the Default components the inherent logic and state update.

A rendering function defined in the props is likely to call another rendering function of the props. The render function of ENTITY_BROWSER_DEFAULT_PROPS calls renderInput, renderViewWaiting and renderViewData from the DefaultEntityBrowser. So if you override many functions check that they have the expected behaviour.

The components which follow this logic are:

• DefaultEntityBrowser implements EntityBrowser
• DefaultEntityForm extends EntityForm
• DefaultEntityRelation extends EntityRelation
• EntityRelationsGroup is extended by DefaultEntityRelationsGroup and MergedEntityRelationsGroup
• EntityRelationsEditor is implemented by DefaultEntityRelationsEditor and SingleEntityRelationsEditor
• EntityAttribute is extended by DefaultEntityAttribute, BooleanEntityAttribute, EnumEntityAttribute, FloatEntityAttribute, FloatEntityAttributeWithStaticUnit and IntegerEntityAttribute

Hooks as a replacement

In earlier versions of this library, the RqlQuerier (a component to edit, execute and view the results of an RQL query) worked as explained above: rendering functions were defined as constant default props, and the logic behind the component (executing the query, etc.) was implemented in the DefaultRqlQuerier component. To make this component more flexible, its state and logic (e.g., query execution) have been gathered in a functional state useQuery which can be reused in any component dealing with their own rendering. The functional components StandaloneRqlQuerier and RqlBrowser both uses the functional state useQuery with their own rendering. This logic was also applied to the SchemaNavigator.