Blog/Airframe-React
Template
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Update README.md

Browse Source
This commit is contained in:
Tomasz O
2019-08-14 23:45:02 +02:00
committed by GitHub
parent 15ed3615cb
commit 8aa49fe8ae
1 changed files with 147 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

321
README.md
View File

@@ -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: