hubl/README.md at a4007d7d4ca8fe18d291b87dd8b784c4da40894c

Jean-Baptiste Pasquier cf1add07cb minor: dynamic npm imports

2021-07-05 18:05:23 +02:00

23 KiB

Raw Blame History

A magic orchestrator that allows any Blox to thrive in a decentralized way, built on top of Startin'blox.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

To install Orbit, you'll need:

A DjangoLDP Server (djangoldp>2)
A Prosody Server (with appropriate modules) (optional)
A SMTP Server (optional)
NodeJS on your machine

Before diving in you have to check your DjangoLDP Server supports the following LDP packages:

djangoldp_account
djangoldp_uploader
an oidc_provider (eg: django-webidoidc-provider)

Those packages are given with the last stable version tested.

Refer to the documentation to install a DjangoLDP Server with this configuration.

Build the application

In order to find your server(s) the client application needs to be assembled with the proper configuration.

Get the code of the Orbit on your machine:

git clone ...
cd orbit
npm install

Then create a config.json based on your needs, see Mandatory and Optional Modules on this page. For convienence a config.sample.json exists in the source.

Then build your new Orbit:

npm run build

The application bundle is in the dist folder, ready to be deployed everywhere as a static file.

Developpers

Serve, watch files & rebuild on change with this command:

npm run watch

Notice that you may have to restart the watcher for the config.json and for locales files.

Multiple config.json

You can have as many config.*.json as you need.

Watch on a custom config file:

CONFIG_PATH='config.customName.json' npm run watch

Build with a custom config file:

CONFIG_PATH='config.customName.json' npm run build

Mandatory modules

By default, a Orbit includes only individual chat modules.

On Server: djangoldp_account, djangoldp_upload, django-webidoidc-provider packages

On config.json:

{
  "client": {
    "name": "Localhost",
    "logo": "/images/logo.webp",
    "server": "http://server"
  },
  "components": []
}

Where:

client.name is the name of your Orbit
client.logo is an URL to an image file
client.server is the main data server of the client
components is your modules declaration registry

Optional personalisation

On config.json:

{
  "client": {
    "favicon": "/images/favicon.webp",
    "css": "/path/to/custom.css",
    "i18n": {
      "lang": "fr",
      "force": "false"
    }
  }
}

Where:

client.favicon is an URL to a distant favicon
client.css is an URL to a distant CSS that'll be the last one loaded by the Orbit
client.i18n.lang is the fallback langage in case the visitor's browser one does not contain the string
client.i18n.force allows to ignore the visitor's browser langage and force the client.i18n.lang one

Most of other modules will need to have an user logged in, if you want to use communities, then scroll back to the User Registration module, else you'll need to activate the Auto Login module:

    {
      "type": "autoLogin",
      "parameters": {
        "authority": "http://server.url/"
      }
    }

Where:

authority is the OpenID Provider. Usually, if you use djangoldp_account it's the same as your djangoldp server.

Optional modules

Adding modules

You can append any module listed bellow to your components entry on your config.json

Eg. to add the notification module:

{
  "components": [
    {
      "type": "notification",
      "route": false
    }
  ]
}

About

About is a short page about the technology behind Orbit.

To activate about on Orbit, add this module declaration your config.json:

    {
      "type": "about",
      "route": false
    }

Administration

Administration is a minimal modulable admin module for all other ones.

To activate administration on Orbit, add this module declaration your config.json:

    {
      "type": "admin",
      "route": false
    }

Analytics

Orbit support Google or Matomo as analytics trackers. To use them, add to your config.json:

    {
      "type": "analytics",
      "parameters": {
        "type": "matomo",
        "url": "https://my-personal.matomo.cloud/",
        "id": "1"
      },
      "route": false
    }

Circles

Circles define group of users that can chat & share documents togethers.

Community module is mandatory.

To activate them, you need:

On Server: djangoldp_circle, djangoldp_communities, djangoldp_notifications packages

Module declaration, on config.json:

    {
      "type": "circles",
      "parameters": {
        "dataSrc": "federation://circles/",
        "dataSrcJoinable": "federation://circles/joinable/",
        "owners": "federation://users/",
        "post": "server://circles/",
        "users": "federation://users/",
        "noRender": "",
        "xmpp": "wss://xmpp-dev.startinblox.com/xmpp-websocket"
      },
      "federation": [
        "..."
      ],
      "route": "circles"
    }

Where:

dataSrc: is a container listing every circles
dataSrcJoinable: is a container listing every public & not joined circles for the user
post: is where you create new circles
noRender: will load datas only when it'll be on screen, remove it if you encounter any issue
owners: is your users container which contains valid owners
users: is your users container
xmpp is your Prosody with appropriate modules configured on.

