ModularAdmin is an open source dashboard theme built in a modular way. That makes it extremely easy to scale, modify and maintain.
We're working hard on version 2, which is a complete rewrite.
V2 demo | V2 code
Please consider supporting us to make this happen!
Note: If you don't want to re-build the project, you may just clone this branch directly
https://github.com/modularcode/modular-admin-html/tree/gh-pages
1. Download ZIP or Git Clone
git clone https://github.com/modularcode/modular-admin-html.git
The cloned/downloaded repository doesn't contain prebuilt version of the project and you need to build it. You need to have NodeJs with npm. You also need to have Bower installed globally.
Install npm dependencies
npm install
Install bower dependencies
bower install
Build the project and start local web server
npm start
Open the project http://localhost:4000.
Warning! all changes made in dist/
folder would be overwriten on application build.
You can also run the project in docker thanks to @japrogramer
βββ bower_components/ # vendor libraries installed by bower
βββ build/ # app build tasks and tools
βββ node_modules/ # node dependencies
βββ dist/ # compiled result
βββ src/ # source files
βββ bower.json # bower configuration file
βββ package.json # npm configuration file
This folder contains our application source files. The folder structure reflects the app component structure.
Each non-underscored folder represents a single component module. Modules can be nested inside each other.
There are also special folders which start with an underscore.
For example _common/
folder contains common components that are used by other components at the same level.
This file structuring makes our app file organization very semantic and scalable. Also It's very easy to work on separate components even if you're developing large-scale applications.
βββ _assets/ # application assets
βββ _common/ # common components
| βββ helpers/ # handlebars helpers
| βββ styles/ # application common styles
βββ _themes/ # different theme versions
βββ app/ # app module (dashboard view)
β βββ _common/ # app common components
β | βββ editor/ # wysiwyg editor files
β | βββ footer/ # footer files
β | βββ header/ # header files
β | βββ modals/ # common modal dialogs (confirm, image library, etc)
β | βββ sidebar/ # sidebar files
β βββ {different modules}
β βββ app-layout.hbs # app view layout
β βββ app.scss # main app view styles
βββ auth/ # auth module (login/signup/recover)
β βββ {different modules}
β βββ auth-layout.hbs # auth view layout
β βββ auth.scss # main auth view styles
βββ _context.js # main handlebars variables
βββ _main.scss # main styles
βββ _variables.scss # variables
βββ config.js # javascript configs
βββ main.js # main script file
This folder contains files related to our application compilation. That can be styles preprocessing (LESS,SASS,PostCSS) and template engine compilation, script file concatenation and minification and other related tasks.
βββ paths/ # application file paths
| βββ app.js # application file paths
| βββ vendor.js # 3-rd party plugins paths
βββ tasks/ # tasks folder
| βββ {different tasks} # each file represents a single build task
βββ utils/ # some utils
βββ config.js # build configs
βββ gulpfile.js # main build file for gulp build system
Compiled state of our app with processed styles, templates, scripts and assets.
Warning! Never work inside this folder, because your changes would be overwritten on every build
Our app consists of different file types.
We use SASS as CSS preprocessor language.
Main variables are defined in src/_variables.scss
folder.
For making life easier we broke down styles into components, and on build we're just merging all .scss
files together and processing it to dist/css/app.css
file. Style files are merged in the following order
{variables.scss}
{bootstrap variables}
{bootstrap mixins}
{rest style files}
The remaining style files are merged in the alphabetical order.
There are also different theme variations located in src/_themes/ folder
, where you can change the main variables to get different themes. There are a few predefined themes built in. You can add new themes by adding a new file in src/_themes/
folder. The file name must end with -theme.scss
.
We separate application's scripts across its components. For simplicity we use ES5 in this version, and just wrap each component's script in jQuery $(function() { })
. JS configurations are defined in src/config.js
file. On build, application script files are merged together and copied to dist/js/app.js
folder. The script files are merged in the following order.
{config.js}
{all .js files except main.js}
{main.js}
Templates are pieces of HTML files written in template engine language. We use Handlebars, which allows to have conditions in HTML, reuse partials in different pages (e.g. sidebars, footers), use loops, layouts etc.
Templates themselves are just parts of the markup, and aren't compiled as separate files. What we really want in the final output is a .html
page in the dist/
folder. There are special handlebar templates for it, their filenames ending with -page.hbs
. Each {pagename}-page.hbs
file would be compiled to dist/{pagename}.html
page with a flatened file structure.
Pages can consist of different templates (partials) which can be included thanks to handlebars partial including feature. Also each page has its context, which is a data passed into the template on rendering. That data is used in template expressions and variables. page contexts can be defined in two ways:
YAML headers (example)
---
foo: bar
list:
- One
- Two
- Three
---
and _context.js files.
module.exports = {
foo: 'bar',
foo2: function() {
// do some magic, return some string
},
list: [
'One', 'Two', 'Three'
]
}
The final result of page context is a combination of both ways. Moreover, different depth level _context.js files are extending each other and then are extended with YAML headers data. For simplicity we use only YAML headers.
If different pages have a lot of common components like sidebars, headers, footers, then it's a good idea to define a layout for those common pages, and define in page files only the content which is unique.
Layout is a page content wrapper. If the page has a layout in output we'll get page's content inserted into the layout. Layouts should have {{{body}}}
handlebars tag, which is entry point for the page content. (example)
To define a page layout you need to specify page file context's layout
variable. It can be done both with a YAML header or a _context.js file. (example).
Layouts can also have contexts and parent layouts.
{_main-layout.hbs} # main layout with doctype, head, scripts declaration
{app/app-layout.hbs} # dashboard layout with sidebar, header and footer
{app/forms/forms-page.hbs} # any dashboard page
If you need more advanced layouting with multiple content blocks at the same time you can use handlebar-layouts helper approach, which is also available out of the box.
In addition to application files, there are also third party plugin files (e.g. Bootstrap). They are managed by using Bower. Usually vendor libraries consist from scripts, styles and assets (images, fonts). The build system will concatenate and copy all the script and style files accordingly to dist/js/vendor.js
and dist/css/vendor.css
. It also will copy all assets to the dist/assets/
folder.
You can run the project in docker. To build the container, you need to install docker and docker-compose than launch the docker daemon. After launching the daemon run the following commands from the project folder:
Build the image
docker-compose build
Launch the container
docker-compose up
Be part of our team! Feel free to open new issues/pull-requests.
You can get in touch with us in gitter chat or in the ModularCode Facebook Group. Feel free to contact us with any questions, sugestions, remarks and potential feature requests that you might have.
- Gevorg Harutyunyan | LinkedIn | Facebook | Twitter | gevharut[at]gmail.com
- Aram Manukyan | LinkedIn
- David Tigranyan | LinkedIn
Support us with a monthly donation and help us continue our activities. [Become a backer]
Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]