Skip to content

Information for Developers

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

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

You will need

Setup process

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

After initially being developed as 'container-bound', this script has been redeployed as a 'standalone' project. This aims to ensure that integration and testing yields predictable results across both the original and cloned/test spreadsheets.

Link the spreadsheets

  1. Extract the spreadsheet ID from the URL of the MASTER SPREADSHEET: https://docs.google.com/spreadsheets/d/{SPREADSHEET ID}/edit#gid=
  2. Extract the spreadsheet ID from the URL of the TEST SPREADSHEET: https://docs.google.com/spreadsheets/d/{SPREADSHEET ID}/edit#gid=
  3. Copy and paste these into the spreadsheetIds object in Main.js

TODO: scriptIds

TODO: deploymentIds

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

Application files are stored in the APPS SCRIPT UNIT TESTS PROJECT, and in the Gsheet Compost Collections app tests repository. See that repository's README for more information.

# EITHER: Update the TEST BUILD then automatically open the test results page
npm run test
# OR: Update the TEST BUILD then manually open/refresh the test results page
npm run clasp:push
Data

Data manipulation can be verified by viewing the MASTER SPREADSHEET. The TEST SPREADSHEET is used during development, to prevent accidental corruption of company data.

Sync the TEST and MASTER SPREADSHEETs

Warning: This overwrites all data in the test sheet!

  1. Open the APPS SCRIPT PROJECT
  2. Open Main.gs
  3. Run: krmSyncRunSheets

This overwrites the test sheet with the latest data (and formatting) from the master sheet.

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

Clone this wiki locally