EvoToolkit - v2.3.0 (Changelog)

Getting Started

There are a few different ways to get going with EvoToolkit, depending on your project.

  • Build System
  • No Build System

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.

New Projects

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 static directory 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.

Directory Setup

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:-

  • /src
    • /assets
      • /scss
        • /components
          • _sample.scss Template file for your project components.
        • /elements
        • /generic
        • /objects
        • /settings
          • _dependencies.scss Here you can modify the dependency chain for existing and new components. See "Extending EvoToolkit" for more details on this.
          • _overrides.scss Configure EvoToolkit globals which are shared across all SASS manifest files. Useful for easily enabling styles which need to be present on every page.
          • _theme-overrides.scss Contains all EvoToolkit options for configuring theme colours.
        • core.scss Manifest file containing generic and element layers. These are unlikely to change, so are split into their own stylesheet where they can be cached ad infinitum.
        • sample.page.scss Duplicate and rename this manifest file for each page, and then you can ensure only the styles in use on the page are compiled.
      • /js
        • /components
        • /objects
        • /tools
        • sample.page.js The JavaScript manifest file where logic is imported. Duplicate for each page to gain more control over what logic is included where; avoiding a huge JavaScript bundle in the process.

When 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.

Compiling Assets

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 src directory and creates a collection of template files.
  • npm run build - Compiles project SASS and JS into dist/static.
  • 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 watch - Whilst this is running, when either the SASS or JS in src/assets is 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.

Existing Projects

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:-

  1. Firstly, make sure you have Node.js installed.
  2. From the boilerplate, copy package.json to your project directory.
  3. Copy the src/assets directory to your project aswell, and then decide where you want to have the compiled files land.
  4. Copy dist/static/fonts to this directory, and then within package.json and any files in /build, update all the paths within each script to reflect your changes.
  5. Depending on your directory setup, you may need to edit the path in the $global-font-path SCSS variable so the CSS @import rules can locate the fonts. See Configuring EvoToolkit for more info.
  6. From here on out, you can follow the 'New Projects' guidelines above.

With existing projects where it's not possible to implement any kind of build system, you can use EvoToolkit by including its compiled CSS and JavaScript directly in your project.

To do this, copy/paste the contents of evotoolkit.min.css into your own CSS file and evotoolkit.min.js into your JavaScript.

You can also include EvoTookit CSS & JS directly through <style> and <script> tags as per the below snippets. These are versioned to prevent the CSS and JavaScript from automatically updating and breaking your code when new versions of EvoToolkit are released.

CSS

Place in the head element.

<link rel="stylesheet" type="text/css" href="https://toolkit.evolutionfunding.com/source/evotoolkit.2.3.0.min.css" />

JavaScript

Place just before the closing body tag.

<script src="https://toolkit.evolutionfunding.com/source/evotoolkit.2.3.0.min.js"></script>

Installing Icons

Some components require SVG icons as a part of their design, so we need to make these available in our HTML. Copy the below snippet into your page, placing it just after the opening body tag.

This is the root svg element which contains our icon system. When a component requires an icon, its symbol will be included so it's just a matter of copying it into the svg and then everything should just work.

For more information on this approach, see here and then here.

Caveats

This approach has a number of limitations when compared to using EvoToolkit via a build system. These include:-

  • The compiled versions represent the full EvoToolkit CSS & JS codebase, so you will be pulling in a lot of code you may not even need, which will lead to larger file sizes. In contrast, with a build system, much of EvoToolkit is disabled by default; encouraging an "enable as required" approach to keep the codebase lean.
  • In CSS, it's more difficult to handle the cascade and selector specificity, as you no longer have the ITCSS architecture to guide how project CSS should be structured.
  • In JS, you can no longer leverage shared functionality, nor can you easily tweak component logic.