Getting Started

This is the documentation for "SPIN" v2: v2.react.spin.webkom.co

Intro

After placing the extracted files in a directory on your local system, you should execute npm install in the root of the project. Attention! - Please be sure the .npmrc file is present in the root of the directory. On Unix based systems, files which start with a dot are hidden by default, which sometimes can cause confusion.

Commands

npm start - start the development version with hot reloading enabled

npm start:prod - start the production version with SSR enabled

npm build:client - build the client application only (no SSR)

npm build:prod - build the application with SSR; this package should then be launched with node on the server

Project Structure

app/components/* - Place general React components here, reference them in the index.js file so they can be imported easilly later in the project.

app/layout/* - The main <Layout> component should be defined in the default.js file. Layout components such as Sidebars, Navbars should be placed in the ./components subdirectory.

app/routes/* - Route components should be defined in here. They should be attached to the Router via 3 functions which are placed at the bottom of the file. This will be described in a more detailed way in further sections.

app/styles - Non-modular SCSS should be placed here. There are already 4 files here - bootstrap.scss, main.scss, variables.scss, _font-awesome.scss. Those files import Bootstrap4 and all of the modifications for the dashboard layout, aswell as FontAwesome as a plugin.

app/colors.js - You can import this file to use the colors defined in the dashboard style.

app/index.html - The main html file which initializes the application.

app/server/* - Setup of the Express server which supports SSR in the application.

build/* - WebPack configuration files and other build tools.

dist/ - Production build files will be genereated here.

Adding Routes

1. Create a directory for the route (let's call it ExampleRoute) in app/routes/ExampleRoute.

2. Add 2 files ExampleRoute.js and index.js.

3. Inside of the ExampleRoute.js add the definition of the component. For example:

   ```jsx

   import React from 'react';

export const ExampleRoute = () => ( Hello World );

4. Re-export the component from `index.js` like so:
```jsx
import { ExampleRoute} from './ExampleRoute';

// NOTE: The component should be exported as a `default` here.
export default ExampleRoute;

1. Now you need to attach the route to ReactRouter:

2. If you need the route to be static which means that it will be loaded at the start of the application just import the route and add it to the body of getRoutes function like so:

   /// (...)
   import ExampleRoute from './ExampleRoute`;
   /// (...)
   const getRoutes = () => {
     return (
         <Switch>
             { /* (...) */ }
             <Route path="/example-route">
                 <ExampleRoute/>
             </Route>
             { /* (...) */ }
         </Switch>
     );
   }

3. You can also make the route asynchronous, then it will be loaded only when the user navigates to it. This technique reduces the initial load time, as the browser doesn't need to load the whole application on start. You can add an async route as follows:

   /// (...)
   import { UniversalComponent } from './universalComponent';
   /// (...)
   const getRoutes = () => {
     return (
         <Switch>
             { /* (...) */ }
             <Route path="/example-route">
                 { /* page prop defines which subdirectory should be asynchronously loaded */ }
                 <UniversalComponent page="ExampleRoute"/>
             </Route>
             { /* (...) */ }
         </Switch>
     );
   }

4. Last step is to add the Sidebar entry. Open the app/layout/components/SidebarMiddleNav.js file where all sidebar route entries should be added. Example:

   export const SidebarMiddleNav = () => (
    <SidebarMenu>
        { /* (...) */ }
        <SidebarMenu.Item
            icon={<i className="fa fa-fw fa-home"></i>}
            title="Example Route"
            to='/example-route'
        />
        { /* (...) */ }
    </SidebarMenu>
   );

5. Now you should be able to navigate to the newly created route through the sidebar.

Layout

You can change the general layout, as well as add specific Navbars and Sidebars for different routes.

General Layout structure

Whole page layout is composed of the <Layout> component and its subcomponents. This composition should be placed in app/layout/default.js In more details the usage of this component is described here.

Sidebar Layout

The <Sidebar> component should be build from <Sidebar.Section> subcomponents. All of the details are described here.

Connecting different Sidebars or Navbars to specific routes.

Let's check out how to add an alternative Sidebar to our ExampleRoute we created earlier.

1. Let's add the additional Sidebar to app/layout/components/ExampleSidebar.js like this:

   ```jsx

   import React from 'react';

   import { Sidebar } from './../../components';

export const ExampleSidebar = () => ( { / Sections compositions for this sidebar /} { / (...) /} );

2. Now we can attach the Sidebar to the route. To do this you need to open `app/routes/index.js`, import the newly created Sidebar and add it to the body of `getSidebars` function:
```jsx
import { ExampleSidebar} from './../layout/components/ExampleSidebar';
// (...)
const getSidebars = () => (
    <Switch>
        <Route
            path="/example-route"
            component={ ExampleSidebar}
        />

        { /* Default Sidebar: */}
        <Route
            component={ DefaultSidebar }
        />
    </Switch>
);

1. Now the new Sidebar should be loaded when navigated to /example-route.

2. Alternative Navbars should be added in the same way. Just instead adding them to getSidebars, use the getNavbars function to attach them.

3. TIP: Sidebar parts should be defined as reusable components, so you can keep the code DRY between multiple layout parts.

Styling

You can create modular and non-modular css files. All of the files placed in the app/styles directory, won't be transformed to modules. On the other hand if you place the style file in the component/route directory - it will become a CSS Module.

By importing app/styles/variables you are able to import all of the Bootstrap variabels and colors.

If you need the colors in a JavaScript form, you need to import the app/colors.js. This file contains an object with all of the colors from the SCSS files described by the object keys. Example: colors['100'] - will return you a gray-100 color, and colors['primary'] will contain the "primary" color.