If you enjoy my Google Workspace Apps Script work, please consider buying me a cup of coffee!
Basic Jekyll theme for local Google Apps Script UI development.
See the blog post.
Useful for:
- Local Add-on and Web Application UI development
- Rapid UI prototyping with Jekyll's auto-regeneration feature
Theme includes:
- Reference to CSS required for all Google Apps Add-ons
- Flexible configuration
Project Directory Structure:
gapps-jekyll-basic/
|-- _includes/
| |-- example/
| |-- search.html
| |-- executionapi/
| |-- executionapi.html
| |-- gsapi.html
| |-- branding.html
| |-- head.html
| |-- css.html
| |-- js.html
|-- _layouts/
| |-- default.html
|-- _config.yml
|-- apiexample.html
|-- index.html
Configuration (_config.yml
):
- Development & Production modes
- Multiple window sizing options:
sidebar
,dialog
orfull
- Optional: jQuery inclusion
- Optional: Non-scrolling branding area inclusion
- Optional: Test integration through the Execution API
# Jekyll Google Apps Script Basic Configuration
config:
production: false
screen:
size: "dialog"
width: "500"
height: "500"
branding: true
jquery:
include: true
version: "2.2.4"
executionApi:
include: false
clientId: "OAUTH CLIENT ID"
scriptId: "SCRIPT ID"
-
Install Jekyll
-
Clone this project
git clone https://github.com/techstreams/gapps-jekyll-basic.git
- Navigate to project directory
cd gapps-jekyll-basic
- Run Jekyll
jekyll serve
- View in the local development server: http://localhost:4000
DEVELOPMENT MODE:
- In
_config.yml
:
-
Set
production
option tofalse
-
Set
screen size
option to desired value:sidebar
,dialog
orfull
If the screen size is
dialog
, set the screenwidth
andheight
options to desired values ...sidebar
andfull
'width' and 'height' values are preset
- Start/Restart the Jekyll server in project directory
jekyll serve
or
jekyll build --watch
-
Add any client-side Javascript to
_includes/js.html
-
Add any custom CSS to
_includes/css.html
-
Make iterative UI modifications to
index.html
... Jekyll will auto-regenerate the site
PRODUCTION MODE:
- In
_config.yml
:
- Set
production
option totrue
- Start/Restart the Jekyll server and wait for site to build
jekyll serve
or
jekyll build
- Copy the generated
_site/index.html
file to the Google Apps Script environment
To Include Branding:
- In
_config.yml
:
- Set the
screen branding
option totrue
-
Start/Restart the Jekyll server
-
Update the
_includes/branding.html
file with branding information
To Include jQuery:
- In
_config.yml
:
-
Set the
jQuery include
option totrue
-
Set the
jQuery version
option the desired Google CDN hosted jQuery version
- Start/Restart the Jekyll server
DEVELOPMENT MODE:
Test UI in Development Mode by integrating with the Google Apps Script Execution API:
-
Create a target script project for the Google Apps Script Execution API (save the Target Script ID for configuration)
-
Turn on the Google Apps Script Execution API (save the OAuth Client ID for configuration)
NOTE: Jekyll's local development server runs on port 4000 by default. Set the Authorized JavaScript origins field to
http://localhost:4000
when creating the OAuth Client ID in the Google Development Console
- In
_config.yml
:
-
Set
production
option tofalse
-
Set the
executionApi include
option totrue
-
Set the
executionApi clientId
option to OAuth Client ID created in Step 2 -
Set the
executionApi scriptId
option to Script ID created in Step 1
-
Start/Restart the Jekyll server
-
Write Execution API calls
See
apiexample.html
and_includes/executionapi/executionapi.html
files for an example
PRODUCTION MODE:
Once the UI is ready ... export in Production Mode:
See
apiexample.html
and_includes/executionapi/gsapi.html
files for an example
- In
_config.yml
:
-
Set
production
option totrue
-
Set the
executionApi include
option totrue
- Start/Restart the Jekyll server and wait for site to build
jekyll serve
or
jekyll build
- Copy the generated
_site/apiexample/index.html
file (or your corresponding generated_site/.../index.html
) to the Google Apps Script environment
- This Jekyll theme builds the UI as a single
_site/index.html
file due to client-side CSS (_includes/css.html
), Javascript (_includes/js.html
) and (optional backend server code ..._includes/executionapi/gsapi.html
) being 'included' in the Jekyll build (see the Jekyll documentation on 'includes' for more information)
If you configure CSS, Javascript or backend server code to be a static asset in your your Jekyll build, remember to include these files in the production Google Apps Script project in addition to the generated
_site/index.html
file
- To change the title element in the generated UI html ... modify the
title
option in_config.yml
title: "Jekyll Google Apps Script Basic Theme"
- Any configuration changes to
_config.yml
require a Jekyll server restart.
Project is licensed MIT.