Adding new components
You can add new components by adding a new folder in src/components
For example, src/components/MyComp
Then create there a new file named MyComp.js with the component code.
For example,
import React, { Component } from 'react';
import ContentWrapper from '../Layout/ContentWrapper';
class MyComp extends Component {
render() {
return (
<ContentWrapper>
{/* view content here */}
</ContentWrapper>
);
}
}
export default MyComp;
You can make use of stateless component too, as seen in other examples in the project.
Adding new routes
You will need now to make the component accessible to the application by adding a route that loads the component. To do that open Routes.js and import the component and add a new route entry like this
// To use static load of routes
import MyComp from './components/MyComp/MyComp';
...
<Route path="/mycomp" component={MyComp}/>
// To use lazy load of routes
const MyComp = lazy(() => import('./components/MyComp/MyComp'));
...
<Route path="/mycomp" mycomp={waitFor(MyComp)}/>
Check other routes in the project to see where the add the Route tag correctly
Finally, you need to add an entry to the sidebar in order to provide a link for the new route created.
To do that, add in src/Menu.js a new menu entry with the information for your menu.
Example
const Menu = [
/* heading elements */
{
// text to show
heading: 'Heading Text',
// translation key
translate: 'sidebar.heading.KEY'
},
/* menu items elements */
{
// text to show
name: 'Item Text',
// class name to show icon
icon: 'icon-class',
// route path (not used on items with submenu)
path: 'routepath',
// translation key
translate: 'sidebar.item.KEY',
// shows a Badge right next to the text
label: { value: 10, color: 'success' },
// list of submenu items
submenu: [{
... Same format as menu items
}
}
...
Vendor assets
Vendor assets can be installed using the Node Package Manager (npm). The following command shows how to install a package so it becomes part of the project
npm install package-name --save
If you don't add the --save flag, the package won't be saved as a dependecy in package.json and it will be only available in your local project.
Once the command ends, files will be available in the node_modules folder and ready to be imported into your application code.
If the package is used globally you can import files using the file Vendor.js
To use a package locally in your new component, you can import the files directly into the code in your component file.
Note about jQuery
If a component requires jQuery you must add the following:
import $ from 'jquery';
Layout classes
Layout can be changed via the following classed applied to the body tag:
| Class name |
Description |
.layout-fixed |
Makes navbars become fixed while the user can scroll only content |
.layout-boxed |
Limits the width of the main wrapper element |
.aside-collapsed |
Condenses the sidebar showing only icons |
.aside-collapsed-text |
Condenses the sidebar showing icons and Text |
.aside-toggle |
used internally for mobiles to hide the sidebar off screen |
.offsidebar-open |
used internally to display the offsidebar component (formally the right sidebar) |
Translation
The translation system uses the i18next module.
The file src/i18n.js contains the setup for the module and what it does is to load the translations files located under folder public/locales
This modules simplifies the translation system by loading translate references from a JSON file and replacing the content where the reference has been used.
Example
import { translate, Trans } from 'react-i18next';
<Trans i18nKey='dashboard.WELCOME'></Trans>
Where the i18key values corresponds to an entry in each json file according the current language selected.
Themes
All available theme source files (SCSS) can be found under folder src\styles\themes, which contains the following files according to each color combination
theme-a.scss
theme-b.scss
theme-c.scss
theme-d.scss
theme-e.scss
theme-f.scss
theme-g.scss
theme-h.scss
Those themes are managed by REDUX and a middleware (src/store/middlewares/themes.middleware.js) which loads the compiled version of each file (CSS) into the template.
Compiled version are placed in folder public/themes
Since it's not possible to load the content of a file in create-react-app, the use of themes has a different workflow to compile the files. When working with themes, use the following command:
npm run build-themes
This command will compile the files and will watch changes to recompile again.
Default Theme
To set a default theme open you need to set it in the initialState of themeReducer in file src/store\reducers/themes.reducers.js like this:
const initialState = {
path: 'themes/theme-e.css'
}
Note that selected themes are automatically saved to localStorage, if you set one as default, but there's another already saved, the saved path will be used instead.
You can enable the horizontal menu following the next instructions:
Open the file src/Routes.js and make sure to import the BaseHorizontal component at the top
import BaseHorizontal from './components/Layout/BaseHorizontal';
Then, replace the Base component with the BaseHorizontal component in the render method of the Route componen
The menu of the horizontal header is declared in file components/Layout/HeaderHorizontal.js and is limited to a few entries for demo purposes only.
RTL
RTL is based on rtlcss plugin using a custom loader that allows to change the application styles into an RTL representation.
To enable RTL open the file webpack.config.extend.js and uncommment the following snippet which enabled the rtlcss loader to process styles:
const isDev = webpackConfig.mode === 'development'
const sassRegex = /\.(scss|sass)$/.toString();
webpackConfig.module.rules[2].oneOf.some((rule, idx) => {
if (rule.test && rule.test.toString() === sassRegex) {
webpackConfig.module.rules[2].oneOf[idx][isDev ? 'use' : 'loader'].splice(
webpackConfig.module.rules[2].oneOf[idx][isDev ? 'use' : 'loader'].length - 1,
0,
rtlcssLoader)
return true;
}
});
Now you can run "npm run start" and the project should be served with their styles converted to RTL.
Heroku
It's necessary to make some changes to the project for this. First, create the following files used by Heroku to run a server and place this new files in the root folder of the project
Procfile
web: node server.js
server.js
var express = require('express');
var app = express();
var path = require('path');
app.use(express.static(path.resolve(__dirname, 'buid')));
app.get('*', (req, res) => {
res.sendFile(path.resolve(__dirname, 'buid', 'index.html'));
});
app.listen(process.env.PORT || 9090);
package.json
This file already exist, so only edit and change the script : "postinstall-heroku" to "postinstall", like this:
"scripts": {
...
"postinstall": "npm run build"
}
Finally, follow this steps to deploy this application to Heroku:
Login into Heroku with your credentials
heroku login
Init a new GIT repo with command
git init
Create your application with
heroku create app-name
Add project files
git add .
Commit project files
git commit -m "initial commit"
Run
heroku config:set NPM_CONFIG_PRODUCTION=false
Push project to Heroku with command:
git push heroku master
If everything went fine, open the app with command
heroku open
Seed Project
This project is an application skeleton. You can use it to quickly bootstrap your ReactJS webapp projects and dev environment for these projects. The seed app doesn't do much and has most of the feature removed so you can add them as per your needs just following the full-features version as example.
This project is provided in order to start with the template using a different approach. Usually, templates will come with all features working and you need to remove them one by one in the way you don't need them.
With the seed project you can start adding custom features and others from the full project to make grow your app.
Since the files and structure is the same for the full and seed versions, you can save time using comparison tools that allows to apply changes from full features project into the seed project.
jQuery and Wrapper script
Starting from version 4.1, this template doesn't need jQuery as a mandatory dependency for core files, this means it is only required when using jQuery based plugins for some features included.
Seed project versions no more include jQuery by default..
The wrapper.js (~ 7k minified) is a new script introduced to emulate some specific jQuery functions used in the template. This made possible to significantly cut the refactoring changes in the code, keeping it readable in a jQuery way and avoiding extra bytes, mainly when loops are repeatedly used to work with multiple elements.
Important The Wrapper script is NOT a replacement for jQuery. All methods were designed for an adequate and specific use and they don't do a deep validation on the arguments provided. It's suggested NOT to use this library extensively. Instead, use pure JS or you might even need jQuery.