Skip to content

Information for Developers

Jump to bottom
Dan Smith edited this page Oct 27, 2024 · 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

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.

However it is recommended to use a local development environment in conjunction with Clasp (Command Line Apps Script Projects), via the NPM scripts. This simplifies some aspects of development, allows the code to be checked into version control (i.e. this repo) and ensures that any changes are packaged correctly (using the NPM scripts to run additional scripts before the clasp scripts).

This Medium article about clasp outlines the benefits of using Clasp.

  1. Open .clasp.json (the Clasp configuration file)
    • 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)
  7. Open package.json and change config.headDeploymentId to the value of Deploy > Test deployments > Head Deployment ID

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

Update the library version used by the container-bound script
  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. Set the locale

  1. Spreadsheet > Settings > Locale > United Kingdom

3b. 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/37

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

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 openEditor
# '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

Tests can't be run from the standalone app, as they require a data source (spreadsheet) and associated app configuration (Apps Script project).

Tests should be run from the spreadsheet menu instead:

  • Frontend tests: GCC Help > Code > Run Unit Tests
  • Backend tests: GCC Help > Code > Run Integration Tests

Both will run tests on the latest code (aka the TEST BUILD).

Testing on different data sources can be performed by adding additional spreadsheets, each with their own container-bound Apps Script configuration.

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.

Debug

  1. Set appConfig.debug: true in Main.js
  2. Use console.log to temporarily output strings and variable values
  3. Or for permanent logging: const { debug } = KrmCache.settings; if (debug) { console.log('foo'); }
  4. Open the APPS SCRIPT PROJECT > Click Executions > Click on any script execution to view its logs
  5. Or open the DEV APP > Click DEBUG in the footer

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 removes the QUnitGS2 integration testing dependency, then updates and opens the latest STABLE APP.

Update References to Published App
  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 Named Ranges and strings/labels:

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

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 unit and integration tests
  • 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
  • open the web browser's developer console and watch for errors there
  • wait a minute then refresh the page
  • run the tests from Tests/Integration.gs - then view the Executions log
Clone this wiki locally