Libro client

Linked data Browser, primarily for use with linked_rails backends.

Also powers Argu.

Getting started

Either use as part of Argu, or as a standalone browser;

• npm install or yarn to install dependencies.
• When using Libro standalone, create a .env file by copying .env.template.
• yarn run start to start the hot reload enabled development build.
• Visit http://localhost:3001/

Development

Commit messages are automatically checked for compliance with conventional commits. Make sure that nodejs is available in the environment where modifying git commands (i.e. commit, rebase, etc) are executed.

• yarn run start run the development server.
• yarn run build to create production builds, stored in /dist.
• yarn run lint to run the ES linter. See .eslintrc for the plugins and exceptions to the recommended set used.
• yarn run test to run all tests.

Structure

Tests are placed in __tests__ folders and should end in .spec.ts(x). Most of the actual runtime code of the app is divided into the various "modules".

• app - Code that runs in the browser
  • components - React components needed to bootstrap Libro.
  • helpers - Helpers for bootstrapping Libro.
  • modules - Encapsulated modules of behaviour.
  • ontology - Shared ontology definitions which don't fit into a particular module.
  • routes - The different routes in Libro, almost always routes to LinkedObject.
  • translations - Stores translations. See the I18n chapter.
• bin - Binaries
• dist - Generated and managed by the build scripts. Here are the distribution files stored, they aren't necessarily public.
• tests - Helpers related to testing.
• webpack - Configuration for your favorite bundler.

Modules

Most of the code should be placed into the async submodule, so it can be loaded on-demand.

• async - Code which is to be loaded asynchronously, via Suspense or import()
  • Contains the module structure (except for async).
• components - Plain React components and suspense loaders for async components.
• hooks - Custom React hooks.
• lib - Other code which can't be properly categorized into the other folders
• middleware - Link middlewares, use for processing custom actions.
• ontology - Files containing ontology related to the module.
• theme - Custom theme, only applicable to App modules.
• topologies - Topology Provider components.
  • index.ts - Default export should contain an array of all the topology IRIs this module defines.
• views - Link components which are registered in the store, mounted by Libro automatically via the Resource component.
• index.ts - The module definition.
• dependencies.ts - A list of other modules the test suite of this module needs to run.

Styling & Theming

Libro uses the makeStyles hook from @material/styles for styling. These can plug into the theming system to enable runtime (server provided) theming options. Themes and their settings can be found in the theme folder of App modules. Whenever writing components be sure to use the appropriate theme variables if applicable.

Testing

Tests are written using jest and @testing-library/react. An enhanced version for views can be found in the test-utilities.

Test which render react components need to declare their environment as jsdom

I18n

Internationalization is done via react-intl.

Do not touch the en.json and all *.json files in /app/lang, they are autogenerated from source.

Adding a translation

1. Use the translation in code
2. Run the t10s:extract script, take note of any warning or errors (esp. duplicates)
3. Add the key and translation to the other locales.
4. Run the t10s:compile script
5. Commit

CAUTION: When deleting translations (e.g. removing a react-intl component), make sure to manually search/check and update the translations files to ensure consistency.

Debugging

When a component isn't rendering as expected. So, your Link View / Property isn't showing. Check the following:

• Is the record in the store?
  • LRS.collectRecord("insert record_id") to see the data if present.
  • LRS.collectRecord($r.props.subject) when having the Resource component selected in React Devtools component panel.
• Is the record being fetched?
  • Check the /bulk requests in the network tab in your browser's debugger view.
  • The requested records are in the payload panel.
  • The retrieved records are in the preview or response panel.
• Check if your view is actually registered, i.e. is the component properly exported and included?
• Is the element present in the virtual DOM? Use the React debugging tools to find the component. Does it contain the Property components that you expect it to have?
• If there is an element, check its data by selecting the Resource element in the React debugging tools and executing dev.data in the console.

Rendering external resources

If you want to preview data from the web:

• Run this in an apex Rails console: Page.argu.update(allowed_external_sources: ['https://myexternaldomain.com'])
• Open the resource in libro using the /org/resource? endpoint: https://argu.localdev/argu/resource?iri=externalresource

Recommended Dev tools

• Chrome plugins: React Dev Tools, Redux Dev Tools