Circles extensions

You can extend circles with other components, the same way you would add them to your modules.

Extensions always inherit from its parent federation.

Actually it support: Events, Resources & Polls.

Eg.:

    {
      "type": "circles",
      "parameters": {
        "dataSrc": "federation://circles/",
        "dataSrcJoinable": "federation://circles/joinable/",
        "owners": "federation://users/",
        "post": "server://circles/",
        "users": "federation://users/",
        "noRender": "",
        "xmpp": "wss://xmpp-dev.startinblox.com/xmpp-websocket"
      },
      "federation": [
        "..."
      ],
      "route": "circles",
      "extensions": [
        {
          "type": "events",
          "parameters": {
            "events": "federation://events/",
            "circles": "federation://circles/",
            "get": "federation://events/",
            "post": "server://events/",
            "postTypeevents": "server://typeevents/",
            "typeevents": "federation://typeevents/",
            "uploads": "server://upload/"
          },
          "federation": [
            "..."
          ]
        }
      ]
    }

Communities

Communities are an optional layer to add on an Orbit. They add a SOLID representation of one to many group of users on your data server.

If you're upgrading an existion Orbit, you can assign all your local users to a community this way:

./manage.py create_community --name="My community"

Don't forget to set some users as admin of the community from the Django Admin if you want to allow them to create new users from app.

To activate community on Orbit, add this module declaration your config.json:

    {
      "type": "communities",
      "route": false
    }

Activate the community directory

When you work with a federated application, you may want a directory for communities.

You can activate it by changing the route to anything else than false. Some endpoints will also get needed:

    {
      "type": "communities",
      "parameters": {
        "addresses": "federation://community-addresses/",
        "dataSrc": "federation://communities/",
        "uploads": "server://upload/"
      },
      "route": "communities"
    }

Dashboard

Dashboard includes card generation from HTML. To activate them, you need:

On Server: djangoldp_dashboard packages

Module declaration, on config.json:

    {
      "type": "dashboard",
      "parameters": {
        "dataSrc": "server://dashboards/",
        "noRender": "",
        "target": false
      },
      "route": "dashboard",
      "experimental": [
        "routing"
      ]
    }

A sample fixture can be loaded with ./manage.py loaddata sample.

You can have multiple dashboard module, see the related documentation.

You need the experimental routing enabled to have a Dashboard.

Events

The events module includes a listing of upcoming events and the capability to create new ones. To activate it, you need:

On Server: djangoldp_event packages

Module declaration, on config.json:

    {
      "type": "events",
      "parameters": {
        "events": "federation://events/",
        "circles": "federation://circles/",
        "get": "federation://events/",
        "post": "server://events/",
        "postTypeevents": "server://typeevents/",
        "typeevents": "federation://typeevents/",
        "pastevents": "visible",
        "visiblecheckbox": "visible",
        "visibilityregions": "visible",
        "uploads": "server://upload/"
      },
      "federation": [
        "..."
      ]
    }

Where:

parameters.pastevents: is blank or hidden to display past events
parameters.visiblecheckbox: is blank or hidden to add a checkbox that allow to show events from another website
parameters.visibilityregions: is blank or hidden to have a Region field on events

You can get only future events by using:

        "get": "http://server.url/events/future/",

Internationalization

Each client can overwrite langs files with their own or even create custom langs.

Overwrite langs

On config.json:

    {
      "type": "lang",
      "parameters": {
        "name": "fr",
        "file": "/path/to/fr.json"
      },
      "route": false
    }

Where:

parameters.name allows to use custom client lang file.
parameters.file is the path the the json lang file

Custom langs

Needs client.i18n.force to true and client.i18n.lang to the custom lang name.

Your custom JSON file must contain every keys, from the template and from every bloxes, prefixed by the blox namespace. See example on src/locales/fr.json.

On config.json:

  "client": {
    "i18n": {
      "lang": "pirate",
      "force": "true"
    }
  },
  "components": [
    {
      "type": "i18n",
      "parameters": {
        "name": "pirate",
        "file": "/path/to/yarr.json"
      },
      "route": false
    }
  ]

Where:

parameters.name allows to use custom client lang file.
parameters.file is the path the the json lang file

Setting custom langs will not allow user to choose their own lang.

Invoices

Invoices allow your Projects to manage invoices

Project is mandatory.

You'll need:

On Server: djangoldp_invoice packages

Module declaration, on config.json:

    {
      "type": "projects",
      "extensions": [
        {
          "type": "invoices",
          "parameters": {
            "uploads": "server://upload/"
          }
        }
      ]
    }

Job Offers

