Commit 9af0eab3 authored by Daniele Berardo's avatar Daniele Berardo

Merge branch 'pages/add-pages-in-order' into 'master'

Pages | Add pages in order

See merge request !37
parents fafd09a7 c7c9d77d
Pipeline #189705057 passed with stages
in 13 minutes and 48 seconds
{
"name": "@tecnojest/widget-base",
"version": "1.4.32",
"version": "1.4.40",
"lockfileVersion": 1,
"requires": true,
"dependencies": {
......
{
"name": "@tecnojest/widget-base",
"author": "Tecnojest srl https://www.invidea.it",
"version": "1.4.32",
"version": "1.4.40",
"publishConfig": {
"registry": "https://npm.invidea.it"
},
......
......@@ -26,12 +26,13 @@ const config = {
},
sidebar: {
forcedNavOrder: [
"/introduction", // add trailing slash if enabled above
"/codeblock"
],
collapsedNav: [
"/codeblock" // add trailing slash if enabled above
"/about", // add trailing slash if enabled above
"/getting-started",
"/embeddable-widget",
"/templates",
"/contributing"
],
collapsedNav: [],
links: [
{ text: "Energenious", link: "https://energenious.eu" },
{ text: "Live Examples", link: `${pathPrefix}/storybook` }
......
---
title: "About"
---
# 🚧 Work in progress 🚧
---
title: "Additional Documentation"
---
# Micro Frontends
The idea of micro frontends has been extensively explained by Martin Fowler.
[Check out this article if would like to learn more.](https://martinfowler.com/articles/micro-frontends.html)
---
title: "Purpose"
---
# 🚧 Work in progress 🚧
---
title: "Use cases"
---
# 🚧 Work in progress 🚧
---
title: "Syntax Highlighting"
metaTitle: "Syntax Highlighting is the meta title tag for this page"
metaDescription: "This is the meta description for this page"
---
The following is a code block with JavaScript language syntax highlighting.
```javascript
import React from '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
- const data = ['1','2'];
+ const data = [1,2];
```
## Live Editing example
```javascript react-live=true
<button className={'btn btn-default'}>Change my text</button>
```
---
title: "Sub Page"
metaTitle: "Syntax Highlighting is the meta title tag for this page"
metaDescription: "This is the meta description for this page"
---
The following is a code block with JavaScript language syntax highlighting.
```javascript
import React from '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
- const data = ['1','2'];
+ const data = [1,2];
```
## Live Editing example
```javascript react-live=true
<button className={'btn btn-default'}>Change my text</button>
```
---
title: "Contributing"
---
## Contributing to the codebase
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)
---
title: "Guide"
---
# 🚧 Work in progress 🚧
---
title: "Embeddable Widget"
---
# 🚧 Work in progress 🚧
---
title: "Additional Functionalities"
---
# 🚧 Work in progress 🚧
---
title: "Global API"
---
# 🚧 Work in progress 🚧
---
title: "Methods"
---
## Examples
### 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
```ts
classes.forEach((externalClass: ExternalCSSClass) => {
const querySelector = `[data-role="${externalClass.role}"]`;
this.injectCSSClass({
uid,
className: externalClass.className,
querySelector
});
});
```
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.
Example:
```jsx
const MyElement = () => <h2 data-role="heading">My widget</div>;
```
5. ✅ Success! User sees the dark-themed widget.
---
title: "Getting started"
---
# First steps
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
---
title: "Configuration"
---
## Configuration
You can define the following static in the main Widget class:
- <code>externalScripts</code> (static) e.g.:
```js
static externalScripts = [
{
'name': 'jquery-validate',
'src': 'https://ajax.aspnetcdn.com/ajax/jquery.validate/1.7/jquery.validate.min.js'
'depends_on': 'jquery'
},
{
'name': 'jquery',
'src': 'https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.js'
}
];
```
- <code>options</code> (static) - options that apply to all widgets in the same namespace, e.g.:
> They will override `options` from `defaultProps`
```ts
static options: Options = {
appendFooter: true;
appendTooltip: true;
singleton: true;
}
```
The above are a subset of the `Options` object below:
```ts
interface Options {
// should append a footer at the bottom
appendFooter?: boolean;
// should append a tooltip with dependencies at the bottom
appendTooltip?: boolean;
// can only one widget of the type exist
singleton?: boolean;
// should a cookie be set with the token
setCookie?: boolean;
// cookie domain used for setting the cookie
setCookieDomain?: string | null;
// should use AJAX to load the script instead of appending a <script> tag
loadScriptAJAX?: boolean;
// the token used for authentication
token?: string;
// name of the token (the key in localstorage)
tokenName?: string;
// main css class of the widget
className?: string;
// credentials can be saved here from the hosting environment
credentials?: string | Object;
// can be used to emit scoped events
scope?: string;
}
```
---
title: "Environmental Variables"
---
## Environmental variables
The following environmental variables are evaluated at runtime, overwrite them to change the desired behaviour:
- <code>WIDGET_TITLE</code>: The widget title displayed in the main page (default to project's title in package.json file)
- <code>WIDGET_MAIN_CSS_CLASS</code>: Add a class name to every element of the widget to increase specificity.
- <code>WIDGET_HIDE_EXPLANATION</code>: Should the widget title and a link to the latest widget's version script be shown on the page?
- <code>WIDGET_ASSET_SERVER</code>: Path to the server used for static asset distribution (public path). Defaults to "/".
- <code>WIDGET_USE_CLEANSLATE</code>: Should a CSS reset be applied?
- <code>WIDGET_UNCOMPRESSED</code>: Should a compressed version of assets be provided in the production mode?
- <code>PORT</code>: The port to be used for the development server. Defaults to 80.
---
title: "Installation"
---
## Get started
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.
<a id="existing-project"></a>
### Existing project
Simply follow the instructions above to login and change configurations, then run the usual routine:
npm install
npm start
<a id="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:
```json
"devDependencies": {
...
"@babel/core": "7.7.4",
"@babel/plugin-proposal-class-properties": "7.7.4",
"@babel/plugin-proposal-decorators": "7.7.4",
"@babel/plugin-proposal-export-namespace-from": "7.7.4",
"@babel/plugin-proposal-function-sent": "7.7.4",
"@babel/plugin-proposal-json-strings": "7.7.4",
"@babel/plugin-proposal-numeric-separator": "7.7.4",
"@babel/plugin-proposal-throw-expressions": "7.7.4",
"@babel/plugin-syntax-dynamic-import": "7.7.4",
"@babel/plugin-syntax-import-meta": "7.7.4",
"babel-eslint": "10.1.0",
"babel-loader": "8.1.0",
"babel-preset-airbnb": "4.4.0",
"clean-webpack-plugin": "^3.0.0",
"compression-webpack-plugin": "^3.1.0",
"copy-webpack-plugin": "5.0.5",
"css-loader": "3.2.0",
"cssimportant-loader": "0.4.0",
"dotenv": "^8.2.0",
"dotenv-webpack": "^1.7.0",
"duplicate-package-checker-webpack-plugin": "^3.0.0",
"eslint": "6.7.1",
"eslint-config-airbnb": "18.0.1",
"eslint-loader": "3.0.2",
"eslint-plugin-import": "2.18.2",
"eslint-plugin-jsx-a11y": "6.2.3",
"eslint-plugin-react": "7.17.0",
"eslint-plugin-react-hooks": "1.7.0",
"file-loader": "^6.0.0",
"html-webpack-plugin": "^3.2.0",
"mini-css-extract-plugin": "0.8.0",
"node-sass": "4.13.0",
"postcss-increase-specificity": "0.6.0",
"postcss-loader": "3.0.0",
"raw-loader": "^4.0.1",
"sass-loader": "8.0.0",
"source-map-loader": "^1.0.1",
"style-loader": "1.0.1",
"tape": "^4.13.0",
"uglify-loader": "^3.0.0",
"uglifyjs-webpack-plugin": "^2.2.0",
"url-loader": "^4.0.0",
"webpack": "4.42.0",
"webpack-cli": "3.3.10",
"webpack-dev-server": "3.10.3",
"webpack-obfuscator": "0.18.5",
"webpack-serve": "3.2.0",
"webpack-shell-plugin": "^0.5.0"
}
```
4. (optional) Create a file called <code>.gitignore</code> and paste the following lines:
```
gitignore
node_modules
coverage
**/dist/
.DS_Store
.env
package-lock.json
```
5. Install remaining packages (from official registry to speed up download)
npm install --registry=https://registry.npmjs.org/
6. Add start and build script into script part of package.json:
```json
"scripts": {
...
"build": "webpack-cli --config ./node_modules/@tecnojest/widget-base/webpack.config.js --mode production",
"start": "webpack-dev-server --config ./node_modules/@tecnojest/widget-base/webpack.config.js --host 0.0.0.0"
}
```
7. Create a main file named src/index.js in the project root dir, implementing the basic methods of the JavaScript API:
- <code>createElement(props)</code>: ...
- <code>render(component,el)</code>: ...
- <code>unmountComponentAtNode(node)</code>: ...
when developing a widget based on React the configuration would be:
#### Index file
```jsx
import EmbeddableWidget from "@tecnojest/widget-base";
import Widget from "./components/widget";
import React from "react";
import ReactDOM from "react-dom";
EmbeddableWidget.Widget = Widget;
EmbeddableWidget.React = React;
EmbeddableWidget.Engine = {
createElement: props => {
return <Widget className={process.env.WIDGET_MAIN_CSS_CLASS} {...props} />;
},
render: (component, el) => ReactDOM.render(component, el),
unmountComponentAtNode: node => ReactDOM.unmountComponentAtNode(node)
};
export default EmbeddableWidget;
```
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:
<code>npm install typescript ts-loader @babel/preset-env @babel/preset-typescript</code>
Then create a <code>tsconfig.json</code> file at the root of your project and paste the following configuration:
```json
{
"compilerOptions": {
"outDir": "./dist/",
"sourceMap": true,
"strictNullChecks": true,
"module": "commonjs",
"jsx": "react",
"target": "es5",
"allowJs": true,
"allowSyntheticDefaultImports": true,
"skipLibCheck": true,
"esModuleInterop": true
},
"include": ["src"],
"exclude": ["node_modules", "dist"]
}
```
7. Start the project
npm start
---
title: "React"
---
# 🚧 Work in progress 🚧
---
title: "TypeScript"
---
# 🚧 Work in progress 🚧
---
metaTitle: "Landing Page"
title: "Widgets"
metaTitle: "Widgets - Energenious"
metaDescription: "Documentation of the library and templates for creating widgets."
---
Some introduction text. Lists out all the headings from h1 to h6. Easy to customise. Some more text. Additional text.
# Heading H1
Heading 1 text
## Heading H2
Heading 2 text
### Heading H3
Heading 3 text
#### Heading H4
Heading 4 text
##### Heading H5
Heading 5 text
###### Heading H6
Heading 6 text
## Lists
- Item 1
- Item 2
- Item 3
- Item 4
- Item 5
---
title: "Introduction"
metaTitle: "This is the title tag of this page"
metaDescription: "This is the meta description"
---
Some introduction text. Lists out all the headings from h1 to h6. Easy to customise.
# Heading H1
Heading 1 text
## Heading H2
Heading 2 text
### Heading H3
Heading 3 text