Live Apps for Quip

Building a Sticky Note App

Let's make your app into something more exciting — a sticky note app that anyone on the document can edit. You'll see firsthand some of the collaborative abilities of the Quip Live Apps API. We'll also demonstrate how to store real data in an app. First we'll set up the data model, then add a Quip rich text box, and finally tweak the CSS.

Note that the app is not ready until you reach the final step (don't try to reload until then).

The completed source code for this example is here:
github.com/quip/quip-apps/tree/master/examples/sticky-note

Storing Data — The Root Record

All the persistent data for your app lives in objects called Records. Every app automatically has its own RootRecord to start with.

Open src/root.jsx and update the code to access the RootRecord via the apps API:

quip.apps.initialize({
    initializationCallback: function(rootNode) {
        let rootRecord = quip.apps.getRootRecord();
        ReactDOM.render(<App/>, rootNode);
    },
});

Introducing Properties

All app data must live in a property of either the RootRecord or a descendant of the RootRecord. These properties can be primitives (number, string, boolean, etc), RecordList objects, or Record objects with properties of their own.

For this app, we want to set up a property for a special type of record designed to store collaborative text — a RichTextRecord. This property will be defined on the RootRecord.

To start adding properties to the root record, you must first define a custom class that extends quip.apps.RootRecord. Then, you must implement the getProperties() function to define the name and type of each property that can live on the record. The API reference explains more about records, properties, and data.

For now, update the code in root.jsx as follows to set up the property and pass it into <App/>:

class StickyNoteRoot extends quip.apps.RootRecord {
    static getProperties() {
        return {
            stickyNote: quip.apps.RichTextRecord
        };
    }
}
quip.apps.registerClass(StickyNoteRoot, "root");

quip.apps.initialize({
    initializationCallback: function(rootNode, params) {
        let rootRecord = quip.apps.getRootRecord();
        if (params.isCreation) {
            rootRecord.set("stickyNote", {});
        }
        ReactDOM.render(
            <App richTextRecord={rootRecord.get("stickyNote")}/>,
            rootNode);
    },
});

Notice how we first create StickyNoteRoot to extend quip.apps.RootRecord. We then implement getProperties() to define the stickyNote property. We say that the stickyNote property has type RichTextRecord, which we need to store our collaborative text.

Here's a deep dive into the rest of this code. If you'd like, just skim it for now to get your sticky note working first.

Deep Dive: Registering the Record Class

You can see that this code calls quip.apps.registerClass after creating StickyNoteRoot. For every record class you define, you also must call quip.apps.registerClass to inform the Quip API about the record class. This Quip API method takes as parameters the record class and a unique string identifier. The string identifier must not change once set (otherwise existing instances of your app may break). The call must happen before quip.apps.initialize.

You can only ever register one class that extends quip.apps.RootRecord. Once you do so, all calls to quip.apps.getRootRecord() will return instances of your custom root class. Note that more complicated apps will want to define descendant records that also have properties — to do so, just extend quip.apps.Record in the same fashion.

Deep Dive: Creating the Property

Now we're ready to actually create and use the stickyNote property! We create the property by calling rootRecord.set("stickyNote", {}). The first parameter of set is the name of the property. set knows that it should create a new RichTextRecord record for stickyNote because of the definition in getProperties. The second parameter is an object that contains child properties to set on the newly-created RichTextRecord. In this case, we don't have any special properties for stickyNote so we pass an empty object.

Once you set a property, it lives on the record for as long as the app exists in the document. That's why we only call set for stickyNote when the app is first created. We detect creation by checking params.isCreation in quip.apps.initialize, where the params object is passed to our app from the Quip document. When params.isCreation is false, quip.apps.initialize is being called on an existing app. In that case, our set-up code already ran and the stickyNote property already lives on the root record. We shouldn't set it up again since it might now contain data.

Deep Dive: Getting the Property

The last thing we do is call rootRecord.get("stickyNote") to access the RichTextRecord object stored in the property. We pass the result into <App/> as a React prop, ready to use. (If the idea of React props is new to you, the React tutorial will help.)

Adding Rich Text

Now we can add the RichTextBox React component to make the app collaborative!

A RichTextBox is one of the powerful Quip platform building blocks. It seamlessly handles edits from different users and provides all the functionality of the Quip editor, including styling and collaborative features like @mentions.

Adding a RichTextBox is incredibly easy. All we need to do is pass it the RichTextRecord — it handles everything else.

Update your code in App.jsx as follows:

import Styles from "./App.less";
export default class App extends React.Component {
    static propTypes = {
        richTextRecord: React.PropTypes.instanceOf(quip.apps.RichTextRecord).isRequired,
    }

    render() {
        return <div className={Styles.hello}>
            <quip.apps.ui.RichTextBox
                record={this.props.richTextRecord}/>
        </div>;
    }
}

Adding Style

All we need to do now is make the app look like a Sticky Note. Let's size the RichTextBox and add a background color and border — we'll use standard CSS and official Quip Yellow for this:

import Styles from "./App.less";
export default class App extends React.Component {
    static propTypes = {
        richTextRecord: React.PropTypes.instanceOf(
            quip.apps.RichTextRecord).isRequired,
    }

    render() {
        const style = {
            backgroundColor: `${quip.apps.ui.ColorMap.YELLOW.VALUE_LIGHT}`,
            border: `1px solid ${quip.apps.ui.ColorMap.YELLOW.VALUE}`,
            boxShadow: "0 2px 5px 5px rgba(0, 0, 0, 0.1)",
            padding: 10,
        };
        return <div className={Styles.hello} style={style}>
            <quip.apps.ui.RichTextBox
                record={this.props.richTextRecord}
                width={280}
                minHeight={280}
                maxHeight={280}/>
        </div>;
    }
}

You Did It!

Your app is ready! Go to your Quip document from earlier and reload your app (review Develop Your App if needed). You should see a yellow sticky note show up. (If you're stuck, try these debugging pointers or compare against the complete code.)

Check out what your app can do with just one Rich Text Box:

• Add a sentence and style every word.
• Try typing @ to mention a person and send them a notification.
• You could type @ followed by a document title to add a link to it.
• Record the special day you made this note by typing @Today.

But there's more! First go ahead and deploy your new changes.

Now try for some real-time collaboration. Your changes automatically sync for everyone viewing, without needing to refresh:

• Share the document with a friend and watch their edits appear.
• Open the document in another tab, and see changes reflect back in the original tab.
• Open the document using the Quip app on your phone. Changes show up there too!

Next Steps

There's so much more you can do with the Quip Live Apps API. Read a Recipe, check out an example app, or browse through the full API.

We can't wait to see what you build!

Questions?

Ask our team and the Quip developer community over at the Salesforce Stack Exchange.