Google Apps Script is, first and foremost, a tool for making Google Apps more powerful — and today’s addition of programmatic control over data-validation rules in Google Sheets is a perfect example. For a quick demo, make a copy of this spreadsheet, then follow the instructions provided.

For the last few months, scriptable access to the data validation feature in Sheets has been the most requested feature on the Apps Script issue tracker. A common use for data-validation rules is to require that a cell’s value match one of the values in a different range. The following example shows how to achieve that goal with Apps Script. First, we use the newDataValidation() method to construct a DataValidationBuilder, then set the appropriate options and apply the final DataValidation with setDataValidation().

// Set the data-validation rule for cell A1 to require a value from B1:B10.
var cell = SpreadsheetApp.getActive().getRange('A1');
var range = SpreadsheetApp.getActive().getRange('B1:B10');
var rule = SpreadsheetApp.newDataValidation().requireValueInRange(range)
    .build();
cell.setDataValidation(rule);

It’s also possible to modify existing data-validation rules. The next example changes rules that require a date in 2013 to require a date in 2014 instead. You’ll see that the script calls getDataValidations() to retrieve the existing rules, then uses getCriteriaType(), getCriteriaValues(), and the DataValidationCriteria enum to examine the rules before applying the new date restriction via the advanced withCriteria() method.

// Change existing data-validation rules that require a date in 2013
// to require a date in 2014.
var oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
var newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
var rules = range.getDataValidations();

for (var i = 0; i < rules.length; i++) {
  for (var j = 0; j < rules[i].length; j++) {
    var rule = rules[i][j];

    if (rule != null) {
      var criteria = rule.getCriteriaType();
      var args = rule.getCriteriaValues();

      if (criteria == SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN
          && args[0].getTime() == oldDates[0].getTime() 
          && args[1].getTime() == oldDates[1].getTime()) {
        rules[i][j] = rule.copy().withCriteria(criteria, newDates).build();
      }
    }
  }
}
range.setDataValidations(rules);

With this new feature in Apps Script, you should find it much easier to manage complex data-validation scenarios. Please keep the feature requests coming!

Asim Fazal   profile Asim is a software engineer on the Google Sheets team in New York — and an enthusiastic occasional contributor to the Apps Script team.

For developers, part of the simplicity of Apps Script has always been that authorization requires zero setup — but we heard from users that the process required too many clicks. At Google I/O this year, we launched an opt-in version of an easier authorization flow; today, that new flow becomes the default for all new scripts.

Besides being prettier and easier, the new flow offers benefits behind the scenes: it allows more scripts to be simultaneously authorized on the same account, which means you shouldn’t need to reauthorize a script unless the code changes substantially.

For developers who use the advanced Google services, the new flow also gets rid of some manual steps that were previously required. Every new script now automatically creates a project in the Google APIs Console — no more messing with secret keys!

If you want the same experience for your existing scripts, you can upgrade them manually in just a few seconds.

Steve Lieberman   profile Steve is an engineer on the Apps Script team in NYC. Before joining Google, he developed financial-trading systems and researched automatically-parallelizing compilers.

Many developers have come to prefer JSON for data serialization, but we recognize that good ol' XML is still an important format for many Apps Script users. Our existing XML service is good at parsing XML, but has limited ability to create or alter existing documents. In order to provide a more complete and consistent experience, we have created a new XML service, which launches today. The new service is accessed using XmlService, in contrast to the old service which was simply called Xml.

Let's take a look at how you can use the new service to create an XML representation of the emails in your Gmail inbox.

function createXml() {
  var root = XmlService.createElement('threads');
  var threads = GmailApp.getInboxThreads();
  for (var i = 0; i < threads.length; i++) {
    var child = XmlService.createElement('thread')
        .setAttribute('messageCount', threads[i].getMessageCount())
        .setAttribute('isUnread', threads[i].isUnread())
        .setText(threads[i].getFirstMessageSubject());
    root.addContent(child);
  }
  var document = XmlService.createDocument(root);
  var xml = XmlService.getPrettyFormat().format(document);
  Logger.log(xml);
}

The code above logs XML that looks something like this:

