@digital-nature-ltd/carbon-lite/README.md

A simple tool to reduce the carbon usage of your website by blanking out the screen after a period of inactivity

# CarbonLite
A lightweight tool that blacks out a browser window when the user has not interacted with the page for a while.

![A preview of CarbonLite in action](carbon-lite-preview.png "CarbonLite when activated")

## Installation
There are a few installation options depending on your own level of expertise/comfort with web development. If you are maintaining a website through a CMS then you will likely want the simple option, but do also check out the simple with configuration option if you would like to customise CarbonLite

### Simple installation
The most simple installation just requires the script to be added to your site
```html
<script defer="defer" type="text/javascript" src="https://cdn.jsdelivr.net/gh/Digital-Nature-LTD/CarbonLite@v1.0.20/dist/CarbonLiteSimple.min.js"></script>
```

### Simple installation - with configuration
As with the simple installation, but you can add parameters to personalise Carbon Lite - see the configuration section below for a list of available parameters
```html
<script defer="defer" type="text/javascript" src="https://cdn.jsdelivr.net/gh/Digital-Nature-LTD/CarbonLite@v1.0.20/dist/CarbonLiteSimple.min.js?message=My Custom Message"></script>
```

### NPM package
You can install the package with npm
```shell
npm i @digital-nature-ltd/carbon-lite
```
You can then import and use CarbonLite in your scripts. 
```javascript
import CarbonLite from '@digital-nature-ltd/carbon-lite';

const cl = new CarbonLite();
// Call init to start CarbonLite.
// You can also pass configuration options to the init method
cl.init({
    timeout: 3000
});
```


### Need help with installation?
We're keen to get CarbonLite installed on as many sites as possible. If you're not able to get it up and running yourself then please get in touch with us on <hello@digital-nature.co.uk> and we will help with the installation - free of charge.


## Configuration
There are several options available to personalise the CarbonLite overlay and message, you can add these to the url parameters when you're adding the script to your page, or to the configuration object when calling the init method.

Note that examples each show a single parameter, but you can add several using the `&` character between each parameter - `e.g. src="https://cdn.jsdelivr.net/gh/Digital-Nature-LTD/CarbonLite@v1.0.20/dist/CarbonLiteSimple.min.js?timeout=45000&message=Hello, world!"`.

### Timeout
This is the number of milliseconds before CarbonLite is triggered

**Param:** `timeout`

**Default:** `60000` (60 seconds)
#### Example
```html
<!-- CarbonLite triggers after 45 seconds of inactivity -->
<script defer="defer" type="text/javascript" src="https://cdn.jsdelivr.net/gh/Digital-Nature-LTD/CarbonLite@v1.0.20/dist/CarbonLiteSimple.min.js?timeout=45000"></script>
```

### Message Timeout
This is the number of milliseconds that it takes for the CarbonLite message to fade out after the user interacts with the page

**Param:** `messageTimeout`

**Default:** `3000` (3 seconds)
#### Example
```html
<!-- The message fades out after 10 seconds -->
<script defer="defer" type="text/javascript" src="https://cdn.jsdelivr.net/gh/Digital-Nature-LTD/CarbonLite@v1.0.20/dist/CarbonLiteSimple.min.js?messageTimeout=10000"></script>
```

### Message
The message displayed in the middle of the screen when CarbonLite is active

**Param:** `message`

**Default:** `CarbonLite is reducing the carbon impact of this site, one (dark) pixel at a time`
#### Example
```html
<script defer="defer" type="text/javascript" src="https://cdn.jsdelivr.net/gh/Digital-Nature-LTD/CarbonLite@v1.0.20/dist/CarbonLiteSimple.min.js?message=My website is reducing carbon"></script>
```

### Background Colour
The background colour when CarbonLite is active. Note that the purpose of CarbonLite is to reduce energy usage, so please ensure you choose a low-energy colour if you're replacing the default

**Param:** `backgroundColour`

**Default:** `#000` (black)
#### Example
```html
<!-- Using a named colour -->
<script defer="defer" type="text/javascript" src="https://cdn.jsdelivr.net/gh/Digital-Nature-LTD/CarbonLite@v1.0.20/dist/CarbonLiteSimple.min.js?backgroundColour=green"></script>
```

Note that when using a hex colour in a url param you will need to encode the hash as %23 otherwise the value will be lost. The example below shows `#333` encoded.
```html
<!-- Note that when using a hex colour you should encode the hash as %23 -->
<script defer="defer" type="text/javascript" src="https://cdn.jsdelivr.net/gh/Digital-Nature-LTD/CarbonLite@v1.0.20/dist/CarbonLiteSimple.min.js?backgroundColour=%23333"></script>
```

### Message Colour
The text/icon colour of the messages shown while CarbonLite is active

**Param:** `messageColour`

**Default:** `#254137`

**Example** - As "Background Colour" but with updated parameter name

### Message Colour on Hover
The text/icon colour of the CarbonLite message while hovering 

**Param:** `messageColourHover`

**Default:** `#7DF799`

**Example** - As "Background Colour" but with updated parameter name

### Message Border Colour
The colour of the CarbonLite message border, note that this is only shown when the CarbonLite background has been removed

**Param:** `messageBorderColour`

**Default:** `#7DF799`

**Example** - As "Background Colour" but with updated parameter name


### Message Drop Shadow Colour
The colour of the CarbonLite message drop shadow, note that this is only shown when the CarbonLite background has been removed

**Param**: `messageDropShadowColour`

**Default**: `#254137`

**Example** - As "Background Colour" but with updated parameter name


## Events
CarbonLite can be suspended and resumed using custom events, this can be useful if there are times that you would like to prevent CarbonLite from triggering, e.g. while watching a video

### Open
Opens CarbonLite immediately.

```javascript
const customEventOpen = new CustomEvent('carbon-lite-open');
document.dispatchEvent(customEventOpen);
```

#### Open - with config
You can (optionally) provide event details to alter the behaviour:

- `interactionDelay` is a number of milliseconds. During this time the overlay will ignore interactions (i.e. stay open)
- `tempMessage` is a temporary message to display while interactions are suspended

The example below will open the overlay immediately, even if the user interacts, it will not close for the next 5 seconds, and during this time it will display the temporary message.
```javascript
const customEventOpen = new CustomEvent('carbon-lite-open', { 'detail': { interactionDelay: 5000, tempMessage: 'This message will show while ignoring interactions' } });
document.dispatchEvent(customEventOpen);
```

### Suspend
Closes CarbonLite and stops it from re-opening
```javascript
const customEventSuspend = new CustomEvent('carbon-lite-suspend');
document.dispatchEvent(customEventSuspend);
```

### Resume
Restarts the CarbonLite timer (from 0s)
```javascript
const customEventResume = new CustomEvent('carbon-lite-resume');
document.dispatchEvent(customEventResume);
```