diff --git a/.clasp.json b/.clasp.json
index 941378d..2e69d42 100644
--- a/.clasp.json
+++ b/.clasp.json
@@ -1,4 +1,4 @@
{
"rootDir": "dist",
- "scriptId": "...paste scriptId here..."
+ "scriptId": "...add scriptId here..."
}
diff --git a/.eslintrc.json b/.eslintrc.json
new file mode 100644
index 0000000..8dafe48
--- /dev/null
+++ b/.eslintrc.json
@@ -0,0 +1,3 @@
+{
+ "parser": "babel-eslint"
+}
diff --git a/.npmrc b/.npmrc
new file mode 100644
index 0000000..4fd0219
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1 @@
+engine-strict=true
\ No newline at end of file
diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 0000000..b009dfb
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+lts/*
diff --git a/.prettierrc.json b/.prettierrc
similarity index 100%
rename from .prettierrc.json
rename to .prettierrc
diff --git a/README.md b/README.md
index d5452bb..c09848c 100644
--- a/README.md
+++ b/README.md
@@ -1,224 +1,185 @@
## React + Google Apps Script
-*Use this demo project as your boilerplate React app for HTML dialogs in Google Sheets, Docs and Forms.*
+*Use this project as your boilerplate for React apps inside Google Sheets, Docs and Forms pages.*
-This project uses labnol's excellent [apps-script-starter](https://github.com/labnol/apps-script-starter) as a starting point, adding support for React. It demonstrates how easy it is to build React apps that interact with Google Apps server-side scripts. Simply clone this project and modify the source code to get started developing with React for Google Apps Script client-side dialogs.
+This project uses labnol's excellent [apps-script-starter](https://github.com/labnol/apps-script-starter) as a starting point, and adds support for building React apps inside Google Sheets, Forms, and Docs pages. Simply clone this project and modify the source code to get started developing React apps with Google Apps Script.
*The demo app for Google Sheets shows insertion/deletion/activation of sheets through React-built HTML dialog.*
## Installation
-
-
1. Clone the sample project and install dependencies:
- ```
- > git clone https://github.com/enuchi/React-Google-Apps-Script.git
- > cd React-Google-Apps-Script
- > npm install
- ```
+ ```bash
+ > git clone https://github.com/enuchi/React-Google-Apps-Script.git
+ > cd React-Google-Apps-Script
+ > npm install
+ ```
2. Enable the Google Apps Script API [(script.google.com/home/usersettings)](https://script.google.com/home/usersettings):
-
+
+ 
-3. Log in to `clasp` to manage your Google Apps Scripts from the command line:
- ```
- > npm run login
- ```
+3. Log in to `clasp`, google's tool to help you manage your Google Apps Script projects from the command line.
+ ```bash
+ > npm run login
+ ```
4. Create a new Google Sheets file and a bound Google Scripts project for your React project:
- ```
- > npm run setup
- Created new Google Sheet: https://drive.google.com/open?id=1lVQUPZ*************************************
- Created new Google Sheets Add-on script: https://script.google.com/d/1K7MPtCH*************************************-**/edit
- ```
- You've created a new Sheet and attached Script file! (But they're still empty for now.) See the notes below if you want to use an existing Google Sheet and Script instead of creating a new one.
-5. Build the app and deploy!
- ```
- > npm run deploy
- ```
- You can now visit your Google Sheet and see your new React app.
+ ```bash
+ > npm run setup
+
+ Created new Google Sheet: https://drive.google.com/open?id=1lVQUPZ*************************************
+ Created new Google Sheets Add-on script: https://script.google.com/d/1K7MPtCH*************************************-**/edit
+ ```
+ This will use `clasp` to create a new Google Sheets spreadsheet and a 'bound' Google Apps Script project, and save the credentials to the `.clasp.json` file in your root directory. If you don't want to create a new spreadsheet and script, and instead want to use this project with an existing project, [see the section below](#Using-an-existing-Sheet).
+
+ Okay, now you've created a new sheet and bound script file! (But they're still empty for now.)
+
+5. Deploy the app!
+ ```bash
+ > npm run deploy
+ ```
+ Open your new spreadsheet in Google Sheets. Your new React app will be available from a new menu item!
### Using an existing Sheet
-The above installation instructions create a new Google Sheets spreadsheet and 'bound' Apps Script, and saves the credentials to a `.clasp.json` file in the root directory. If you want to use an existing sheet's script file, then simply copy the scriptId into the `.clasp.json` file as below. You can find the script's scriptId by opening your sheet, selecting **Tools > Script Editor**, then **File > Project properties**.
+If you want to use an existing google script for your project:
+1. Copy the existing script project's `scriptId`. You can find it by opening your sheet, selecting **Tools > Script Editor**, then **File > Project properties**.
+
+2. Run the command below to add the existing project's `scriptId` to your`.clasp.json` file. (You can also just edit the `.clasp.json` file directly. Make sure not to remove `"rootDir": "dist"` from the `.clasp.json` file.)
+
+ ```bash
+ # If your scriptId is 1K7MPtCHkjasdf93238234asdKFDF3sa9 then run
+ > npm run setup:use-id 1K7MPtCHkjasdf93238234asdKFDF3sa9
+ ```
-Paste the `scriptId` into the `.clasp.json` file. *Make sure to include `"rootDir": "dist"` in this file:
-```
-// .clasp.json
-{"rootDir": "dist", "scriptId":"...paste scriptId here..."}
-```
### Making changes to the code
-Modify the server-side and client-side source code in the `src` folder using ES6/7 and React. Change the scopes in `appsscript.json` if needed. When you're ready, build the app and deploy! You can run `npm run deploy` to build and deploy, or `npm run build` just to build the bundled files in the `./dist` directory.
+Modify the server-side and client-side source code in the `src` folder. [Add any additional scopes](https://developers.google.com/apps-script/concepts/scopes) to `appsscript.json` as needed. When you're ready, build the app and deploy! You can run `npm run deploy` to build and deploy, or `npm run build` just to build the bundled files in the `./dist` directory.
## The sample app
Insert/activate/delete sheets through a simple HTML dialog, built with React. Access the dialog through the new menu item that appears. You may need to refresh the spreadsheet and approve the app's permissions the first time you use it.
-## How it works
-"[Google Apps Script](https://en.wikipedia.org/wiki/Google_Apps_Script) is based on JavaScript 1.6 with some portions of 1.7 and 1.8 and provides subset of ECMAScript 5 API."
-
-That means many JavaScript tools used today in modern web development will not work in the Google Apps Script environment, including `let`/`const` declarations, arrow functions, spread operator, etc.
-
-This project circumvents those restrictions by transpiling newer code to older code that Google Apps Script understands using Babel, and also bundles separate files and modules using Webpack.
-
-On the client-side, Google Apps Scripts has restrictions on the way HTML dialogs are used. While in normal web development you can simply reference a separate css file, e.g.
-```
-
-```
-in the Google Apps Script environment you need to use [HTML templates](https://developers.google.com/apps-script/guides/html/templates), which can be cumbersome to work with. With this project, all files are bundled together by inlining .css and .js files. Using a transpiler and bundling tool also allows us to use JSX syntax, and external libraries such as React.
## Features
-- Support for JSX syntax:
-```
-return
Name: {person.firstName}
-```
- Support for external packages. Simply install with npm or from a file and `import`:
-```
-$ npm install react-addons-css-transition-group
-```
-```
-// index.jsx
-import ReactCSSTransitionGroup from 'react-addons-css-transition-group';
-```
-- `import` CSS from another file:
-```
-import "./styles.css";
-```
- - Use promises with e.g. `.then`/`.catch` instead of `google.script.run`:
- ```
-// instead of this:
-google.script.run
- .withSuccessHandler(successHandler)
- .withFailureHandler(failureHandler)
- .getSheetsData()
-
-// you can do this:
-import server from '../server';
-// access all your server functions here:
-const { getSheetsData } = server;
-addSheet(newSheetTitle)
- .then(successHandler)
- .catch(failureHandler);
+ ```bash
+ > npm install react-transition-group
```
-How does this work? We rewrite `google.script.run` to support Promises:
-```
-// ./src/client/server.js
+ ```js
+ // index.jsx
+ import { TransitionGroup, CSSTransition } from 'react-transition-group';
+ ```
+- `import` CSS from another file:
+ ```js
+ import "./styles.css";
+ ```
+ - Use promises to call and handle responses from the server instead of using `google.script.run`:
+ ```js
+ // Google's documentation wants you to do this. Boo.
+ google.script.run
+ .withSuccessHandler(response => doSomething(response))
+ .withFailureHandler(err => handleError(err))
+ .addSheet(sheetTitle)
-const serverMethods = {};
-// skip the reserved methods
-const ignoredMethods = [
- 'withFailureHandler',
- 'withLogger',
- 'withSuccessHandler',
- 'withUserObject',
-];
+ // Poof! With a little magic we can now do this:
+ import server from '../server';
-for (const method in google.script.run) {
- if (!ignoredMethods.includes(method)) {
- serverMethods[method] = (...args) => {
- return new Promise((resolve, reject) => {
- google.script.run
- .withSuccessHandler(resolve)
- .withFailureHandler(reject)[method](...args);
- });
- };
- }
-}
-export default serverMethods;
-```
-Now we can use familiar Promises in our client-side code and have easy access to all server functions!
+ // We now have access to all our server functions, which return promises!
+ const { addSheet } = server;
+ addSheet(sheetTitle)
+ .then(response => doSomething(response))
+ .catch(handleError(err));
-- Use newer ES6/7 code, including arrow functions, spread operators, `const`/`let`, and more:
-```
-const getSheetsData = () => {
- let activeSheetName = getActiveSheetName();
- return getSheets().map((sheet, index) => {
- let sheetName = sheet.getName();
- return {
- text: sheetName,
- sheetIndex: index,
- isActive: sheetName === activeSheetName,
- };
- });
-};
-```
-## Tern support
-This project includes support for GAS definitions and autocomplete through a [Tern](http://ternjs.net/) plugin. Tern is a code-analysis engine for JavaScript, providing many useful tools for developing. See Tern's site for setup instructions for many popular code editors, such as Sublime, Vim and others.
+ // Or we can use async/await:
+ async () => {
+ try {
+ const response = await addSheet(sheetTitle);
+ doSomething(response);
+ } catch (err) {
+ handleError(err)
+ }
+ }
+ ```
+Now we can use familiar Promises in our client-side code and have easy access to all server functions. See [the code](./src/client/server.js) for the implementation details.
-Tern provides many indispensable tools for working with Google Apps Script, such as autocompletion on variables and properties, function argument hints and querying the type of an expression.
+## Full Autocompletion
+This project includes support for the full autocompletion and type definitions.
-- Autocomplete example. Lists all available methods from the appropriate Google Apps Script API:
-
+
+- Lists all available methods from the appropriate Google Apps Script API:
- Full definitions with links to official documentation, plus information on argument and return type:
-
-
## Extending this app
- You can split up server-side code into multiple files and folders using `import` and `export` statements.
- Make sure to expose all public functions including `onOpen` and any functions you are calling from the client. Example below shows assignment to `global` object:
-```
-const onOpen = () => {
- SpreadsheetApp.getUi() // Or DocumentApp or FormApp.
- .createMenu('Dialog')
- .addItem('Add sheets', 'openDialog')
- .addToUi();
-}
+ ```js
+ const onOpen = () => {
+ SpreadsheetApp.getUi() // Or DocumentApp or FormApp.
+ .createMenu('Dialog')
+ .addItem('Add sheets', 'openDialog')
+ .addToUi();
+ }
-global.onOpen = onOpen
-```
+ global.onOpen = onOpen
+ ```
- You may wish to remove automatic linting when running Webpack. You can do so by editing the Webpack config file and commenting out the eslintConfig line in client or server settings:
-```
-// webpack.config.js
+ ```js
+ // webpack.config.js
-const clientConfig = Object.assign({}, sharedConfigSettings, {
- ...
- module: {
- rules: [
- // eslintConfig,
- {
-```
+ const clientConfig = Object.assign({}, sharedConfigSettings, {
+ ...
+ module: {
+ rules: [
+ // eslintConfig,
+ {
+ ```
## Multiple dialogs
-This project now supports multiple dialogs and sidebars. Here is an example of the `server` code for a 'main.html' dialog and an 'about.html' sidebar:
-```
-// ./src/server/sheets-utilities.js
+This project now supports multiple dialogs and sidebars. See the `server` code at [src/server/ui.js](./src/server/ui.js) for a 'main.html' dialog and an 'about.html' sidebar:
+```js
+// ./src/server/ui.js
-const openDialog = () => {
+export const onOpen = () => {
+ SpreadsheetApp.getUi()
+ .createMenu('My Sample React Project') // edit me!
+ .addItem('Sheet Name Editor', 'openDialog')
+ .addItem('About me', 'openAboutSidebar')
+ .addToUi();
+};
+
+export const openDialog = () => {
const html = HtmlService.createHtmlOutputFromFile('main')
.setWidth(400)
.setHeight(600);
- SpreadsheetApp
- .getUi() // Or DocumentApp or FormApp.
- .showModalDialog(html, 'Sheet Editor');
+ SpreadsheetApp.getUi().showModalDialog(html, 'Sheet Editor');
};
-const openAboutSidebar = () => {
+export const openAboutSidebar = () => {
const html = HtmlService.createHtmlOutputFromFile('about');
- SpreadsheetApp
- .getUi()
- .showSidebar(html);
+ SpreadsheetApp.getUi().showSidebar(html);
};
```
And here is the configuration in webpack that creates multiple html files. You will need to edit this if you want to add more dialog html files:
-```
+```js
// ./webpack.config.js
// Client entrypoints:
const clientEntrypoints = [
{
- name: "CLIENT - main dialog",
- entry: "./src/client/main.jsx",
- filename: "main.html"
+ name: 'CLIENT - main dialog',
+ entry: './src/client/MainDialog.jsx',
+ filename: 'main.html',
},
{
- name: "CLIENT - about sidebar",
- entry: "./src/client/about.jsx",
- filename: "about.html"
+ name: 'CLIENT - about sidebar',
+ entry: './src/client/AboutDialog.jsx',
+ filename: 'about.html',
},
];
```
## Suggestions
-Open a pull request!
+Pull requests welcome!
diff --git a/dist/about.html b/dist/about.html
index 3abb4cf..7bcef36 100644
--- a/dist/about.html
+++ b/dist/about.html
@@ -7,5 +7,5 @@
-