From 8aa49fe8ae9134414028a28d56c08c2e37db9f33 Mon Sep 17 00:00:00 2001
From: Tomasz O <tomasz.owczarczyk@gmail.com>
Date: Wed, 14 Aug 2019 23:45:02 +0200
Subject: [PATCH] Update README.md

---
 README.md | 321 +++++++++++++++++++++++++-----------------------------
 1 file changed, 147 insertions(+), 174 deletions(-)

diff --git a/README.md b/README.md
index 40b790e..03693d2 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,10 @@
-# Airframe
+# Airframe React
 
 High Quality **Dashboard / Admin / Analytics template** that works great on any smartphone, tablet or desktop. Available as **Open Source as MIT license.**
 
 - [View Demo](http://dashboards.webkom.co/jquery/airframe) 
-- [React Version](http://dashboards.webkom.co/react/airframe/)
+- [View Demo](http://dashboards.webkom.co/react/airframe/)
+- [jQuery Version](http://dashboards.webkom.co/jquery/airframe) 
 - [Next Version](http://airframe.nextjs.webkom.co) - _Documentation in preparation_ 
 - [Angular Version](http://dashboards.webkom.co/angular/airframe) - _Documentation in preparation_
 - [Vue Version](http://dashboards.webkom.co/vue/airframe) - _Documentation in preparation_
@@ -16,7 +17,7 @@ High Quality **Dashboard / Admin / Analytics template** that works great on any
 
 **Airframe Dashboard** with a minimalist design and innovative Light UI will let you build an amazing and powerful application with great UI. Perfectly designed for large scale applications, with detailed step by step documentation.
 
-This **Airframe version** is a standard HTML template using **jQuery** and **Bootstrap 4**. Most of the layouting and components you are able to find in the [Official Bootstrap Documentation](http://getbootstrap.com).
+This **Airframe** project is a typical Webpack based React app, [React Router](https://reacttraining.com/react-router/web/guides/quick-start) also included together with customised [Reacstrap](https://reactstrap.github.io). This project has all of it's few dependencies up to date and it will be updated on a regular basis. This project doesn't support SSR. If you need it - use the [NextJs](https://github.com/zeit/next.js/) based version.
 
 # Features
 
@@ -40,189 +41,161 @@ This **Airframe version** is a standard HTML template using **jQuery** and **Boo
 
 # Installation
 
-## Additional Components
-This Dashboard has some additional classes and JS components to achieve the final effect.
+## Initial Configuration:
+You need to have [NodeJs](https://nodejs.org/en/) (>= 10.0.0) installed on your local machine, before attempting to run a dev environment.
 
-### Layout
-This component will keep the whole layout in place it should look like this.
-```html
-<div class="layout layout--theme--light--primary">
-    <div class="layout__sidebar">
-    <!-- Optional element: Airframe Sidebar should be placed here -->
-    </div>
-    <div class="layout__wrap">
-        <div class="layout__navbar">
-        <!-- Bootstrap Navbars should be placed here, they can be stacked on on another -->
-        </div>
-        <div class="container>
-        <!-- Page Content should be placed here
-        </div>
-    </div>
-</div>
+1. Extract contents of the package to your local machine.
+2. Using the Terminal navigate to the extracted contents.
+3. Run `npm install`.
+
+Make sure you have a file called `.npmrc` in the extracted directory. Those files are typically hidden in Unix based systems.
+
+### Development
+To start the development environment type `npm start` in the console. This will start a development server with hot reloading enabled.
+
+### Production
+To create a production build type `npm run build:prod`. After the process is complete you can copy the output from the `/dist/` directory. The output files are minified and ready to be used in a production environment.
+
+### Build Customization
+You can customize the build to suit your specific needs by adjusting the [Webpack](https://webpack.js.org) configuration files. Those files can be found in the `/build` directory. For more details checkout the documentation of WebPack.
+
+## Project Details
+Some points of interest about the project project structure:
+
+* `app/components` - custom React components should go here
+* `app/styles` - styles added here won't be treated as CSS Modules, so any global classes or library styles should go here
+* `app/layout` - the `AppLayout` component can be found here which hosts page contents within itself; additional sidebars and navbars should be placed in `./components/` subdir.
+* `app/colors.js` - exports an object with all of the defined colors by the Dashboard. Useful for styling JS based components - for example charts.
+* `app/routes` - PageComponents should be defined here, and imported via `index.js`. More details on that later.
+
+### Defining Routes
+Route components should be placed in separate directories inside the `/routes/` directory. Next you should open `/routes/index.js` file and attach the component. You can do this in two diffrent ways:
+
+#### Static Imports
+Pages imported statically will be loaded eagerly on PageLoad with all of the other content. There will be no additional loads when navigating to such pages **BUT** the initial app load time will also be longer. To add a statically imported page it should be done like this:
+
+```jsx
+// Import the default component
+import SomePage from './SomePage';
+// ...
+export const RoutedContent = () => {
+    return (
+        <Switch>
+            { /* ... */ }
+            { /* Define the route for a specific path */ }
+            <Route path="/some-page" exact component={SomePage} />
+            { /* ... */ }
+        </Switch>
+    );
+}
 ```
 
-The layout component also supports **theming** you can add a specific class related to a particular theme which will add a color scheme to the whole layout (mainly sidebar and targeted navbars). Classes which are providing this feature have this format: `layout--theme--<theme style>--<theme color>`. Here are the possible values for `theme-style` and `theme-color`:
+#### Dynamic Imports
+Dynamically imported pages will only be loaded when they are needed. This will decrease the size of the initial page load and make the App load faster. You can use `React.Suspense` to achieve this. Example:
+```jsx
+// Create a Lazy Loaded Page Component Import
+const SomeAsyncPage = React.lazy(() => import('./SomeAsyncPage'));
+// ...
+export const RoutedContent = () => {
+    return (
+        <Switch>
+            { /* ... */ }
+            { /*
+                Define the route and wrap the component in a React.Suspense loader.
+                The fallback prop might contain a component which will be displayed
+                when the page is loading.
+            */ }
+            <Route path="/some-async-page">
+                <React.Suspense fallback={ <PageLoader /> }>
+                    <SomeAsyncPage />
+                </React.Suspense>
+            </Route>
+        </Switch>
+    );
+}
+``` 
+#### Route specific Navbars and Sidebars
+Sometimes you might want to display additional content in the Navbar or the Sidebar. To do this you should define a customized Navbar/Sidebar component and attach it to a particular route. Example:
 
-**theme-style**
-* `light`
-* `dark`
-* `color`
+```jsx
+import { SidebarAlternative } from './../layout/SidebarAlternative';
+import { NavbarAlternative } from './../layout/NavbarAlternative';
+// ...
+export const RoutedNavbars  = () => (
+    <Switch>
+        { /* Other Navbars: */}
+        <Route
+            component={ NavbarAlternative }
+            path="/some-custom-navbar-route"
+        />
+        { /* Default Navbar: */}
+        <Route
+            component={ DefaultNavbar }
+        />
+    </Switch>  
+);
 
-**theme-color**
-* `primary`
-* `success`
-* `info`
-* `warning`
-* `danger`
-* `indigo`
-* `purple`
-* `pink`
-* `yellow`
-
-### Sidebar
-Sidebar can contain a navigation menu and addtional information. Everything is organized in sections. It can be in a Slim state on larger displays, and collapsible on small screens. Example Sidebar:
-```html
-<div class="sidebar sidebar--animations--enabled">
-    <!-- This element will be displayed only on mobile and will collapse the sidebar when closed -->
-    <div class="sidebar__close">
-        <a href="javascript:;" class="action--sidebar-trigger">
-            <i class="fa fa-times-circle fa-fw"></i>
-        </a>
-    </div>
-
-    <!-- Sidebar contents are organized in sidebar__section elements -->
-    <div class="sidebar__section sidebar__hide-slim">
-        <!-- Some non-scrollable content, visible only on non slim sidebar -->
-    </div>
-
-    <!-- This wrap will allow scrolling all of the sections inside on Mobile Screens -->
-    <div class="sidebar__mobile-fluid">
-        <!--
-            A fluid section will fill all of the available height in the sidebar,
-            cover section will fill all of the available space inside. This combination
-            is mainly designed to place SidebarMenu component inside.
-        -->
-        <div class="sidebar__section sidebar__section--fluid sidebar__section--cover">
-            <!-- Sidebar Menu should be placed here -->
-        </div>
-
-        <!--
-            This section will be at the bottom of the sidebar because
-            of the fluid section defined above
-        --> 
-        <div class="sidebar__section">
-            <!-- Sidebar Bottom content -->
-        </div>
-    </div>
-</div>
+export const RoutedSidebars = () => (
+    <Switch>
+        { /* Other Sidebars: */}
+        <Route
+            component={ SidebarAlternative }
+            path="/some-custom-sidebar-route"
+        />
+        { /* Default Sidebar: */}
+        <Route
+            component={ DefaultSidebar }
+        />
+    </Switch>
+);
 ```
 
-**Notable classes**
-* `sidebar--animations--enabled` - will make the sidebar animated in most of the interactions
-* `sidebar--slim` - will allow the sidebar to be slim when collapsed on desktop
-* `sidebar--collapse` - will hide the sidebar, or make it slim if defined so
-* `sidebar__mobile-fluid` - all of the contents of that element will be scrollable on mobile sidebar
-* `sidebar__section` - building block of the sidebar
-* `sidebar__section--fluid` - section which will fill all available height of the sidebar
-* `sidebar__section--cover` - removes the section padding
-* `sidebar__hide-slim` - __(helper)__ hides an element when the sidebar goes into slim mode
-* `sidebar__show-slim` - __(helper)__ shows an element when the sidebar goes into slim mode
+## Theming
+You can set the color scheme for the sidebar and navbar by providing `initialStyle` and `initialColor` to the `<ThemeProvider>` component which should be wrapping the `<Layout>` component.
 
-### Sidebar Menu
-Provides navigation for the sidebar. Allows for multilevel nesting, may be in a slim form with dropdowns. Has to be placed in a fluid, covered section. Example Sidebar Menu:
-```html
-<ul class="sidebar-menu">
-    <!-- A single link without any nesting -->
-    <li class="sidebar-menu__entry">
-        <!-- Link to the target page -->
-        <a href="/some-page" class="sidebar-menu__entry__link">
-            <!-- Icon representing the link -->
-            <i class="fa fa-fw fa-th sidebar-menu__entry__icon"></i>
-            <!-- Content of the link -->
-            <span>Some Page</span>
-        </a>
-    </li>
+Possible `initialStyle` values:
+* light
+* dark
+* color
 
-    <!-- Container which will have nested entries inside -->
-    <li class="sidebar-menu__entry sidebar-menu__entry--nested">
-        <!-- Trigger which will expand the child entries on clicking -->
-        <a href="javascript:;" class="sidebar-menu__entry__link">
-            <!-- Icon representing the trigger -->
-            <i class="fa fa-fw fa-home sidebar-menu__entry__icon"></i>
-            <!-- Content of the trigger -->
-            <span>Dashboards</span>
-        </a>
+Possible `initialColor` values:
+* primary
+* success
+* info
+* warning
+* danger
+* indigo
+* purple
+* pink
+* yellow
+
+### Programatic Theme Changing
+You can change the color scheme on runtime by using the `ThemeConsumer` from the components. Example:
+```jsx
+// ...
+import { ThemeContext } from './../components';
+// ...
+const ThemeSwitcher = () => (
+    <ThemeConsumer>
+        ({ onChangeTheme }) => (
+            <React.Fragment>
+                <Button onClick={() => onThemeChange({ style: 'light' })}>
+                    Switch to Light
+                </Button>
+                <Button onClick={() => onThemeChange({ style: 'dark' })}>
+                    Switch to Dark
+                </Button>
+            </React.Fragment>
+        )
+    </ThemeConsumer>
+);
 
-        <!-- Contains the child entries -->
-        <ul class="sidebar-submenu">
-            <!-- First Child Entry -->
-            <li class="sidebar-submenu__entry">
-                <a class="sidebar-submenu__entry__link" href="/nested-page-1">
-                    <span>First Nested Page</span>
-                </a>
-            </li>
-            <!-- Second Child Entry -->
-            <li class="sidebar-submenu__entry">
-                <a class="sidebar-submenu__entry__link" href="/nested-page-2">
-                    <span>Second Nested Page</span>
-                </a>
-            </li>
-        </ul>
-    </li>
-</ul>
 ```
-* `sidebar-menu` - parent of the menu
-* `sidebar-menu--slim` - should be present when the sidebar is in slim collapsed mode
-* `sidebar-menu__entry` - contains the 0 level link
-* `sidebar-menu__entry--nested` - contains the 0 level nested links
-* `sidebar-menu__entry--no-caret` - removes the caret which is added by nested entries
-* `sidebar-menu__link` - level 0 link
-* `sidebar-menu__entry__icon` - icon representing a particular entry
-* `sidebar-submenu` - contains the nested entries
-* `sidebar-submenu__entry` - contains the nth level link
-* `sidebar-submenu__entry--nested` - contains the nth level nested links
-* `sidebar-submenu__entry__link` - nth level link
 
-### Navbars
-Navbars are essentially Bootstraps navbars, but there are some additional classes which extend their behavior.
-* `navbar-themed` - will receive the theme colors from the layout theme class
-* `navbar-shadow` - will add a shadow at the bottom of the navbar
-* `navbar-multi-collapse` - allows to make the navbar collapse, not collapse all of the items, the underling `container` should also have `navbar-collapse-wrap` class
-
-### Additional Helpers
-* `sidebar__brand` - will add a theme color to a brand text
-* `sidebar__link` - should be used on additional links in sidebar, will add proper themed colors
-* `sidebar__link--muted` - muted modifier for the sidebar link
-* `text-theme` - will set the text color to the current theme
-* `bg-theme` - will set the background color to the current theme
-
-## JavaScript
-You can add predefined script which will handle all of the sidebar behaviour: sidebar menu, sidebar collapsing, animations etc.
-
-```html
-<head>
-    <!-- Those scripts should be loaded with a priority in head -->
-    <script src="/assets/js/side-menu.js"></script>
-    <script src="/assets/js/layout.js"></script>
-</head>
-<body>
-    <!-- (...) -->
-    <div class="layout__sidebar">
-        <!-- Sidebar Definition -->
-        <!-- (...) -->
-
-        <script>
-            Dashboard.Sidebar.init($, window);
-        </script>
-    </div>
-    <!-- (...) -->
-    <script>
-        Dashboard.Layout.init($, window, document);
-    </script>
-    <!-- Will provide animations -->
-    <script defer src="/assets/js/animate.js"></script>
-</body>
-```
+Options provided by the `ThemeConsumer`:
+* **style** - current theme style
+* **color** - current theme color
+* **onChangeTheme({ style?, color? })** - allows to change the theme
 
 # Credits
 Used plugins in this dashboard: