Tutorial 4: Call Scripts

Intermediate App Maker skills

About 10 minutes

What you’ll build

You’ll build an app that lets a user compose and send a rich-text (HTML) email message. The app uses both client scripts and server scripts.

What you’ll learn

This tutorial teaches you how to:

• Create and call a client script
• Create and call a server script
• Use the value of a Text Editor widget and send an email message with an HTML body.

Create your app

1. Sign in to the G Suite account provided by your employer or school.
2. Open App Maker.
3. Create a blank app:
   • If App Maker displays the welcome dialog, click Create New App.
   • Otherwise, click Menu New Blank Application.
4. Rename the app. Delete the default name, Untitled App, and enter Email Sender.

Create the UI

You’ll build a form that looks like this:

To create this UI:

1. Rename the page:

   1. In the left sidebar, hover over NewPage and click More Rename.

   2. Enter Email and click OK.

      Tip: Valid characters are letters, nonleading numbers, and nonleading underscores.

2. Add a text box for the recipient:

   1. Click Widgets and drag a Text Box near the top-left corner of the canvas.

   2. Drag the right handle to increase the length of the text box.

   3. In the Property Editor, change the name property of the text box to To and enter To: as the label property.

3. Add a text box for the subject:

   1. Click Widgets and drag a Text Box below the To text box.

   2. Drag the right handle to increase the length of the text box.

   3. In the Property Editor, change the name property of the text box to Subject and enter Subject: as the label property.

4. Add a text editor for the body of the email message:

   1. Click Widgets and drag a Text Editor below the Subject text box.

   2. In the Property Editor, change the name property of the text editor to Msg.

      Tip: For plain-text entry, you could use a Text Area widget.

5. Add a button for the user to click to send the email message:

   1. From Widgets , drag a Button onto the canvas to the right of the To text box. Double-click the button and rename it to Send Email.

6. Define an action to take when a user clicks the Send Email button.

   1. Click Send Email.

   2. In the Property Editor Button section, click the onClick property and select Custom Action.

   3. Use JavaScript to define the action. In the Client Script dialog, copy and paste this script:

          var widgets = widget.parent.descendants;
      var to = widgets.To.value;
      var subject = widgets.Subject.value;
      var msg = widgets.Msg.value;
      widgets.EmailStatus.text = 'Sending email...';
      sendMessage(to, subject, msg); 

      In the action, note the following references to App Maker objects and properties:
      • widget.parent.descendants—The parent widget of the Send Email button is the top-level panel for the page. The descendants of that panel include all widgets on the page.
      • widgets.To.value, widgets.Subject.value, widgets.Msg.value, and widgets.EmailStatus.text—The value properties of three widgets and the text property of a fourth.

   4. Press Esc to close the dialog.

7. Add a button for the user to click to clear all fields on the form:

   1. From Widgets , drag a Button onto the canvas below the text editor. Double-click the button and rename it to Clear Form.

8. Define an action to take when a user clicks the Clear Form button.

   1. Click Clear Form.

   2. In the Property Editor Button section, click the onClick property and select Custom Action.

   3. Use JavaScript to define the action. In the Client Script dialog, copy and paste this script:

      clearEmailForm();

9. Add a label for the status:

   1. From Widgets , drag a Label onto the canvas below the text box.

   2. In the Property Editor, set the name property to EmailStatus. Delete the text property.

10. Click Close to close Widgets.

Learn about the scripts the app will use

In this step, you’ll copy and paste the JavaScript functions that your app needs to send email and clear the form into scripts in your app. Scripts are containers in App Maker that are similar to script files:

• Client script—Contains JavaScript that the browser’s JavaScript engine runs.
• Server script—Contains JavaScript that a JavaScript engine on the App Maker server runs.

Tip: You could put all client JavaScript functions in one client script and all server JavaScript functions in a single server script, however, we recommend that you organize your JavaScript functions in multiple scripts. For example, place important functions in separate scripts and auxiliary functions in the related scripts.

Client script functions

clearEmailForm

The clearEmailForm function clears the entire email form.

sendMessage

The sendMessage function:

