There are a few different ways to get going with EvoToolkit, depending on your project.
Using EvoToolkit with a build system is the recommended way to add it to your project, as because you're dealing with the uncompiled source files directly, it gives you a lot more flexibility to tailor it towards your project needs.
If you're working on a project where you have the opportunity to implement a build system, you can leverage EvoToolkit to its full potential using the EvoToolkit Boilerplate.
To get started, download the boilerplate,
cd into it, and then run
npm install to install project dependencies.
This is the directory structure you'll be working with:-
dist- A directory which represents the files which you should
distribute to the user. Feel free to use your own directory structure to accomodate HTML, PHP or anything else, as long as you leave the
staticdirectory and its contents intact, as SASS and JS assets will be compiled here.
src- Source files for EvoToolkits SASS and JS. Here's where you'll be working with each of these respective elements.
You may notice that
src doesn't actually exist yet. To fix this, run
npm run init, which creates the
src directory and populates it with a number of subdirectories and files:-
init is complete, remove the
src line from the
.gitignore file to sure git picks up your project source files.
Whilst having seperate SCSS and JS manifest files for each page is recommened to lower filesize and performance impact, it's not required. In some projects, it may make more sense to have one set of manifest files which are shared across all pages.
Alongside the commands already mentioned, the boilerplate comes with commands (called NPM scripts) which allow you to easily compile SASS and JS assets. Type these commands into the terminal, within the git repo:-
npm install- Installs project depedencies.
npm run init- Sets up the
srcdirectory and creates a collection of template files.
npm run build- Compiles project SASS and JS into
npm run build:css- Same as above, but only compiling SASS.
npm run build:css:debug- Compiles SASS into unconpressed CSS, allowing for easier debugging.
npm run build:js- Same as above, but only compiling JS.
npm run build:svg- Concatinates all svg files in
src/assets/imginto one big
npm run watch- Whilst this is running, when either the SASS or JS in
src/assetsis edited, the build tasks will automatically run.
npm run watch:css- Same as above, but only watching for SASS changes.
npm run watch:js- Same as above, but only watching for JS changes.
It's possible to implement a build system to compile SASS and JS source files into existing projects, by downloading and tweaking the EvoToolkit Boilerplate to fit your needs:-
package.jsonto your project directory.
src/assetsdirectory to your project aswell, and then decide where you want to have the compiled files land.
dist/static/fontsto this directory, and then within
package.jsonand any files in
/build, update all the paths within each script to reflect your changes.
$global-font-pathSCSS variable so the CSS
@importrules can locate the fonts. See Configuring EvoToolkit for more info.
You can either place this in the head element to include all of the CSS.
<link rel="stylesheet" type="text/css" href="https://toolkit.evolutionfunding.com/source/evotoolkit.3.7.2.min.css" />
Or alternatively using its PHP api, you can include only the EvoToolkit CSS you need, which will result in a smaller, leaner stylesheet.
Pass the version number and any Object, Component or Utility parts in the query string like in the examples below, and the API will return all the CSS you need in a single request. When a stylesheet has been generated, the response is cached on the server to speed up future requests.
<!-- Includes Layout object and the Button component --> <link rel="stylesheet" type="text/css" href="https://toolkit.evolutionfunding.com/source?v=3.7.2&object/layout&component/button" /> <!-- Includes Inputs component, Typography component and the Widths utilties --> <link rel="stylesheet" type="text/css" href="https://toolkit.evolutionfunding.com/source?v=3.7.2&component/inputs&component/typography&utility/widths" /> <!-- Includes only Generic/Elements base styles. Not recommended if you're working on a system with existing styles, as these layers contain base CSS (eg: body, typography, box-sizing) which will likely create conflicts with existing styles. --> <link rel="stylesheet" type="text/css" href="https://toolkit.evolutionfunding.com/source?v=3.7.2&core" />
Place in the head element, anywhere after the CSS snippet.
<script defer src="https://toolkit.evolutionfunding.com/source/evotoolkit.3.7.2.min.js"></script>
Some components require SVG icons as a part of their design. These are located in a file called
evotookit.svg, which will be referenced in component HTML like:
<svg><use xlink:href="/static/img/evotoolkit-a9f6d11dc7.svg#icon-id" /></svg>
The only thing you will need to do for each icon is change this URL to match the external SVG resource, like so:
<svg><use xlink:href="https://toolkit.evolutionfunding.com/source/evotoolkit.3.7.2.svg#icon-id" /></svg>
This approach has a number of limitations when compared to using EvoToolkit via a build system. These include:-