inclusive-design / wecount.inclusivedesign.ca

The source files for the We Count website, built with Eleventy.

We Count

The source code for the We Count website.

The front end of the website is built with Eleventy.

The website uses Decap CMS to manage the following content:

• events
• pages
• news
• initiatives

The website also uses one backend API:

• Airtable API that serves user comments for events.
  • The production table: WeCount
  • The development table: WeCount_DEV

Getting Started

To contribute, please be sure to review our development processes as documented in the contributing guide.

To work on the project, you need to install NodeJS and NPM for your operating system.

Then, clone the project from GitHub. Create a fork with your GitHub account, then enter the following in your command line (make sure to replace your-username with your username):

git clone https://github.com/your-username/wecount.inclusivedesign.ca.git

From the root of the cloned project, enter the following in your command line to install dependencies:

npm ci

Content Management System (CMS)

Decap CMS is a client-side React application which manages files in a git repository, creating pull requests when new content is drafted and merging them when it is published. Access to this website's CMS is managed via Netlify Identity. If you need access to the CMS, a team administrator must invite you to create a Netlify Identity account.

CMS Configuration

The CMS is configured via a config.yml file according to Decap CMS' specifications. As an example, here is the configuration for the events collection, stored in src/collections/events:

- name: events
  label: Events
  label_singular: Event
  folder: src/collections/events
  sortable_fields: [eventDate, title]
  slug: "{{title}}"
  preview_path: "events/{{slug}}"
  create: true
  fields:
    - label: Event Title
      name: title
      widget: string
    - label: Event ID
      name: id
      widget: uuid
      hint: The ID is used to associate comments with this event and cannot be edited.
    - label: Permanent Link
      name: permalink
      widget: string
      required: false
      hint: |-
        If you do not specify a permanent link, one will be automatically generated from the event title.
        Permalinks must have the format /events/event-title/ (the trailing slash is required).
    - label: Event Date
      name: eventDate
      widget: datetime
      time_format: false
      required: false
    - label: Cover Image
      name: coverImageUrl
      widget: image
      required: false
    - label: Cover Image Alt Text
      name: coverImageAltText
      widget: string
      required: false
    - label: Event Body
      name: body
      widget: markdown
    - label: Short Description
      name: shortDescription
      widget: markdown
      hint: The short description is shown on the Events page.
    - label: Preview Image
      name: previewImageUrl
      widget: image
      required: false
      hint: The preview image is shown on the Events page.
    - label: Preview Image Alt Text
      name: previewImageAltText
      widget: string
      required: false

For information on individual widgets and their configuration, see Decap CMS' widget documentation.

Previews

Decap CMS supports preview templates for CMS content, which must be a React component registered with the following code (the following examples are for events):

CMS.registerPreviewTemplate("events", Event);

The Event React component is created in src/admin/cms.js based on a technique demonstrated in Andy Bell's Hylia Eleventy starter kit:

1. The site's Nunjucks templates are precompiled and copied to the admin directory of the built site (Eleventy handles this here).
2. A generic Preview React component accepts a data object and a Nunjucks template path, renders the Nunjucks template with the supplied data using Nunjucks Slim, and outputs the resulting HTML.
3. The specific Event React component passes the Preview component the entry object (from Decap CMS), the Nunjucks template path (relative to src/_includes), and a function which maps the entry object's data to what's needed in the Nunjucks template expects.

This approach allows the templates which Eleventy uses to render the production site to be consumed by Decap CMS and used to generate live previews as content editors are updating content in the CMS interface.

Testing the CMS

The CMS may be tested locally without authentication if the site is being run in development mode as documented below. Any changes made will be immediately reflected in the file system. This is a good way of making sure that CMS functionality behaves as expected, but content should not be edited this way under normal circumstances. Rather, content editors should log in under their Netlify Identity accounts at https://wecount.inclusivedesign.ca/admin/ and create content through the CMS interface.

How to Run

The website uses Netlify Functions to provide a server side endpoint that supports the save of user comments for initiatives on the "Initiatives" page. To run the website in local development mode that supports a live reload at file changes, there are two ways to test the website with and without Netlify Functions. The latter is easier than the former:

Test the website with Netlify Functions

1. Follow Netlify instructions to install tools for testing and deploying Netlify functions locally;
2. Once the tool is set up, using Netlify Dev as an example, run following commands:

# Due to security concerns, these environment variables are only available to WeCount team members
export AIRTABLE_API_KEY=AIRTABLE_API_KEY_VALUE
export EMAIL_FROM=EMAIL_TO_VALUE
export EMAIL_FROM_PWD=EMAIL_FROM_PWD_VALUE
export EMAIL_TO_PRODUCTION=PRODUCTION_SITE_MODERATOR_EMAIL
export EMAIL_TO_DEV=DEV_SITE_MODERATOR_EMAIL
export AIRTABLE_BASE_PRODUCTION=AIRTABLE_BASE_VALUE_FOR_PRODUCTION
export AIRTABLE_BASE_DEV=AIRTABLE_BASE_VALUE_FOR_DEV

netlify dev

Look for this box in your console output:

   ┌──────────────────────────────────────────────────┐
   │                                                  │
   │   * Server now ready on http://localhost:64939   │
   │                                                  │
   └──────────────────────────────────────────────────┘

The website will be available at http://localhost:64939.

Alternatively, a .env file can be created within the local project directory and environment variables can be added directly to it as follows:

AIRTABLE_API_KEY=AIRTABLE_API_KEY_VALUE
EMAIL_FROM=EMAIL_TO_VALUE
EMAIL_FROM_PWD=EMAIL_FROM_PWD_VALUE
EMAIL_TO_PRODUCTION=PRODUCTION_SITE_MODERATOR_EMAIL
EMAIL_TO_DEV=DEV_SITE_MODERATOR_EMAIL
AIRTABLE_BASE_PRODUCTION=AIRTABLE_BASE_VALUE_FOR_PRODUCTION
AIRTABLE_BASE_DEV=AIRTABLE_BASE_VALUE_FOR_DEV

(Note: .env is in the project's .gitignore file to prevent sensitive information from being accidentally committed to git.)

If a .env file is used, the local development server can be started with the following command:

netlify dev

Test the website without Netlify Functions

Note that the website launched via this testing method cannot save user comments to Airtable due to the absence of the server side save function.

# Due to security concerns, these environment variables are only available to WeCount team members
export AIRTABLE_API_KEY=WECOUNT_API_KEY
export AIRTABLE_BASE_PRODUCTION=AIRTABLE_BASE_VALUE_FOR_PRODUCTION
export AIRTABLE_BASE_DEV=AIRTABLE_BASE_VALUE_FOR_DEV
npm run start

The website will be available at http://localhost:3000.

Alternatively, a .env file can be created within the local project directory and environment variables can be added directly to it as follows:

AIRTABLE_API_KEY=AIRTABLE_API_KEY_VALUE
AIRTABLE_BASE_PRODUCTION=AIRTABLE_BASE_VALUE_FOR_PRODUCTION
AIRTABLE_BASE_DEV=AIRTABLE_BASE_VALUE_FOR_DEV

(Note: .env is in the project's .gitignore file to prevent sensitive information from being accidentally committed to git.)

If a .env file is used, the local development server can be started with the following command:

npm run start

How to Lint

To lint JavaScript, CSS and Markdown files in the project (including JavaScript and CSS in Vue components), enter the following in the command line:

npm run lint

We use the following lint configurations:

• ESLint (JS)
• Stylelint (CSS/SCSS)
• MarkdownLint (Markdown)

How to Build

Note that the website launched via this build method cannot save user comments to Airtable due to the absence of the server side save function.

To build and serve a static version of the website, enter the following in your command line:

# Due to security concerns, these environment variables are only available to WeCount team members
export AIRTABLE_API_KEY=AIRTABLE_API_KEY_VALUE
export AIRTABLE_BASE_PRODUCTION=AIRTABLE_BASE_VALUE_FOR_PRODUCTION
npm run build
npm run serve

The website will be available at http://localhost:5000.

Alternatively, a .env file can be created within the local project directory and environment variables can be added directly to it as follows:

AIRTABLE_API_KEY=AIRTABLE_API_KEY_VALUE
AIRTABLE_BASE_PRODUCTION=AIRTABLE_BASE_VALUE_FOR_PRODUCTION

(Note: .env is in the project's .gitignore file to prevent sensitive information from being accidentally committed to git.)

If a .env file is used, the site can be built and served with the following commands:

npm run build
npm run serve

How to Deploy

This repository is connected to Netlify, and commits will be automatically deployed as follows:

• Pull request #175 (for example): https://deploy-preview-175--wecount.netlify.app
• Branch dev: https://dev--wecount.netlify.app
• Branch main: https://wecount.inclusivedesign.ca

License

This work is licensed under a Creative Commons Attribution 4.0 International License.