<?xml version="1.0" encoding="UTF-8"?>
<threads>
  <thread messageCount="1" isUnread="true">
    Can't wait for the new XML service!
  </thread>
  <thread messageCount="1" isUnread="true">
    50% off all widgets through Friday
  </thread>
  <thread messageCount="3" isUnread="false">
    Don't forget about the picnic on Saturday
  </thread>
</threads>

The new XML service has some notable advantages over the old service:

• The ability to alter parsed XML content and save it back to a string.
• Access to all entity types in the XML document (CDATA sections, Comments, etc.)
• More control over the formatting of the XML string.

With the launch of this new service, we are deprecating some of our older XML tools in Apps Script, specifically the old XML service, the SOAP service, and the JavaScript feature E4X. Calls to these services will continue to work, but we encourage you to start migrating your code to the new XML service for better long-term support. On February 1, 2014, these old services will no longer appear in auto-complete or in our documentation, per the Apps Script sunset schedule.

Ever wanted to programmatically insert something at the cursor in Google Docs (say, a “Sign Here” image) or read the user’s selection (maybe for an on-the-spot translation)? Starting today, you can.

Apps Scripts bound to Google Docs can now access the active user's Cursor and Selection by calling Document.getCursor() and Document.getSelection(), respectively. The returned objects provide useful information like the element the cursor is positioned in and an array of all of the elements contained in the selection.

Example #1: Selection Translator

This Google Doc contains a simple script that uses Apps Script’s Language Service to translate selected text from English to Spanish through a custom menu item.

Here, it uses the getSelectedElements() method of the Selection class to get an array of selected elements:

var selection = DocumentApp.getActiveDocument().getSelection();
  if (selection) {
    var elements = selection.getSelectedElements();

Next, it loops through each element, performs the translation, and replaces the original text:

var translatedText = LanguageApp.translate(
    element.asText().getText(), 'EN', 'ES'); 
element.asText().setText(translatedText);

Example #2: Bibliography App

At Google I/O this year, Apps Script engineer Jonathan Rascher demonstrated Bibstro, a bibliography sample app for Google Docs that inserts inline citations at the cursor. Today, we’re releasing the source code for Bibstro; you can also try it out by making of copy of this Google Doc.

To insert text, the script calls the aptly named insertText() method of the Cursor object:

var cursor = DocumentApp.getActiveDocument().getCursor();
if (cursor) {
  // Determine the text of the new inline citation to insert.
  var citation = bibStrategy.getInlineCitationText(...);

  var surroundingText = cursor.getSurroundingText().getText();
  var surroundingTextOffset = cursor.getSurroundingTextOffset();

  if (surroundingTextOffset > 0 &&
      surroundingText.charAt(surroundingTextOffset - 1) != ' ') {
    // If the cursor follows a non-space character, insert a space
    // and then the citation.
    cursor.insertText(' ' + citation);
  } else {
    // Otherwise, just insert the citation.
    cursor.insertText(citation);
  }
}

You’ll also notice that the script uses the Cursor class’s getSurroundingText() method to determine whether to insert a space before the new inline citation.

Example #3: Cursor Inspector

To help you become familiar with how cursor and selection work, we've also created a Cursor Inspector sample script. As you navigate through a document, the script displays up-to-date information about your cursor or selection in a custom sidebar. We’re also releasing the source code for Cursor Inspector on GitHub.

These new APIs are available immediately. We’re excited to see what kind of scripts you come up with!

Kalyan Reddy profile | Stack Overflow Kalyan is a Developer Programs Engineer on the Google Apps Script team in New York City. He is committed to increasing developers’ productivity by helping them fully utilize the power of Apps Script. In his free time, he enjoys participating in the maker community and hacking together robots.

Flubaroo, a popular Apps Script application that helps teachers with grading, has just reached version 3.0. The new features and improvements include:

• Smarter emailing of grades.
• Option to email "Help Tips" for each question.
• Option to send students individualized feedback.
• Multi-language support, with first language of Spanish.
• Easier to read grade emails.

If you know any teachers who aren’t using Flubaroo yet, why not encourage them to try it out? It doesn’t cost a thing, and has helped thousands of teachers save time and gain insight into student performance — all through the power of Apps Script.

Dave Abouav   profile Dave is a Googler who also teaches physics at community college at nights. He developed Flubaroo as his 20%-time project, and runs edCode.org, a community of teachers and developers creating free, open-source tools for education.