LinkedPipes Applications Frontend

Welcome to LinkedPipes Applications frontend documentation. This documentation is intented for developers looking for references about frontend implementation of the platform as well as details on code structure, coding conventions, React component design patterns and overview of Components and Containers.

Installation

The following set of tutorials is intented for developers aiming to:

Work on contributing into our Frontend implementation of LinkedPipes Applications platform.
Work on their own forked version, extend or expand the frontend for their own use-cases.
Simply look for a reference documentation about certain components and their internal structure.

Prerequisites

Yarn 1.17.0
Node.js v10.15.x
Docker and Docker-compose # if you intent to run via docker compose along with other containers

Running locally

This assumes that you are currently inside the root folder of the whole application's repository and you have other components such as Discovery, ETL, Backend and etc. running locally in your system:

 
​
$ cd src/frontend
$ yarn install
$ yarn startLocalDevSockets
​

After that navigate to localhost:9001 to access the frontend served via webpack-dev-server.

Running locally without sockets

If you simply want to render the whole frontend without connecting to running instances of Backend, ETL, Discovery and databses, execute the following.

 
​
$ cd src/frontend
$ yarn install
$ yarn startLocalDev
​

Please, note that you won't be able to debug any functionality that requires other components of LinkedPipes Applications platform. This is mainly usefull for very specific cases when a UI of a component being developed needs to be debugged without wasting resources on other components running within docker-compose.

Running with docker-compose

This assumes that you are currently inside the root folder of the whole application's repository.

 
$ cd docker
$ docker-compose up --build --force-recreate
​

After that navigate to localhost:9001 to access the frontend, by default docker is being exposing it on port 9001 .

Running with docker-compose with persistent volumes

If you use the default docker-compose.yml file you will notice that it does not specify the volumes for PostgreSQL and Virtuoso containers. Therefore, your data won't be lost upon every docker-compose up session. If you want to have persistend docker-compose setup, follow these steps instead:

 
$ cd docker
$ docker-compose -f docker-compose-persistent.yml up --build  --force-recreate
​

This will create two folders named data and appdata inside the root folder of the repository. This is where your data is going to be stored for next docker-compose up sessions.

Alternatively inspect, the lpa-cli.sh script for a simplified commands if you prefer not to interact with docker-compose directly.

How we structure the project

The structure below explains the main project structure that you should get familiar with:

 
├── assets # Files, SVGs, PNGs all goes here and loaded by webpack file-loader
├── docs # Usually generated during runtime of `docz:build` command and contains a static `docz` website that hosts this documentation.
├── public # Generated by webpack when production is build, this hold the React Web App.
├── src # The root of the React codebase, the implementation of frontend is hosted here
    ├── components/ # Contains all minor UI components used withing LPApps frontend. For instance, buttons, toggles, appbars and etc.
    ├── containers/ # Contains assembled web pages. We call this folder containers because it mostly hosts platform specific set of React components representing individual web pages. We also tend to declare a separate component that manages all the states called `Container`, while **Component** serves as a stateless component only responsible for rendering and manipulating props.
    ├── constants # Contains various variables and constants used throughout frontend implementation.
    ├── ducks # A duck is a Redux pattern that structures the actions, reducers and selectors within the same folder or a file, allowing easier manipulation over Redux states. Therefore, folder contains main Redux related logic.
    ├── layouts # Contains several simple stateless components that wrap components that are passed to it. This allows easy customization of each individual webpage being routed from `AppRouter`. Things like, NavigationBar and SideBar are all assembled via layouts.
    ├── storage # Contains an independent set of components and folders with its own structure, responsible for everything related to storing, manipulating, publishing and removing Application configurations from SOLID servers.
    ├── utils # A set of various utility and helper functions and methods.
    ├── AppRouter.jsx # Main component that manages the 'react-router' 'BrowserRouter' and 'socket.io' connections.
    ├── store.jsx # Configures redux `store` for all `redux` states in the application.
    ├── withRoot.jsx # A custom component that wraps around root component and sets custom `Material-UI` themes.
    ├── wrapper.js # A custom wrapper component used for this `docz` documentation that simulates a root component plugged to `redux` and `react-router`.
    └── index.jsx
