Hello and welcome to the Materialism documentation.
Get a overview of the theme and how to set things up as we intended it for you.
For fast and streamlined development we have set up this project using Node, Grunt and Bower.
Please install these requirements to enjoy the full potential of this theme.
First make sure you have Node.js installed.
When you have successfuly installed Node you should see something similar when running the commands:
$ node --version
v5.1.1
$ npm --version
3.5.1
Now that we have Node and NPM we can install Grunt and Bower which will help us compile (CSS), uglify (JS) and do all sort of usefull tasks.
$ npm install -g grunt-cli bower
With Bower you download the required assets (Angular, Bootstrap etc) and with NPM you download the Grunt dependencies (SASS).
$ cd /to/path/where Gruntfile.js and bower.json are located
$ npm install
$ bower install
Sometimes when running Bower a version mismatch can occur between certain assets. When this happens for Angular always choose the version used by Materialism.
Unable to find a suitable version for angular, please choose one:
1) angular#~1.3 which resolved to 1.3.20 and is required by c3-angular#0.7.1
2) angular#1.4.8 which resolved to 1.4.8 and is required by angular-animate#1.4.8
3) angular#^1.2 which resolved to 1.4.8 and is required by angular-simple-logger#0.0.4
4) angular#1.2 - 1.4 which resolved to 1.4.8 and is required by angular-google-maps#2.2.1
Prefix the choice with ! to persist it to bower.json
? Answer 2
In this case we awnser with: 2
From here on out when we mention to run a command, do so from the project root (Where Gruntfile.js is located).
To view the theme start a local webserver with grunt using:
$ grunt
This will start a local webserver on port 9000. Open one of the following urls in your browser:
The project is divided into two parts dist and source.
The dist is the compiled version of the source.
When you are looking for examples take a look at the dist version.
You can use the grunt tasks to develop your own application. To make changes and automatically compile your CSS run:
$ grunt
When you are done for a distribution of your own version run:
$ grunt dist
This will copy all the required assets to dist/ and compile the CSS and JS.
In the final step everything will be compressed into a zip file.
When you start your project you may want to choose which assets are compiled into your project.
We have chosen to use grunt-usemin for this task. When you have a look at index.dev.html you will see something like this:
<!-- build:js assets/js/vendors.min.js -->
<script charset="utf-8" src="/bower_components/angular/angular.js"></script>
<!-- endbuild -->
This will create the file dist/assets/js/vendors.min.js minified, uglified and hashed when running the grunt dist task.
We provide four of these files for you: vendors.min.js, app.min.js, vendors.min.css and styles.min.css.
And you are free to modify them to your pleasing.
You are also free to name the files whatever you want. Usemin will automatically pick this up and use that filename.
For this theme we use a SCSS index file which gets recompiled every time you make a change to one of the SCSS files.
But only while you are running grunt, because this will watch for changes.
You can find this file in app/assets/css/scss/materialism.scss
If you go to the directory app/assets/tpl you'll find the html files that are used in this theme.
The templates are separated by folders which corresponds to the navigational namings.
The main layout file is located in app/index.dev.html This file is for development purposes and
will be used when the grunt tasks minimize your application for production and send to the dist file.
Looking at app/assets/tpl you'll need to change partials/sidebar for navigational items.
The following maps are shared: directives, partials
Don't discard these if you are not sure starting your own application.
SASS offers the most functionality in regards to css frameworks and that's why we've chosen to work with SASS.
Although there are still some static CSS files used in the theme, most of it is written in SASS.
Looking at app/assets/css/ you'll see a sass folder and some css files.
The css files are static files used from plugins that didn't supply SASS files or are custom.
See directory structure for information on the files.
materialism.scss is the base for your application css.
All files are included here and you'll probably need to customize this file for your specific wishes.
The pages folder is something that is used for showcasing the theme and is a good base for your own application pages.
We like writing clean CSS and clean is reusing code.
The helpers.css file is a swiss army knife for quickly prototyping your application.
Take a look at this file because it's static, there are a lot of handy classes that extend bootstrap functionality.
For instance m-r-5 is margin-top: 5px; or p-t-20 is padding-top: 20px;
Add these classes to any element like:<div class="m-t-30 m-b-5">My awesomely spaced content</div>
If you look at the colors page, you can see a rich variety of colors and how to use them.
Text colors are automatically calculated based on the intensity of the background color but can also be set manually.
Here a quick example:<div class="red lighten-1">my very own red box with white text</div>
When you are experiencing errors with npm or bower most of these problems are solved by doing a clean install.
Remove the following directories bower_components and node_modules and run
$ cd /to/path/where Gruntfile.js and bower.json are located
$ npm install
$ bower install
Sometimes you'll need to remove your cached versions of npm also by removing the .npm directory in your home folder.
Grunt uses libraries maintained by other developers which tend to change paths.
When grunt gives you an error about not finding a file inside the bower_components folder you should check
if the requested file is present and if not, it is probably moved so you need to change the path in materialism.scss
For this theme we use a set of existing tools with each offering their own extensive documentation.
Having good knowledge in these packages will greatly help you develop with this theme.
Bootstrap is the base for this theme.
Also, we use the SASS version of bootstrap.
We have also added Angular Strap to provide Angular with directives for Bootstrap.
SASS is a CSS extension which lets you write clean and modular CSS.
Angular is the JS framework.
Node.js is what we use to compile SASS into CSS or run a local webserver.
When you look at package.json you'll see which Node packages we are using for this theme.
Grunt is what allows us to create automated tasks which helps you with development.
Have a look at the Gruntfile.js to see which tasks we have defined for you.
Bower is the package manager we use so you can easily update your dependencies.
See bower.json for which dependencies we have included.
Charting is done with C3 in combination with C3 Angular.
Angular animate
Angular auto validate
Angular cookies
Angular elastic – Auto grow textarea’s
Angular file upload
Angular google maps – Google maps directives
Angular loading bar
Angular local storage
Angular motion – Fancy CSS3 animations for Angular
Angular table – Table directive
Angular route
Angular sanitize
Angular smooth scroll
Angular strap – Bootstrap directives
Angular ui-select – Select2 directives
CSS animations – SCSS version of animate.css
Bootstrap additions
Bootstrap – SASS version
jVectorMap
C3 Angular Directive – C3 directives
Fontawesome
Hammer.js – Touch gestures
jQuery
jQuery Hammer.js
Lodash
Material design iconic font – Material design icons
noUiSlider – Range slider
Roboto font
SHA-1 – SHA-1 hash generator
textAngular – Lightweight Angular.js Text-Editor
Velocity.js – Accelerated JavaScript animation
Waypoints – Execute a function when you scroll to an element
Weather icons
Pic Jumbo – Free stock photos
Ballicons – 30 pixel-perfect colorful icons