To run this project you will need a package manager such as `npm`.
To install it, follow the guide at [npmjs.com](https://www.npmjs.com/get-npm).
### Library
To be able to use the widget API you will need to download the `@tecnojest/widget-base` package or build the `lib` yourself.
To be able to use the widget API you will need to download the `@tecnojest/widget-base` package or build the `lib` yourself.
#### Installing from the npm registry
If you are a registered partner, you will be able to download the package from the official registry. You will need to configure your local npm engine to point to Tecnojest's registry, by doing the following:
# authenticate in the private npm registry
...
...
@@ -42,17 +45,19 @@ if during the first `npm login` step you receive a `UNABLE_TO_VERIFY_LEAF_SIGNAT
and try again.
#### Building the lib yourself
Everyone is able to build the `lib` themselves. To do so, follow these steps:
Everyone is able to build the `lib` themselves. To do so, follow these steps:
1. Clone the repository
2.`cd` into the repository
3.`npm install` to install the dependencies
4. To build, run:
4.1 OSX / Linux: `npm run build`
4.2 Windows: `npm run build-windows`
4.1 OSX / Linux: `npm run build`
4.2 Windows: `npm run build-windows`
To link the `lib` in your widget template:
a) Modify the import in the widget template of your choice to point to the built lib instead of `@tecnojest/widget-base`
b) Run `npm link` in the `lib` folder and `npm link @tecnojest/widget-base` in the widget template folder
a) Modify the import in the widget template of your choice to point to the built lib instead of `@tecnojest/widget-base`
b) Run `npm link` in the `lib` folder and `npm link @tecnojest/widget-base` in the widget template folder
<aid="get-started"></a>
...
...
@@ -62,17 +67,19 @@ This repository contains the documentation, lib and templates for creating widge
Additional templates or implementations of widgets can be created by following the [lib's README](./lib/README.md#index-file)
<aid="folder-structure"></a>
## Folder structure
In the repository you can find the following folders:
*[doc](./doc)
Contains a thorough description and outlines the purpose of the whole project in markdown.
See [the first article on the concept](https://blog.energenious.eu/?p=74).
*[lib](./lib)
The core of this project. Contains the skeleton for rendering widgets written in different techologies.
-[doc](./doc)
Contains a thorough description and outlines the purpose of the whole project in markdown.
See [the first article on the concept](https://blog.energenious.eu/?p=74).
-[lib](./lib)
The core of this project. Contains the skeleton for rendering widgets written in different techologies.
*[templates](./templates)
-[templates](./templates)
Basic, working implementations of widgets written in various technologies, ready to be developed further. It is recommended to start off with these templates.
To use a template, please refer to its corresponding README.
...
...
@@ -82,6 +89,10 @@ See [the first article on the concept](https://blog.energenious.eu/?p=74).
To contribute to particular parts of the repository, please refer to the corresponding READMEs.
### CI/CD configuration
Please run the CI/CD locally using GitLab Runner. The guide on how to use it can be found here: [GitLab Runner Installation and Usage](https://medium.com/@umutuluer/how-to-test-gitlab-ci-locally-f9e6cef4f054)
The following is a code block with JavaScript language syntax highlighting.
```javascript
importReactfrom'react';
```
Supports multiple languages.
The following is a code block with diff. Lines with `+` highlighted in green shade indicating an addition. Lines with `-` highlighted in red shade indicating a deletion.
```javascript
-constdata=['1','2'];
+constdata=[1,2];
```
## Live Editing example
```javascript react-live=true
<button className={'btn btn-default'}>Change my text</button>
The following is a code block with JavaScript language syntax highlighting.
```javascript
importReactfrom'react';
```
Supports multiple languages.
The following is a code block with diff. Lines with `+` highlighted in green shade indicating an addition. Lines with `-` highlighted in red shade indicating a deletion.
```javascript
-constdata=['1','2'];
+constdata=[1,2];
```
## Live Editing example
```javascript react-live=true
<button className={'btn btn-default'}>Change my text</button>
To contribute to particular parts of the repository, please refer to the corresponding READMEs.
## CI/CD configuration
Please run the CI/CD locally using GitLab Runner. The guide on how to use it can be found here: [GitLab Runner Installation and Usage](https://medium.com/@umutuluer/how-to-test-gitlab-ci-locally-f9e6cef4f054)
### Applying dark/light theme based on the hosting platform's preferences
To accomplish our goal, we need to have the ability to add some classes to our elements at runtime. Let us first outline the usage flow:
1. User adds a widget to a dashboard and chooses a dark theme.
2. The hosting platform knows that it should apply the dark theme to widget(s), but it does not know which elements can be styled in a particular widget.
3. The hosting platform invokes
```js
EmbeddableWidget.applyExternalCSSClasses({
uid:WIDGET_UID,
classes:[
{role:"background",className:"background--dark"},
{role:"foreground",className:"foreground--dark"}
]
});
```
4. The SDK applies styles to all elements under our widget (resolved by uid) which are found by
Note that, for the SDK to be able to style your widget, you have to define the appropriate `data-role` attributes on elements to be styled. These have to be consistent with the hosting platform's code too, otherwise no styles will be applied.
This repository contains the documentation, lib and templates for creating widgets.
Additional templates or implementations of widgets can be created by following README.
## Prerequisites
### Node.js and npm
To run this project you will need a package manager such as `npm`.
To install it, follow the guide at [npmjs.com](https://www.npmjs.com/get-npm).
### Library
To be able to use the widget API you will need to download the `@tecnojest/widget-base` package or build the `lib` yourself.
### Installing from the npm registry
If you are a registered partner, you will be able to download the package from the official registry. You will need to configure your local npm engine to point to Tecnojest's registry, by doing the following:
# authenticate in the private npm registry
npm login --registry https://npm.invidea.it
# set the registry to point to @tecnojest's scope
npm config set @tecnojest:registry https://npm.invidea.it
if during the first `npm login` step you receive a `UNABLE_TO_VERIFY_LEAF_SIGNATURE` error, then run:
npm config set strict-ssl false
and try again.
## Building the lib yourself
Everyone is able to build the `lib` themselves. To do so, follow these steps:
1. Clone the repository
2.`cd` into the repository
3.`npm install` to install the dependencies
4. To build, run:
4.1 OSX / Linux: `npm run build`
4.2 Windows: `npm run build-windows`
To link the `lib` in your widget template:
a) Modify the import in the widget template of your choice to point to the built lib instead of `@tecnojest/widget-base`
b) Run `npm link` in the `lib` folder and `npm link @tecnojest/widget-base` in the widget template folder
To be able to use the widget API you need to integrate this package in your project. Follow the steps in [New project](#new-project) if you are creating a new project from scratch, or in [Existing project](#existing-project) if you are trying to run an existing project locally. In either case you will need to configure your local npm engine to point to Tecnojest's registry, by doing the following:
# authenticate in the private npm registry
npm login --registry https://npm.invidea.it
# set the registry to point to @tecnojest's scope
npm config set @tecnojest:registry https://npm.invidea.it
if during the first `npm login` step you receive a `UNABLE_TO_VERIFY_LEAF_SIGNATURE` error, then run:
npm config set strict-ssl false
and try again.
<aid="existing-project"></a>
### Existing project
Simply follow the instructions above to login and change configurations, then run the usual routine:
npm install
npm start
<aid="new-project"></a>
### New project
1. Init new project
npm init
2. Install widget base
npm install @tecnojest/widget-base
3. Add peer dependencies into devDependcies of package.json file:
This file must include at least the EmbeddableWidget.Engine part, implementing the three methods <code>createElement(...)</code>, <code>render(...)</code>, and <code>unmountComponent(...)</code> - (the example above uses React and ReactDOM).
### React
If you also use ReactJS then install the basic modules: <code>npm install react react-dom</code>
### TypeScript
If you want to use TypeScript then install the necessary modules:
