Skip to content

Information for Developers

Jump to bottom
Dan Smith edited this page May 27, 2023 · 24 revisions

This page is for the owner/developer of the web app.

You will need

Setup process

1. Set up a Google Cloud Project

This is required to manage access to the app.

  1. Open https://console.cloud.google.com/cloud-resource-manager?walkthrough_id=resource-manager--create-project
  2. Select Create project
  3. Project name: Gsheet Compost Collections
  4. Project ID (edit): gsheet-compost-collections-2 (I use -2 after migrating from my company Google account to a personal Google account)

2. Set up the standalone Apps Script project

This involves setting up clasp then deploying the application code for the project. You can then use this code as-is, or edit it to meet your needs.

2a. Download the app files

  1. Open the SPREADSHEET
  2. Open GCC Help > Code > Open Code Repository
  3. Clone this repository to your local machine: Code > Download ZIP
  4. Open a Terminal > Navigate to the downloaded folder > npm install

2b. Create an Apps Script project

Application files are stored in this Github repository and hosted in Google Apps Script.

  1. https://script.google.com/ > Start scripting > Log in
  2. https://script.google.com/ > New project > Untitled project > type Gsheet Compost Collections
  3. Project Settings (cog icon) > Show "appsscript.json" manifest file in editor
  4. Project Settings (cog icon) > Script ID > Copy (this is the same ID as shown in the URL i.e. https://script.google.com/home/projects/{ID})

The web app reads and writes from a Google Sheet. Google Apps Script offers the choice of a 'container-bound' (spreadsheet linked) or 'standalone' project.

The main script is authored as a 'standalone' project (created at script.google.com rather than via sheets.google.com). This facilitates testing across different spreadsheets and allows the project to be reused as an Apps Script library.

Additional container-bound scripts are used for configuration purposes.

2c. Set up Clasp

Clasp (Command Line Apps Script Projects) allows files to be edited in your local IDE (code editor) rather than in the remote (web-based) IDE.

Clasp is essential for GCC, because the project uses NPM tasks to run additional scripts before running Clasp functions.

  1. Open .clasp.json
    • set the scriptId to the value copied from the Project Settings in 2b. Create an Apps Script project
    • set the projectId to the value used in 1. Set up a Google Cloud Project (npx clasp setting projectId YOUR_PROJECT_ID does the same thing)
  2. Enable the Apps Script API: https://script.google.com/home/usersettings
  3. Open https://console.developers.google.com/apis/credentials/consent?project=YOUR_PROJECT_ID (Edit app registration: OAuth consent screen)
    • App information
      • User Type: External (or Internal if that suits you better, see also Information-for-Administrators.md > App users - share the GCP PROJECT)
      • App name: Gsheet Compost Collections (this would be seen by any end user trying to load the library Web App URL directly, for the first time)
      • User support email: select your email from the list
      • App logo: - (no logo to upload)
    • App domain
      • Application home page: https://github.com/dotherightthing/gsheet-compost-collections
      • Application privacy policy link: https://github.com/dotherightthing/gsheet-compost-collections
      • Application Terms of Service link: https://github.com/dotherightthing/gsheet-compost-collections
      • Authorised domains: github.com
    • Developer contact information: enter your email
  4. Project Settings (cog icon) > Google Cloud Platform (GCP) Project > Change project > (Enter GCP project number) > Set project (if you lose your Project number you can retrieve it from https://console.cloud.google.com/home/dashboard?project=YOUR_PROJECT_ID)
  5. Open https://console.cloud.google.com/apis/credentials?project=YOUR_PROJECT_ID > Create credentials > OAuth client ID
    • Application type: Desktop App
    • Name: Gsheet Compost Collections OAuth Client
    • Download the JSON credentials file to the project directory as creds.json
  6. Open a Terminal, navigate to the folder downloaded in 2a. Download the app files then run npx clasp login (this will log you in globally - don't run npx clasp login --creds creds.json)

2d. Upload the app files to Apps Script

  1. npm run push
  2. At ? Manifest file has been updated. Do you want to push and overwrite? (y/N) type y (Yes)

2e. Deploy the standalone app

The main application code is consumed as a library rather than accessed directly from a URL.

Deployment allows new versions to be added to the standalone library.

Container-bound scripts can then choose to load the development version of the library (HEAD) or a specific numbered version.

This protects users by allowing them to use an older version of the app library while new features are being developed.

Initial deployment

The initial deployment must be done from the IDE:

  1. Deploy > New deployment
  2. Select type: Web app
  3. Description: Initial deployment
  4. Execute as: User accessing the web app
  5. Who has access: Only myself
  6. Deploy

Subsequent deployments (releases)

Thereafter, deployments can be managed from the commandline:

# Update the STABLE BUILD
npm run publish --gccmessage="VERSION_DESCRIPTION"

This updates and opens the latest STABLE APP (TODO using the old version of the library).

Then:

  1. Open the container-bound Apps Script project (see 4. Set up the container-bound Apps Script project)
  2. Open appsscript.json
  3. Change dependencies.libraries.version to the deployed library version (integer)
  4. Save changes
  5. Open spreadsheet (see 3. Create a spreadsheet) > GCC Help > Mobile App > Open STABLE App

3. Create a spreadsheet

The app uses a spreadsheet as its database and for limited configuration.

3a. Create Named Ranges

Specific Named Ranges must be added to demarcate rows and cells for processing by the script.

  1. TODO - https://github.com/dotherightthing/gsheet-compost-collections/issues/36

4. Set up the container-bound Apps Script project

This is attached to the spreadsheet.

It loads the standalone Apps Script project as a library.

It is used to configure the standalone application.

It provides a custom spreadsheet menu and access to the Web App.

  1. See instructions in https://github.com/dotherightthing/gsheet-compost-collections/tree/main/demo

5. Deploy the container-bound app

Test deployment

  1. Deploy > Test deployments > Web app > URL > Copy
  2. Paste the URL into a web browser

Versioned deployment

Subsequent deployments (tests)

  1. https://script.google.com/ > Open project > Deploy > Test Deployments > Web app > Copy
  2. Paste the URL into a web browser
  3. At the prompt, click Review permissions > click on your account name > scroll down > click Allow
  4. If there is an error, go to https://script.google.com/ > Open project > Executions > click on the Failed execution

TODO xXXXX

Configure the container bound script and add youself as a test user - see Information-for-Administrators.md

TODO xxxcxx

Spreadsheet > Settings > Locale > United Kingdom

Configure development environment

Online development

Application code may be edited and deployed using the Apps Script project IDE (https://script.google.com/ > My Projects > Gsheet Search > Editor), which is similar to VSCode.

Local development

Alternatively, application code can be cloned to your local development environment using clasp. This simplifies some aspects of development and allows the code to be checked into version control (i.e. this repo).

This Medium article about clasp outlines the benefits of this approach.

To configure the CLASP configuration file:

  1. Open .clasp.json
  2. Locate the scriptId property and change its value to your script ID

Then:

npm install
npx clasp login

Workflow

Sync

Get the latest code from the server, to capture changes from any developers not using the Github repo.

Note: You will need to manually copy the internals of src/Htmlified files to the corresponding originals in src/Classes.

npx clasp pull

Develop

Code execution can be tested by directly calling the serverside functions contained in Main and Middleware.js.

This is a great way to get developer-friendly error messages, rather than the user-friendly ones provided in-app.

Due to issue #1, this requires jumping over to the online development environment.

npm run editor
# 'Select function to run' from the dropdown:
# doGet - tests the template generation
# Click 'Run'

Test

Linting

A Husky Git Hook triggers the following tasks whenever code is pushed to Github:

  1. linting of CSS files
  2. linting of JavaScript files
  3. rebuild of the JavaScript documentation (MANual)
Functions

Input handling is tested by running Qunit tests on the latest code (aka the TEST BUILD).

npm run test

Note: Testing on different data sources can be performed by using the app as a library.

Data

Data manipulation can be verified by viewing the SPREADSHEET.

Deploy

Visual and interactive testing requires viewing the web app.

# EITHER: Update the TEST BUILD then automatically open the web app
npm run openPreview
# OR: Update the TEST BUILD then manually open/refresh the web app
# Note! Do not run `npx clasp push` directly, as this bypasses extra steps which the app must perform on push
npm run push

This updates and opens the latest DEV APP.

This allows changes to be tested without impacting the STABLE APP.

Note: In the online IDE, this Web app URL is accessed under Test deployments.

Publish

The initial deployment must be done from the IDE: Deploy > New deployment.

Thereafter, deployments can be managed from the commandline:

# Update the STABLE BUILD
npm run publish --gccmessage="VERSION_DESCRIPTION"

This updates and opens the latest STABLE APP.

Then:

  1. Open the APPS SCRIPT PROJECT
  2. Open appsscript.json
  3. Change dependencies.libraries.version to the deployed version (integer)
  4. Save changes

Code documentation

The MANual is generated from JSDoc comments in the sourcecode (Local development only).

Data integrity

The good functioning of the app is dependent on the structure of the source spreadsheet being maintained.

Brittleness is mitigated somewhat by referencing strings/labels rather than ranges/locations:

  • Column headers - Row and column containing header strings
  • Named ranges
  • Run range - e.g. Row containing "MT VIC RUN", down to the row containing "MT COOK RUN"
  • etc

Troubleshooting tips

When a test fails to load, or fails to run, or fails unexpectedly, Qunit won't usually offer any useful feedback. In this case:

  • run npm run test rather than npx clasp push once
  • check that the tested static method doesn't access this
  • check that the test targets the correct testing function (i.e. that the method exists for a particular class)
  • navigate through the app and watch for load error messages
  • wait a minute then refresh the page
  • run the tests from Apps Script > Gsheet Compost Collections App tests > Editor > Code.gs - then view the Execution log

Clone this wiki locally