EvoToolkit - v3.0.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
      • /img
        • [svg icon files] All of the .svg files for EvoToolkit components are included here. On compile, they are concatinated into a single .svg file.
      • /js
        • /components
        • /objects
        • /tools
        • sample.page.js The JavaScript manifest file where logic is imported. You may want to duplicate for each page to gain more control over what logic is included where; avoiding a huge JavaScript bundle in the process.
      • /scss
        • /components
          • _sample.scss Template file for your project components.
        • /elements
        • /generic
        • /objects
        • /settings
          • _overrides.scss Configure EvoToolkit globals which are shared across all SASS manifest files.
          • _theme-overrides.scss Contains all EvoToolkit options for configuring theme colours.
        • sample.page.scss This is where all the partials are imported. Rename to something more appropriate for your website.

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 build:svg - Concatinates all svg files in src/assets/img into one big .svg file.
  • 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, JavaScript and SVGs directly in your project.

To do this, copy/paste the contents of evotoolkit.min.css into your own CSS file, evotoolkit.min.js into your JavaScript, and evotoolkit.svg in an svg file (Remember to update the xlink:href paths in SVGs belonging to any EvoToolkit components you use).

You can also include EvoTookit CSS, JavaScript and SVG directly through <style> and <script> tags as per the below snippets. These are versioned to prevent the CSS, JavaScript and SVGs 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.3.0.0.min.css" />

JavaScript

Place in the head element, anywhere after the CSS snippet.

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

SVG Icons

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:

The only thing you will need to do for each icon is change this URL to match the external SVG resource, like so:

Compression

As these files include all of Evotoolkit, whether used or not, it's important if possible to compress files to reduce load times. Here are estimated savings you can expect to make for the latest version.

v3.0.0 Uncompressed gzip Brotli
CSS 231.5kb 22.3kb 15.3kb
JavaScript 163.6kb 40.2kb 35.1kb
SVG 3.3kb 1.5kb 1.3kb

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 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, you can take 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.