Commit 215a3412 authored by Łukasz Starosta's avatar Łukasz Starosta

Filled getting started

parent f90372a5
Pipeline #192447145 passed with stages
in 6 minutes and 22 seconds
---
title: "About"
metaTitle: "Widgets - About"
---
## Introduction
......
---
title: "Purpose"
metaTitle: "Widgets - Purpose"
---
## Composition
......
---
title: "Use cases"
metaTitle: "Widgets - Use cases"
---
## Micro-frontends approach
......
---
title: "Additional Documentation"
metaTitle: "Widgets - Additional Documentation"
---
# Micro Frontends
......
---
title: "Getting started"
metaTitle: "Widgets - 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
......@@ -20,16 +16,21 @@ To be able to use the widget API you will need to download the `@tecnojest/widge
### 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:
If you are a registered partner, you will be able to download the package from the official registry. Otherwise, skip this step and [build the lib yourself](#buildingthelibyourself).
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
```bash
# 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
```
npm config set strict-ssl false
```
and try again.
......@@ -38,7 +39,7 @@ and try again.
Everyone is able to build the `lib` themselves. To do so, follow these steps:
1. Clone the repository
2. `cd` into the repository
2. `cd` into the `lib` folder of the repository
3. `npm install` to install the dependencies
4. To build, run:
4.1 OSX / Linux: `npm run build`
......
---
title: "Installation"
metaTitle: "Widgets - Installation"
---
First, follow the [getting started guide](/getting-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.
<a id="existing-project"></a>
### Existing project
Simply follow the instructions above to login and change configurations, then run the usual routine:
```bash
npm install
npm start
```
<a id="new-project"></a>
### New project
### 1. Init new project
```bash
npm init
```
### 2. If you do not have access to the @tecnojest npm namespace skip this step and refer to Getting started to see how you can use the lib, else:
```bash
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. Create a file called .gitignore 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)
```bash
npm install --registry=https://registry.npmjs.org/
```
### 6. Add start and build scripts into the scripts 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 directory, implementing the basic methods of the API:
- `createElement(props)`: ...
- `render(component,el)`: ...
- `unmountComponentAtNode(node)`: ...
when developing a widget based on React the configuration would be:
### Index file
```jsx
import React from "react";
import ReactDOM from "react-dom";
import EmbeddableWidget from "@tecnojest/widget-base";
import Widget from "./components/widget";
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 `createElement(...)`, `render(...)`, and `unmountComponent(...)` - (the example above uses React and ReactDOM).
### React
If you wish to use React in your project, refer to [React Configuration](/getting-started/react-configuration)
### TypeScript
If you want to use TypeScript in your project, refer to [TypeScript Configuration](/getting-started/typescript-configuration)
### 8. Start the project
```
npm start
```
---
title: "React Configuration"
metaTitle: "Widgets - React Configuration"
---
## React in your project
Follow the [getting started](/getting-started) and [installation](/getting-started/0-installation) guides.
Then install the basic modules: `npm install react react-dom`
---
title: "TypeScript Configuration"
metaTitle: "Widgets - TypeScript Configuration"
---
## TypeScript in your project
Follow the [getting started](/getting-started) and [installation](/getting-started/0-installation) guides.
Then install the necessary modules:
```bash
npm install typescript ts-loader @babel/preset-env @babel/preset-typescript
```
Then create a `tsconfig.json` 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"]
}
```
---
title: "Configuration"
metaTitle: "Widgets - Configuration"
---
> ⚠ Remember that all of these have to be `static`
## static externalScripts
To import e.g. `jQuery` or any other external dependency which should be shared among your components, you can define the following static in the main Widget class:
```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'
}
];
```
## static options
> These will override `options` from `defaultProps`
Options that apply to all widgets in the same namespace, e.g.:
```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;
}
```
## Example - pass a callback through options
See how to use `options` in a different way - to react to a change that happened on the hosting platform. [Example](/widget-api/methods)
---
title: "Environmental Variables"
metaTitle: "Widgets - Environmental Variables"
---
### Usage
To use the environmental variables, create a `.env` file at the root of your project. Then fill it with the variables you wish to use e.g. like so:
```
WIDGET_TITLE=My widget
```
The following environmental variables are evaluated at runtime, overwrite them to change the desired behaviour:
### WIDGET_TITLE
The widget title displayed in the main page (default to project's title in package.json file)
### WIDGET_MAIN_CSS_CLASS
Add a class name to every element of the widget to increase specificity.
### WIDGET_HIDE_EXPLANATION
Should the widget title and a link to the latest widget's version script be shown on the page?
### WIDGET_ASSET_SERVER
Path to the server used for static asset distribution (public path). Defaults to "/".
### WIDGET_USE_CLEANSLATE
Should a CSS reset be applied?
### WIDGET_UNCOMPRESSED
Should a compressed version of assets be provided in the production mode?
### PORT
The port to be used for the development server. Defaults to 80.
---
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 u