EvoToolkit - v2.3.0 (Changelog)

Extending EvoToolkit

Introducing new components and functionality to EvoToolkit on a project by project basis is relatively straightforward.

  • CSS
  • JavaScript

New Components

When creating new parts within your ITCSS layers, it's largely just a matter of creating the files in the correct directory, and then adding their imports to your SCSS manifest files: -

// COMPONENTS (Ready made, customisable UI components which you can drop into your project) @import 'node_modules/evotoolkit/src/scss/components/core'; @import "components/my-component";

If you have a seperate manifest file for every page, a good pattern is to create your own core.scss and add your imports there. This means that as long as this file is being imported into each of your manifest files, when any future components are added, you will only have to update that single core.scss file.

// COMPONENTS (Ready made, customisable UI components which you can drop into your project) @import 'node_modules/evotoolkit/src/scss/components/core'; @import "components/core";

It's recommended that you use the template from scss/components/_sample.scss as a base for your component, as this includes all the bespoke EvoToolkit structure and functionality shared by other parts.

If your new component is wrapped in the render() mixin, you must also add your new component $imports to make sure it is included in the compiled CSS.

Editing Existing Parts

When editing existing parts, one option is to just copy their existing scss file from node_modules/evotoolkit/src/scss, place it in your own corresponding layer directory, make your changes and then update the import path in the relevant core.scss file.

Though this isn't recommended, as if you update your EvoToolkit dependency in the future, bug fixes or changes won't make it through to your edited version. The recommended way to edit existing EvoToolkit content is to create what's called an extend.

This is simply a new file with an extend prefix:- extend.my-component.scss, placed in the correct ITCSS directory, and containing only the changes you're introducing. This means you aren't blocking updates, and still having your changes in effect.

With all this taken into account, within a typical EvoToolkit SASS manifest, the component imports may look something like this:-

// COMPONENTS (Ready made, customisable UI components which you can drop into your project) @import 'node_modules/evotoolkit/src/scss/components/core'; @import "components/extend.typography"; @import "components/extend.table"; @import "components/extend.box"; @import "components/component"; @import "components/colors"; @import "components/header"; @import "components/module"; @import "components/footer"; @import "components/nav"; @import "components/icons";

Here there's a mixture of default EvoToolkit components imported via core.scss, extended components where changes are introduced, and brand new components bespoke to the project.

If you have a seperate manifest file for every page, as mentioned under 'New Components', creating your own core.scss to store your imports and adding it to each manifest files, means you will only have to edit one file as new components are introduced.

New Components

Any JavaScript for new components should be seperated into their own files, and then imported into your JavaScript manifest, which is named sample.page.js by default. Like with SCSS, you can duplicate this file per page, allowing you to only import the JavaScript you require.

Classes are used to store logic for any EvoToolkit layer parts which require some form of JavaScript functionality. A template can be found in js/components/sample.js.

Editing Existing Components

When editing existing component's JavaScript logic, it's worth checking first if you can add your custom logic by hooking into component event hooks. These are events which are fired on key component actions (For example:- modal open) and are intended to serve as entry points for custom behaviour. You can find a full breakdown in each component's documentation page.

You would typically attach logic to custom events in the same way you would regular events - with Event Listeners:-

const myComponent = document.querySelector('.js-my-component'); myComponent.addEventListener('eventName', function() { // Custom logic });

If your custom behaviour can't be added via event hooks, the alternative may be to just copy the component file from node_modules and change it to meet your needs. However, the downside is when the EvoToolkit depedency is updated, bug fixes and new features won't come into effect for that file, as you're no longer importing the latest version.

Here's some general tips for working with JavaScript in EvoToolkit:-

  • Try to extrapolate repeatable functionality into seperate helper functions to keep things DRY.
  • Feel free to use ES6 JavaScript, as it's transpiled by Babel on compile.
  • When adding extra logic to existing components, it's recommended that you add a new class with a js prefix to your target element. Why? You may not want your new logic to apply to every instance of the component in use.
  • When declaring variables, always use const, unless you know it's going to be mutated, where you should instead use let.

See JavaScript API for more information.