Job Offers includes a job board with conversation. To activate them

Community module is mandatory.

You'll need:

On Server: djangoldp_joboffer, djangoldp_skill, djangoldp_upload, djangoldp_conversation packages

Module declaration, on config.json:

    {
      "type": "job-board",
      "parameters": {
        "dataSrc": "federation://job-offers/current/",
        "dataSrcExpired": "federation://job-offers/expired/",
        "postDataSrc": "server://job-offers/",
        "noRender": "",
        "rangeSkills": "federation://skills/",
        "fields": "earnBusinessProviding"
      },
      "route": "job-offers",
      "experimental": [
        "routing"
      ]
    }

Where:

parameters.fields: Optional set of custom fields. Notice that only earnBusinessProviding is already handled on djangoldp-joboffer.

You need the experimental routing enabled to have a Job Board.

Notifications

The notification module adds a bell with user's notification list and a badge on each menus with how much notifications are related to this resource. You'll need:

On Server: djangoldp_notifications packages

On config.json:

    {
      "type": "notification",
      "route": false
    }

One-to-one chat

One-to-one chat allow your users to chat together on a private channel.

Community & User Directory modules are mandatory.

You'll need:

Module declaration, on config.json:

    {
      "type": "chat",
      "parameters": {
        "noRender": "",
        "xmpp": "wss://xmpp-dev.startinblox.com/xmpp-websocket"
      }
    }

Where:

xmpp is your Prosody with appropriate modules configured on.

Polls

The polls module allows user to create polls. To activate it, you need:

On Server: djangoldp_polls, djangoldp_conversation packages

On config.json:

    {
      "type": "polls",
      "parameters": {
        "dataSrc": "http://server.url/polls/",
        "post": "http://server.url/polls/",
        "pollRangeTags": "http://server.url/tags/",
        "pollRangeCircles": "http://server.url/circles/",
        "uploads": "http://server.url/upload/",
        "displayStartEndDates": false
      }
    }

Where:

parameters.displayStartEndDates display or not the start and the end date of polls

Project

Project are a private group chat including Customer and Business Provider management.

Community module is mandatory.

To activate them, you need:

On Server: djangoldp_project packages

Module declaration, on config.json:

    {
      "type": "projects",
      "parameters": {
        "captains": "federation://users/",
        "circles": "federation://circles/",
        "dataSrc": "federation://projects/",
        "dataSrcJoinable": "federation://projects/joinable/",
        "post": "server://projects/",
        "users": "federation://users/",
        "noRender": "",
        "xmpp": "wss://xmpp-dev.startinblox.com/xmpp-websocket"
      },
      "route": "projects"
    }

Where:

captains: is your users container which contains valid captains
xmpp is your Prosody with appropriate modules configured on.

Resources

The resources module includes a listing of indexed resources and the capability to index new ones. To activate it, you need:

On Server: djangoldp_resource, djangoldp_conversation packages

Module declaration, on config.json:

    {
      "type": "resources",
      "parameters": {
        "dataSrc": "http://server.url/resources/",
        "post": "http://server.url/resources/",
        "types": "http://server.url/types/",
        "keywords": "http://server.url/keywords/",
        "circles": "http://server.url/circles",
        "postTypes": "http://server.url/types/",
        "postKeywords": "http://server.url/keywords/",
        "uploads": "http://server.url/upload/"
      }
    }

User registration

The user registration module allows users to self-register.

Community module is mandatory.

If you set allow_self_registration on a community, it'll disable the auto-login feature of Orbit and allow your users to self register on your application.

To activate it, you need:

Module declaration, on config.json:

    {
      "type": "registering",
      "parameters": {
      "dataSrc": "server://open-communities/",
        "authority": "http://server.url/",
        "authorityName": "your-authority-indentifier"
      }
    }

Where:

authority is the OpenID Provider. Usually, if you use djangoldp_account it's the same as your djangoldp server.
authorityName is a visual name of your OpenID Provider

Theme checker

The Orbit theme manager is very handy for customer to easily customize the main colors they want to use.

But developers should verify that their development use those colors to fit the customer wishes.

Module declaration, on config.json:

    {
      "type": "themeChecker",
      "route": false
    }

Then you'll find the color picker tool in the header bar.

Changing the color will set them on the whole app so that you can verify that your development take them into account correctly.

Users Directory

Directory includes a listing of each users of your app and editable individual profile. To activate them, you need:

On Server: djangoldp_skill packages

Community module is mandatory.

Module declaration, on config.json:

    {
      "type": "directory",
      "parameters": {
        "dataSrc": "federation://users/",
        "rangeSkills": "federation://skills/",
        "noRender": "",
        "paginateBy": "30",
        "uploads": "server://upload/"
      },
      "federation": [
        "..."
      ],
      "route": "members",
      "experimental": [
        "routing"
      ]
    }