• Calls the sendEmailMessage server script to send the email message
• Calls the clearEmailForm client script to clear the email form

Server script function

sendEmailMessage

The sendEmailMessage server script function calls the MailApp.sendEmail function to send the email message. The htmlBody option of MailApp.sendEmail indicates that the body of the message is HTML.

Create a client script

1. Create a client script to contain the functions that the client will run.

   1. Hover over Scripts and click to add a script.

   2. When the Create script dialog appears, leave Client selected, uncheck Generate sample code, and click Create.

2. Rename the client script:

   1. In the left sidebar, hover over NewScript and click More Rename.

   2. Enter ClientScript and click OK.

3. Copy and paste this JavaScript into ClientScript:

   /**
   * Clears the entire email form
   */
   function clearEmailForm(){
     var formWidgets = app.pages.Email.descendants;
     formWidgets.EmailStatus.text = "";
     formWidgets.To.value = "";
     formWidgets.Subject.value = "";
     formWidgets.Msg.value = "";
   }
   /**
   * Sends an email message.
   * @param {string} to - Message recipient
   * @param {string} subject - Message subject
   * @param {string} msg - Body of message (HTML from Text Editor)
   */
   function sendMessage(to, subject, msg){
     var status = app.pages.Email.descendants.EmailStatus;
     google.script.run
      .withFailureHandler(function(error) {
         // An error occurred, so display an error message.
         status.text = error.message;
       })
     .withSuccessHandler(function(result) {
        // Report that the email was sent.
        status.text = 'Email sent...';
     clearEmailForm();
      })
    .sendEmailMessage(to, subject, msg);
   }
   

Note the object reference app.pages.Email.descendants, which references all objects that are descendants of the Email page, that is, all widgets. In this app, this reference is an alternative to the equivalent reference (widget.parent.descendants) used in the onClick action of the Send Email button. (Whether these references are equivalent depends on the object hierarchy.)

Create a server script

1. Create a server script to contain the function that the server will run:

   1. Hover over Scripts and click to add a script.

   2. When the Create Script dialog appears, click Server, leave Generate sample code unchecked, and click Create.

2. Rename the server script:

   1. In the left sidebar, hover over NewScript and click More Rename.

   2. Enter ServerScript and click OK.

3. Copy and paste this JavaScript into ServerScript:

    /**
     * Sends an email message.
     * @param {string} to - Message recipient
     * @param {string} subject - Message subject
     * @param {string} msg - Body of message (HTML from Text Editor)
     * The body of the message is not a complete HTML document. It
     * doesn't need to be. When calling MailApp.sendEmail, you do
     * need to specify the option htmlBody for the message body, so that
     * MailApp.sendEmail will include the correct Content-Type header.
     */
    function sendEmailMessage(to, subject, msg){
      MailApp.sendEmail(to, subject, msg, {htmlBody: msg});
    }
   

   Note how the recipient, subject, and message are passed to the function that actually sends the email. The action defined for the onClick property of the Send Email button calls the SendMessage function in the client script, passing to the function the recipient, subject, and message. The SendMessage function passes these same arguments to the sendEmailMessage function in the server script, which passes the arguments to the MailApp.SendMail function. The MailApp.SendMail function sends the email.

Preview and test your app

Preview your Send Email app to see it in action.

1. In the top-right corner, click Preview to run your app in a new browser tab.
2. Click Allow to allow your app to use specific information.
3. Enter an email address and a subject.
4. In the Text Editor, type a brief message.
5. Click Clear Form. Now you have to start over.
6. Enter an email address and a subject.
7. In the Text Editor, type a brief message.
8. Use tools in the Text Editor toolbar to style your message.
9. Click Send Email. The Send Email app sends the email and clears the form.

Congratulations! You’ve just built an App Maker app that uses client scripts and a server script to send email.

Next steps

1. Take Tutorial 5—Learn about relations.
2. Learn more about App Maker scripts.
3. Explore other applications in the App Maker Samples list.

4. Find out more about this tutorial’s key concepts; for example:

   • Discover more about Apps Script.

   • Read more about different types of callbacks.