Initial commit

CONTRIB.md

@@ -0,0 +1,35 @@
+# How to become a contributor and submit your own code
+
+## Contributor License Agreements
+
+We'd love to accept your sample apps and patches! Before we can take them, we
+have to jump a couple of legal hurdles.
+
+Please fill out either the individual or corporate Contributor License Agreement
+(CLA).
+
+  * If you are an individual writing original source code and you're sure you
+    own the intellectual property, then you'll need to sign an [individual CLA]
+    (https://developers.google.com/open-source/cla/individual).
+  * If you work for a company that wants to allow you to contribute your work,
+    then you'll need to sign a [corporate CLA]
+    (https://developers.google.com/open-source/cla/corporate).
+
+Follow either of the two links above to access the appropriate CLA and
+instructions for how to sign and return it. Once we receive it, we'll be able to
+accept your pull requests.
+
+## Contributing A Patch
+
+1. Submit an issue describing your proposed change to the repo in question.
+1. The repo owner will respond to your issue.
+1. If your proposed change is accepted, and you haven't already done so, sign a
+   Contributor License Agreement (see details above).
+1. Fork the desired repo, develop and test your code changes.
+1. Ensure that your code adheres to the existing style in the sample to which
+   you are contributing. Refer to the
+   [Google Cloud Platform Samples Style Guide]
+   (https://github.com/GoogleCloudPlatform/Template/wiki/style.html) for the
+   recommended coding standards for this organization.
+1. Ensure that your code has an appropriate set of unit tests which all pass.
+1. Submit a pull request.

README.md

@@ -0,0 +1,61 @@
+Apps Script Mobile Add-ons
+==========================
+
+Android applications that interact with the Google Docs and Sheets
+editor apps, and use the
+[Apps Script Execution API](https://developers.google.com/apps-script/guides/)
+to call Apps Script functions to interact with Google services.
+
+Introduction
+------------
+
+Google Apps Script now allows developers to construct mobile add-ons --
+Android applications which extend and support Google Docs and Sheets.
+
+This repository contains sample mobile add-ons that are meant to
+provide an example of a mobile add-on's project structure.
+
+Learn more
+----------
+
+To continue learning about mobile add-ons for Google Docs and Sheets,
+take a look at the following resources:
+
+* [Mobile Add-ons](https://developers.google.com/apps-script/add-ons/mobile)
+* [Apps Script Execution API](https://developers.google.com/apps-script/guides/)
+
+Support
+-------
+
+For general Apps Script support, check the following:
+
+- Stack Overflow Tag: [google-apps-script](http://stackoverflow.com/questions/tagged/google-apps-script)
+- Issue Tracker: [google-apps-script-issues](https://code.google.com/p/google-apps-script-issues/issues/list)
+
+If you've found an error in this sample, please file an issue:
+https://github.com/googlesamples/apps-script-mobile-addons
+
+Patches are encouraged, and may be submitted by forking this project and
+submitting a pull request through GitHub.
+
+License
+-------
+
+Copyright 2016 Google, Inc.
+
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.

mobile-translate/Code.gs

@@ -0,0 +1,245 @@
+/**
+ * @OnlyCurrentDoc
+ *
+ * The above comment directs Apps Script to limit the scope of file
+ * access for this add-on. It specifies that this add-on will only
+ * attempt to read or modify the files in which the add-on is used,
+ * and not all of the user's files. The authorization request message
+ * presented to users will reflect this limited scope.
+ */
+
+/**
+ * Creates a menu entry in the Google Docs UI when the document is opened.
+ * This method is only used by the regular add-on, and is never called by
+ * the mobile add-on version.
+ *
+ * @param {object} e The event parameter for a simple onOpen trigger. To
+ *     determine which authorization mode (ScriptApp.AuthMode) the trigger is
+ *     running in, inspect e.authMode.
+ */
+function onOpen(e) {
+  DocumentApp.getUi().createAddonMenu()
+      .addItem('Start', 'showSidebar')
+      .addToUi();
+}
+
+/**
+ * Runs when the add-on is installed.
+ * This method is only used by the regular add-on, and is never called by
+ * the mobile add-on version.
+ *
+ * @param {object} e The event parameter for a simple onInstall trigger. To
+ *     determine which authorization mode (ScriptApp.AuthMode) the trigger is
+ *     running in, inspect e.authMode. (In practice, onInstall triggers always
+ *     run in AuthMode.FULL, but onOpen triggers may be AuthMode.LIMITED or
+ *     AuthMode.NONE.)
+ */
+function onInstall(e) {
+  onOpen(e);
+}
+
+/**
+ * Opens a sidebar in the document containing the add-on's user interface.
+ * This method is only used by the regular add-on, and is never called by
+ * the mobile add-on version.
+ */
+function showSidebar() {
+  var ui = HtmlService.createHtmlOutputFromFile('Sidebar')
+      .setTitle('Translate');
+  DocumentApp.getUi().showSidebar(ui);
+}
+
+/**
+ * Gets the text the user has selected. If there is no selection,
+ * this function displays an error message.
+ *
+ * @return {Array.<string>} The selected text.
+ */
+function getSelectedText() {
+  var selection = DocumentApp.getActiveDocument().getSelection();
+  if (selection) {
+    var text = [];
+    var elements = selection.getSelectedElements();
+    for (var i = 0; i < elements.length; i++) {
+      if (elements[i].isPartial()) {
+        var element = elements[i].getElement().asText();
+        var startIndex = elements[i].getStartOffset();
+        var endIndex = elements[i].getEndOffsetInclusive();
+
+        text.push(element.getText().substring(startIndex, endIndex + 1));
+      } else {
+        var element = elements[i].getElement();
+        // Only translate elements that can be edited as text; skip images and
+        // other non-text elements.
+        if (element.editAsText) {
+          var elementText = element.asText().getText();
+          // This check is necessary to exclude images, which return a blank
+          // text element.
+          if (elementText != '') {
+            text.push(elementText);
+          }
+        }
+      }
+    }
+    if (text.length == 0) {
+      throw 'Please select some text.';
+    }
+    return text;
+  } else {
+    throw 'Please select some text.';
+  }
+}
+
+/**
+ * Gets the stored user preferences for the origin and destination languages,
+ * if they exist.
+ * This method is only used by the regular add-on, and is never called by
+ * the mobile add-on version.
+ *
+ * @return {Object} The user's origin and destination language preferences, if
+ *     they exist.
+ */
+function getPreferences() {
+  var userProperties = PropertiesService.getUserProperties();
+  var languagePrefs = {
+    originLang: userProperties.getProperty('originLang'),
+    destLang: userProperties.getProperty('destLang')
+  };
+  return languagePrefs;
+}
+
+/**
+ * Gets the user-selected text and translates it from the origin language to the
+ * destination language. The languages are notated by their two-letter short
+ * form. For example, English is 'en', and Spanish is 'es'. The origin language
+ * may be specified as an empty string to indicate that Google Translate should
+ * auto-detect the language.
+ *
+ * @param {string} origin The two-letter short form for the origin language.
+ * @param {string} dest The two-letter short form for the destination language.
+ * @param {boolean} savePrefs Whether to save the origin and destination
+ *     language preferences.
+ * @return {Object} Object containing the original text and the result of the
+ *     translation.
+ */
+function getTextAndTranslation(origin, dest, savePrefs) {
+  var result = {};
+  var text = getSelectedText();
+  result['text'] = text.join('\n');
+
+  if (savePrefs == true) {
+    var userProperties = PropertiesService.getUserProperties();
+    userProperties.setProperty('originLang', origin);
+    userProperties.setProperty('destLang', dest);
+  }
+
+  result['translation'] = translateText(result['text'], origin, dest);
+
+  return result;
+}
+
+/**
+ * Replaces the text of the current selection with the provided text, or
+ * inserts text at the current cursor location. (There will always be either
+ * a selection or a cursor.) If multiple elements are selected, only inserts the
+ * translated text in the first element that can contain text and removes the
+ * other elements.
+ *
+ * @param {string} newText The text with which to replace the current selection.
+ */
+function insertText(newText) {
+  var selection = DocumentApp.getActiveDocument().getSelection();
+  if (selection) {
+    var replaced = false;
+    var elements = selection.getSelectedElements();
+    if (elements.length == 1 &&
+        elements[0].getElement().getType() ==
+        DocumentApp.ElementType.INLINE_IMAGE) {
+      throw "Can't insert text into an image.";
+    }
+    for (var i = 0; i < elements.length; i++) {
+      if (elements[i].isPartial()) {
+        var element = elements[i].getElement().asText();
+        var startIndex = elements[i].getStartOffset();
+        var endIndex = elements[i].getEndOffsetInclusive();
+
+        var remainingText = element.getText().substring(endIndex + 1);
+        element.deleteText(startIndex, endIndex);
+        if (!replaced) {
+          element.insertText(startIndex, newText);
+          replaced = true;
+        } else {
+          // This block handles a selection that ends with a partial element. We
+          // want to copy this partial text to the previous element so we don't
+          // have a line-break before the last partial.
+          var parent = element.getParent();
+          parent.getPreviousSibling().asText().appendText(remainingText);
+          // We cannot remove the last paragraph of a doc. If this is the case,
+          // just remove the text within the last paragraph instead.
+          if (parent.getNextSibling()) {
+            parent.removeFromParent();
+          } else {
+            element.removeFromParent();
+          }
+        }
+      } else {
+        var element = elements[i].getElement();
+        if (!replaced && element.editAsText) {
+          // Only translate elements that can be edited as text, removing other
+          // elements.
+          element.clear();
+          element.asText().setText(newText);
+          replaced = true;
+        } else {
+          // We cannot remove the last paragraph of a doc. If this is the case,
+          // just clear the element.
+          if (element.getNextSibling()) {
+            element.removeFromParent();
+          } else {
+            element.clear();
+          }
+        }
+      }
+    }
+  } else {
+    var cursor = DocumentApp.getActiveDocument().getCursor();
+    var surroundingText = cursor.getSurroundingText().getText();
+    var surroundingTextOffset = cursor.getSurroundingTextOffset();
+
+    // If the cursor follows or preceds a non-space character, insert a space
+    // between the character and the translation. Otherwise, just insert the
+    // translation.
+    if (surroundingTextOffset > 0) {
+      if (surroundingText.charAt(surroundingTextOffset - 1) != ' ') {
+        newText = ' ' + newText;
+      }
+    }
+    if (surroundingTextOffset < surroundingText.length) {
+      if (surroundingText.charAt(surroundingTextOffset) != ' ') {
+        newText += ' ';
+      }
+    }
+    cursor.insertText(newText);
+  }
+}
+
+
+/**
+ * Given text, translate it from the origin language to the destination
+ * language. The languages are notated by their two-letter short form. For
+ * example, English is 'en', and Spanish is 'es'. The origin language may be
+ * specified as an empty string to indicate that Google Translate should
+ * auto-detect the language.
+ *
+ * @param {string} text text to translate.
+ * @param {string} origin The two-letter short form for the origin language.
+ * @param {string} dest The two-letter short form for the destination language.
+ * @return {string} The result of the translation, or the original text if
+ *     origin and dest languages are the same.
+ */
+function translateText(text, origin, dest) {
+  if (origin === dest) {
+    return text;
+  }
+  return LanguageApp.translate(text, origin, dest);
+}