You need the experimental routing enabled to have a Profile Directory.

  {
    "type": "link",
    "parameters": {
      "icon": "icon-docs",
      "name": "some.path",
      "target": "https://startinblox.com"
    },
    "route": true
  },

Where:

parameters.icon is a valid simple line icon
parameters.name is a path to a translation. You can create your own with the lang component
parameters.target is the target URL

Enfore NPM package version

To enforce a version to get used from NPM, add this to your config.json:

  "npm": [
    {
      "package": "@startinblox/core",
      "version": "0"
    }
  ],

Where:

npm[].package is the package name to include
npm[].version if the version of the package you want to use
npm[].attributes (optional) allows to add attributes to the script element

Package will get required from Skypack CDNs.

Use local packages

Use the npm parameter on your config.json

    {
      "package": "@startinblox/oidc",
      "version": "0",
      "path": "./path/to/sib-auth/sib-auth.js"
    }

Route generation

Orbit will, by default, generate an unique route for every of your module. You can customize this route by setting a route attribute on your module declaration.

Eg. for the Users Directory:

    {
      "type": "directory",
      "parameters": {
        "dataSrc": "server://users/",
        "skills": "server://skills/",
        "uploads": "server://upload/"
      },
      "route": "profiles"
    }

Will lead to http://client.url/profiles as URL to reach the module instead of the default http://client.url/directory.

If you provide no route, then Orbit will use the type as route view name. If two modules share the same route, they'll get suffixed with a random unique id.

Some module don't need any route to be active, set route to false so.

Components can get the route of a module with window.orbit.getRoute('componentName').

Experimental routing

This experimental setting allow to create a view containing a solid-* with every parameters provided without any code.

    {
      "type": "display",
      "parameters": {
        "dataSrc": "server://users/",
        "fields": "name"
      },
      "experimental": [
        "routing"
      ]
    }

will provide a view with:

<solid-display data-src="http://server/users/" fields="name"></solid-display>

Change the default route

By default, Orbit will take a Dashboard as a default route.

You can enforce a component to be the default one by adding defaultRoute to its parameters.

Eg.:

    {
      "type": "directory",
      "parameters": {
        "dataSrc": "server://users/",
        "skills": "server://skills/",
        "uploads": "server://upload/"
      },
      "route": "directory",
      "defaultRoute": true
    }

If there is more than one component with this parameter, it'll be ignored.

Federation generation

Any parameter of your config.json can take benefits from the source generation:

server:// will be replaced by the value of client.server:

    {
      "type": "awesome",
      "parameters": {
        "dataSrc": "server://users/"
      }
    }

federation:// will generate a virtual federated container linking:

client.server
client.servers
component.federation
extension.federation, if on an extension

  {
    "client": {
      "server": "http://serverA",
      "servers": [
        "http://serverB"
      ]
    },
    "components": [
      {
        "type": "awesome",
        "parameters": {
          "dataSrc": "federation://users/"
        },
        "federation": [
          "http://serverC"
        ]
      }
    ]
  }

Will result on a virtual federated container containing http://serverA/users/, http://serverB/users/ and http://serverC/users/ on data-src.

Troubleshooting

Circles or Projects are missing the @user list

Did you properly created subscriptions on your DjangoLDP's server? You can quickly create them with ./manage.py create_subscriptions

I see some technical strings instead of my fallback language strings

By default, the template fallback to fr lang, which is the most complete. If you're using your own fallback lang within your configuration, please ensure that this lang is completly translated.

I see some technical strings instead of my custom language

Using a custom language file does not allow to use the default fallback language.

Built With

Sib-Core - A SOLID-Compliant framework

23 KiB Raw Blame History

A magic orchestrator that allows any Blox to thrive in a decentralized way, built on top of Startin'blox.

Getting Started

Prerequisites

Build the application

Developpers

Multiple config.json

Mandatory modules

Optional personalisation

Allow to login to your application

Optional modules

Adding modules

About

Administration

Analytics

Circles

Circles extensions

Communities

Activate the community directory

Dashboard

Events

Internationalization

Overwrite langs

Custom langs

Invoices

Job Offers

Notifications

One-to-one chat

Polls

Project

Resources

User registration

Theme checker

Users Directory

Add link to left menu

Enfore NPM package version

Use local packages

Route generation

Experimental routing

Change the default route

Federation generation

Troubleshooting

Circles or Projects are missing the @user list

I see some technical strings instead of my fallback language strings

I see some technical strings instead of my custom language

Built With

23 KiB

Raw Blame History