├── .babelrc
├── .eslintrc.json
├── .dockerignore
├── .gitignore
├── .prettierrc
├── Dockerfile # Dockerfile used for development build images
├── Dockerfile-prod # Dockerfile used for production build images
├── doczrc.js # Configuration for styling and plugins for this documentation website
├── Dockerfile # Dockerfile used for development build images
├── jsconfig.json # Specifies aliases to root folders for easier import statements using webpack
├── nginx.conf # Nginx configuration used for cases when frontend is a container inside docker-compose environment deployed on `applications.linkedpipes.com` server
├── webpack.config.js
└── yarn.lock

Designing the React component

Every component in LinkedPipes Applications frontend consist of two main folders. Components and Containers. Components usually contain elements that used in more than one webpage throughout the project, such as buttons, switches, image wrappers and etc. Containers represent complex react components that are basically rendering individual webpages or sub-elements of webpages that deal with complex user interaction use-cases.

Simple components

Whenever an individual component needs to be implemented and it will be used in multiple webpages throughout the project, it is being placed into Components folder.

There are two main types of components that can be placed into Components folder and have different design conventions.

Simple stateless component responsible for rendering
A complex component that needs to aggregate multiple sub-components, manage redux, manage internal states and etc.

Whenever a component needs to be implemented and it falls into first category, a corresponding .jsx file being created following certain naming convention that is not strict but highly recommended:

 
[(Optional) Type of a component, Button/Switch etc][Name of an abstraction that it represents]Component.jsx

Whenever a component needs to be implemented and it falls into second category, a corresponding pair of components is created. Those can be described as follows:

Stateless react component responsible for props and rendering sub-components with a following naming convention,

 
[(Optional) Type of a component, Button/Switch etc][Name of an abstraction that it represents]Component.jsx

A Pure React component that manages redux, material-ui styles and its internal states that are passed as props to the statless component. It usually has the following naming convention for a file,

 
[(Optional) Type of a component, Button/Switch etc][Name of an abstraction that it represents]Container.jsx

To recap this sub-section, whenever a component gets complex, we simply tend to split into separate component responsible for rendering and a separate component callsed container that manages the states of the statless component. This allows easier navigation within the project as well as faster code debugging.

For more examples simply explore the Components folder.

Complex components

Containers folder follows similar naming conventions to Components folder, the only difference is that it only hosts very specific and complex React components that usually represent the whole Webpage.

Whenever such component is being implemented, a corresponding set of files is created inside a sub-folder following this naming convention,

 
[Name of the feature representing the webpace]Page/

The components inside those folders all follow the same convention described in Components sub-section, meaning that it is always splitted into two .jsx files where one is managing state and the other manages rendering. The only difference is that the title of the file starts with the name of the feature that represents the webpage.

The diagram below recaps the described component design convention for splitting the single component into a pair of stateless and stateful components.

For more examples simply explore the Containers folder.

Coding conventions

Refer to the .eslintc.json configuration for all information about Javascript, ES6 and React coding conventions used within the project.

Material-UI

Frontend implementation heavily utilizes the Material-UI react framework. This allows faster and easier web development and component implementation. For more details about stock Material-UI component refer to their component examples and documentation.

What's next ?

If you want to explore the individual Components and Containers refer to the corresponding sections on this website. Each component details page allows you to browse through the main props being used as well as a live component example, that you can fork into an isolated CodeSandbox environment and play with different configurations.

If you want to learn more about more generic components of LinkedPipes Applications platform, such as Discovery, ETL or our Backend refer to a User oriented documentation and/or Backend documentation.