ID-SK frontend toolkit¶ ↑
A collection of Sass and JavaScript files for using as part of your application's frontend.
This project is not tied to a specific language and is designed to be used as a dependency in as many different languages as needed.
There's a Gemfile
and a package.json
in this directory, but they are only for running tests and are not an indication that this project prefers Ruby or Node.js.
Installing¶ ↑
Ruby on Rails¶ ↑
We recommend you use the idsk_frontend_toolkit_gem and follow the installation instructions.
Node.js¶ ↑
idsk_frontend_toolkit_npm is an NPM package that can be installed or included in your package.json.
If you are using a build tool that depends on Libsass then you may need to upgrade to a more recent version to use the grid helpers. Minimal compatible versions include node-sass
1.0.0, grunt-sass
0.16.0, gulp-sass
1.2.0 and libsass
3.0.0.
Django¶ ↑
Requirement: NodeJS installed. This gives you {Node Package Manager}[https://docs.npmjs.com/getting-started/installing-node](NPM) which is required to install npm packages.
The easiest way to integrate it would be to create a package.json
file in your application with npm init
You then install the toolkit with npm install --save idsk_frontend_toolkit
. If you need javascript files, they will live in (node_modules/idsk_frontend_toolkit/javascripts
). If you need stylesheets they will live in (node_modules/idsk_frontend_toolkit/stylesheets
).
With Django you can use github.com/jrief/django-sass-processor to compile Sass files.
Note: if you need complete styles you might want to install idsk-elements-sass package that also installs toolkit
Other projects¶ ↑
Using the tagged versions¶ ↑
Each version of the toolkit is tagged with the version number in this format:
v*version number*
, for example v4.1.1
for version 4.1.1.
If your dependency management tool allows the use of Git repositories as dependencies, you can point to a version by using its tag.
For example, if you are using bower, you can add the toolkit to your bower.json
like so:
"idsk_frontend_toolkit": "git://github.com/id-sk/idsk_frontend_toolkit#v4.1.1"
(assuming you want version 4.1.1)
Using git submodules¶ ↑
You can include the toolkit as a git submodule.
To add the submodule to your project run the following command substituting the path to a subdirectory in your project's assets directory:
$ git submodule add https://github.com/id-sk/idsk_frontend_toolkit.git ./path/to/assets/idsk_frontend_toolkit
We recommend you use https
rather than ssh
for submodules as they don't require key exchanges when deploying to remote servers.
If you clone a project with the toolkit submodule installed you will need to initialise the submodule with the following command:
$ git submodule init
To update the toolkit to the latest version you can use:
$ git submodule update
Running tests¶ ↑
Tests for this project use Jasmine for the JavaScript and Ruby's scss
and scss-lint
to check the stylesheets.
The requirements are Node.js 0.8 or higher and PhantomJS, and Ruby:
bundle install npm install npm test
Standard JavaScript¶ ↑
idsk_frontend_toolkit
uses standardjs, an opinionated JavaScript linter. All JavaScript files follow its conventions. Read more
Using the local test runner¶ ↑
The test suite can be run by opening the ./spec/support/LocalTestRunner.html
file in a browser for a more detailed trace of errors.
The files for unit tests and any supporting JavaScript should be added to ./spec/manifest.js
file.
Usage¶ ↑
At the top of a Sass file in your project you should use an @import
rule to include the file for the mixins you require, eg if you want the conditionals and typography mixins you should add:
@import '_conditionals'; @import '_typography';
You may need to include the relative path to the toolkit if it is installed as a submodule:
@import '../toolkit/_conditionals';
If you are compiling Sass from the command-line tool, here are some options we recommend.
In development:
sass --style expanded --line-numbers --load-path [path to]/idsk_frontend_toolkit/stylesheets input.scss output.css
In production:
sass --style compressed --load-path [path to]/idsk_frontend_toolkit/stylesheets input.scss output.css
Documentation¶ ↑
Licence¶ ↑
Released under the MIT Licence, a copy of which can be found in the file LICENCE
.