Skip to content

Information for Developers

Jump to bottom
Dan Smith edited this page Dec 18, 2022 · 24 revisions

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

You will need

Setup process

A. Download the app files

  1. Open the SPREADSHEET
  2. Open GCC Help > Open Code Repository
  3. Clone this repository to your local machine

B. 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.

This 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.

C. Set up Clasp (standalone app)

NOTE! This step is only necessary if you will be using the app in standalone mode (for performance reasons or so that you can edit the codebase to suit your own needs). Alternatively you can just use the app as a library, within your own app. In that case you will have minimal code to manage so there's little benefit in using Clasp. TODO add instructions for this.

TODO npx clasp clone <scriptId> might also work! (see https://developers.google.com/apps-script/guides/clasp)

NOTE: it may be that none of this is necessary. I only needed to do it when clasp push starting failing but that was due to redundant super() calls in my code.

  1. Open .clasp.json
  2. Set the scriptId to the value copied from the Project Settings in step B
  3. Create a GCP project:
  4. Open https://console.developers.google.com/apis/credentials/consent?project=gsheet-compost-collections (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)
      • Application name: clasp project (TODO: I think this IS seen by users and should NOT reference Clasp)
      • 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
  5. 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=gsheet-compost-collections)
  6. Open https://console.cloud.google.com/apis/credentials?project=gsheet-compost-collections > 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
  7. Run npx clasp login (this will log you in globally)
  8. Don't run npx clasp login --creds creds.json

D. Configure app

  1. Open Config.js
  2. Edit saConfig and devConfig to suit your project

E. Upload the app files to Apps Script

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

F. Deploy the app

  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

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 preview
# OR: Update the TEST BUILD then manually open/refresh the web app
npm run clasp: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 --krmmessage="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