Goal:
- Have the class work together to create a Google Document App Script that will automatically change the background color of the document if it reaches a certain number of words.
Working Example: Word Limit Notifier
- If you would like to see the full code, then create a copy, and go to Tools => Script Editor.
- There is a Group Tasks file that includes completed examples of each groups scripts.
- Learning how to code is best done by looking at other examples. However there is always a thin line between looking at other's code to learn and taking it all-to-gather. I suggest leaving it up on the teachers machine for students to reference. Just extrapolating the information that is pertinent to them is an important skill in coding.
Tasks:
- As a Group create a function.
- function getCharacterLimit(){
var labelTxt = "The length: ";
var ad = DocumentApp.getActiveDocument();
var text = ad.getBody().getText();
var lenghth = text.length;
Logger.log(lenghth);
} - Split the class into groups; each group is responsible for their section of the script.
- Sections / Groups
- User Interface: This group is responsible for creating the menu, dialogues and prompts. The information they capture will need to be saved as a variable.
- Prompt: "Set Count" ~ log the result
- Prompt: "Set bgColor" ~ log the result
- Run: "Force Check"
- Alert: "Current Count" ~ Multiline alert that will eventually include "Max Allowed Words:", "Background Color:", "Word Count:".
- Take it further: Use HtmlService instead of getUi to create the dialogue.
- Documentation
- Save hidden information: This group will be charged with learning how to save variable information using the PropertiesService so that it can be used the next time the document is opened.
- Save the Set Count
- Save the Set bgColor
- Retrieve the Set Count
- Retrieve the bgColor
- Take it further: Learn to save information as an object using JSON.stringify() and JSON.parse().
- Properties Service Documentation
- Triggers: Triggers tells the script to do something at a particular time or interval. In the scripts case it will be checking the word count and if it is above the set count then it will change the background.
- Set a trigger to run a function that adds to the log every minute: (1 minute is the minimum amount of time a trigger can launch consecutively.
- Check to see if the trigger has already been installed.
- Find out at what point the trigger should be installed in the completed script.
- Take it further: Set date triggers, and learn about simple vs programmed triggers.
- Trigger Documentation
- Get the Word Count & Change the Background Color: There is no program key that gives you the word count, so to complete this you will need to think of ways to accomplish getting at least a rough estimate of how many words. Secondly you will want to be able to change the background color of the document.
- Get the current word count and write it to the log
- Take it further: Capture other information like character count or how many times the word "The" appears and see if you can log that information also.
- Write a function that will change the background color.
- Take it further: Find other attributes that you can change.
- Documentation
- Bring it together:
- In a class discussion format, or individually as homework have the students take all the different parts and put them together into a single script.
- Take it further: Add in checks to prevent user error.
- Take it further: Improve the user interface to make it simpler for the end user.
Glossary Of Terms:
- Function: A section of code that can be run by itself.
- Variable: A word or letter that information gets stored to so that it can be accessed within a function.
- Trigger: An event that fires at a particular time or interval.
- String: Information stored as plain text. (var aString = "";)
- Object: Used for storing information in a complex format. (var someObject = {};)
- Array: This is a group of information that can be accessed one after another. (var anArray = [];)
- API: The different commands that can be run to build your script.
- Comment: A section of the code that does not run.
- Log: A place to store information while you are developing.
Import things to know:
- Each link of code ends with a semi-colon. A line of code may take up severs lines on the document, but when it is read by the application, it looks for the semi-colon to know when it actually ends.
- Functions have a format of: function functionName(){ code goes here }
- Variables can be passed between functions, by placing them inside the ( )'s.
- Periods are used to add a sub-API event to the root API. DocumentApp.getUi();
- Save and test often.
- Most of App Scripting is based off of Javascript.
Important Links:
- API reference ~ Primary documentation that lists of all the commands that can be run (Also found in the Help menu of the script)
- StackOverFlow.com ~ Scripting forum used to get or provide help with scripts.
- Issue Tracker ~ Used to list any bugs found in the API's.
