Ob2SS.com

Quick Start Guide

This page helps you get acquainted with Ob2ss basics and shows you how to get started using the library.

Importing the Library

Ob2ss is loaded into an Apps Script project by referencing it as a Library. Read more about libraries here. Once it's imported, you call functions on the library.

First, click the plus in the "Libraries" pane.

Then, add the library ID, click "Look Up", and click "Add". Here's that Library ID:

10r01m6-bM7-Ksz1ccwIceIdxmKyjd7LvqUtw8C6FupcLjgoBecG_Q2dv

And you're done! Now you can start calling Ob2ss from your project.

Using Ob2ss

In this section I'll write about a few common ways to get started using Ob2ss. It's really flexible so there're a few key ways to use it.

Suppose you're just looking to write and read data locally and quickly, you can do so without much fuss. The following code writes a new object and reads it back.

let writeObject = {id: 1, brand: 'Toyota', model: 'Camry'};
Ob2ss.addAppend(writeObject);
let readObject = Ob2ss.readLast()[0];
// readObject is now {id: 1, brand: 'Toyota', model: 'Camry'}

Notice that Ob2ss was never told where to write this data. It figures that out automatically! It'll try the following in order to figure out where to store data:

1. Is there a spreadsheet bound to this script? If so, use that.
2. Is there a spreadsheet that already exists and is named after this script? If so, use that.
3. Otherwise, make a new spreadsheet named after this script and use that.

This ability to get up and running quickly is super useful! It works really well for situations like rapid prototyping or when you just need to record some data- just once- to facilitate some bigger process.

Suppose you want to use Ob2ss on an existing spreadsheet, that's easy to do as long as the spreadsheet conforms to a few important details.

The most important thing is there must be a header row: a row near the top of the spreadsheet that contains the name of the field that each column represents. This can be expressed in one of three ways, and this is the order in which Ob2ss looks for them.

1. If there are no frozen rows then Ob2ss uses the first row of the spreadsheet.
2. If there are frozen rows then Ob2ss uses the last frozen row, right above the data.
3. If there are frozen rows and you set options.headerOffset then Ob2ss will count that number of rows up from the last frozen row and use that row instead.

I know this can be confusing, so take a look at the images below to see those three in action.

Here's what it looks like with no frozen rows.

And here's what it looks like with frozen rows, by default.

And here's what it looks like with frozen rows, with options.headerOffset = 1.

Notice that in option 3 we get to keep using spreadsheet features like Filtering and Sorting! Remember that, in order to use that, you must set options.headerOffset on the table, like this:

Ob2ss.getTableByName('my_table').options.headerOffset = 1

And that's it! Now that you see how to get started using Ob2ss, consider jumping over to the Cookbook section to see how you can use Ob2ss in your own projects.