Unifer DocumentationRelease V1.0

Matthew S

July 28, 2014

Contents

1 Unifer Tutorial - Notes Web App 31.1 Setting up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Getting the Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Layout of the Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 app.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.5 index.html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.6 ucallback.html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.7 home.html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 What is Unifer? 7

3 Why use Unifer? 9

4 But I don’t care about that 11

5 What are these docs? 13

6 Status of the docs 15

7 Indices and tables 17

i

ii

Unifer Documentation, Release V1.0

Unifer is a simple protocol that allows web developers to write dynamic websites and applications with only static,client-side code.

With Unifer, you write client-side apps that users log into with their own Unifer provider, a server that provides aconsistent API for you to write against. It’s extremely similar to unhosted’s remoteStorage.

Contents:

Contents 1

Unifer Documentation, Release V1.0

2 Contents

CHAPTER 1

Unifer Tutorial - Notes Web App

Unifer lets you build engaging websites that store, retrieve, and share user data without writing a line of backend code.This tutorial walks you through creating your first Unifer site, a simple note taker.

We’ll be using uniferlib-js to connect with Unifer, and it’s reccomended that you use uniferlib-js in your Unifer sitesas well.

1.1 Setting up

Unifer apps are great because you don’t need to have a fancy web server or database running in the background. Anyweb server capable of displaying HTML files will work fine! If you don’t already have one set up, you have a lot ofoptions.

You’ll need a place to put your site, so create a folder somewhere (let’s call it ~/notes-app). Now set up yourweb server to display the contents of ~/notes-app as a site on localhost. If you have Python installed, this isas simple as navigating in a command prompt to ~/notes-app and running python -m SimpleHTTPServer8000.

Now that you’ve got the server set up, open a browser and go to http://localhost:8000. You should see eitheran error message or a directory listing, but that’s good! It shows that your server is up and ready, you just need to giveit something to show.

OK, now we’re past the simple stuff, you should know that there are a few prerequisites for this tutorial. You shouldhave a working knowledge of Javascript and HTML, as well as an understanding of how most web apps work. Ifyou’re just starting out with web development there are better places to start learning.

1.2 Getting the Template

Uniferlib-js provides a great, bare-bones template that you can use to jump start your app. We’ll download and usethis template for our notes app.

Download the latest copy of the uniferlib-js repo from Github as a zip file. Unzip the downloaded file, then copy thecontents of the Tutorial folder to ~/notes-app.

1.3 Layout of the Template

The template contains three html files and one folder for scripts.

3

Unifer Documentation, Release V1.0

index.html is the landing page for your app. This is what people will see before they log in. ucallback.html is wherethe user is redirected after signing in with their Unifer provider. It redirects to home.html. home.html is the home pagefor your app. It’s what your users will see after they log in.

In the scripts folder,

cookie.handler.js provides simple functions for reading, updating, and modifying both generic cookies and the user’sUnifer access token. app.js provides an app object with basic functions for using Unifer, like app.logout() andapp.getUniferClient().

The template grabs the latest version of uniferlib-js from Github, but if you’d rather ensure a stable version (which isprobably a good idea) you can copy uniferlib.js from the Library folder in the repo you downloaded.

We’ll walk through and explain each file in the rest of the tutorial as we add the code required to create a notes app.

1.4 app.js

The first thing you’ll notice upon opening app.js is an object called app.globalUniferData. You should alwaysmodify appName and appId.

• appName can be anything you want. For now, just replace {AppName} with Unifer Notebook.

• appId, on the other hand, must be exclusive to your app. A good rule of thumb is to use either a link tothe Github source of your app (if applicable), or the final domain where you’ll host it. You can not changethe appId after using your app. For now, just set it to Your-Name-Notes-App-Tutorial-Date, or arandom string (about 30 characters long, to be safe) from random.org.

globalUniferData should now look like:

app.globalUniferData = {appName: "Unifer Notebook",appId: "[Your Name]-Notes-App-Tutorial-[Date]",callback: (location.protocol + "//" + location.host + "/ucallback.html"),autoJSON: true

};

A function or two below globalUniferData you’ll notice a function called initBuckets. initBuckets iscalled directly after the user signs in with their Unifer provider, and can be used to initalize all the buckets you mightuse.

1.4.1 What are buckets?

Buckets are the Unifer term for data containers which are basically tables in traditional SQL databases.You should create a different bucket for each type of data you plan on using in your app. For this app,we’ll need to create a Notes bucket to hold our user’s notes.

Looking within the initBuckets folder in app.js you’ll notice an array named buckets. Any buckets you definewithin that array will be created when the user first signs in to your app. There should already be an example entry inthe array, so we’ll just edit it.

• name is the name of the bucket. Let’s set it to Notes, or whatever you find most appealing.

• tag is how we’ll reference the bucket later. It’s a good idea to only ever use a tag once. Let’s set it to notes.

• about is an explanation of the bucket. It’s not necessary, but if there’s something you want to explain it can behandy. We won’t use it for this app.

• tokens is slightly more interesting:

4 Chapter 1. Unifer Tutorial - Notes Web App

Unifer Documentation, Release V1.0

1.4.2 What are tokens?

Granting other people and apps permission to read, update, replace, and delete buckets and items aredone with tokens. You must define a token on the bucket before you can use it to grant permissions onindividual items within that bucket.

For now, we’ll add a token with the access token public and the maximum possible access levels as READ andUPDATE. To do this, set tokens to [ { token: "public", scopes: ["READ", "UPDATE"] } ].

Note that just because we define the public token on the notes bucket, that does not mean every note we add to thebucket is automatically read and writeable by the public token. All items, no matter which bucket they’re added to,are private by default. You must explicitly specify tokens and scopes on the items when creating or updating them.

Your buckets array should now look like:

var buckets = [{ name: "Notes", tag: "notes", tokens: [ { token: "public", scopes: ["READ", "UPDATE"] } ] }

];

Past that, you shouldn’t have to change anything else in app.js. The only interesting thing cookie.handler.jsis cookieName, which you can use to set the name of the cookie that stores the Unifer access token data (it’s set toudata by default).

1.5 index.html

Index.html provides a login UI for your users. Change the <title> to something that represents the app, likeWelcome to your Notebook!.

When #start is clicked, uniferlib is called to validate that the Unifer provider exists and works. If it does, thetemplate will begin the auth process.

Customize and theme this page as much as you want, all that’s provided in the template is the bare minimum neededto sign in.

1.6 ucallback.html

After the user auths your application, they’ll be redirected to ucallback.html along with a few GET requestparameters - token, userId, and provider. If the user grants your application access to their provider,ucallback.html is set up to receive and store those values, then forward the user to home.php. If they don’t, itredirects to index.html?error=NotAuthed.

1.7 home.html

1.5. index.html 5

Unifer Documentation, Release V1.0

6 Chapter 1. Unifer Tutorial - Notes Web App

CHAPTER 2

What is Unifer?

Unifer as a whole is split into three main portions - the protocol, unifer-server, and uniferlib-js.

The Unifer protocol defines a standard set of requests and responses that Unifer providers and clients are expected touse. The protocol allows clients to be provider-agnostic, so users are free to use any provider that follows the protocol.

Unifer-server is the reference provider for Unifer. It fully supports all requirements in the protocol, and so can beused to host user data, test against, or use as a reference to create other providers. Note that while unifer-server is thereference provider, it’s by no means the only possible provider. Thanks to the protocol, any server that responds in asimilar way to unifer-server should be able to work with app client apps.

Uniferlib-js is the Javascript client wrapper for Unifer. It simplifies the process of writing Unifer client apps withouttaking away any control you’d have writing it yourself. Uniferlib-js effortlessly allows you to handle errors, timeouts,callbacks, and more. Throughout these docs we’ll assume you’re using uniferlib-js to create a web app. Which bringsus to another important question...

7

Unifer Documentation, Release V1.0

8 Chapter 2. What is Unifer?

CHAPTER 3

Why use Unifer?

Unifer provides a few advantages over a traditional web application.

Firstly, it allows multiple forks and interfaces for an application to access the same underlying user data. With Unifer,you can test out someone’s app on Github pages, then fork, modify, and use it on your own computer or Github pagewithout having to sign up again. Unifer allows you and your users to seamlessly try out multiple different forks of thesame application without losing their data.

Unifer also gives the user control over their own data. That means that if they fill up 10GB worth of space with blogposts they’re the one who pays for it, not you. It also means you can spend slightly less time worrying about sysadminand more time working on a great web app.

9

Unifer Documentation, Release V1.0

10 Chapter 3. Why use Unifer?

CHAPTER 4

But I don’t care about that

Unifer certainly isn’t for every, or even most, apps. In general, it’s best suited for small apps where the most data youneed to store is short and user-specific - think a notepad or game that saves your progress as you go on.

Unifer is *not* built for apps which rely on cross-referencing data across multiple users. Especially things likesite-wide search of user generated content (think Facebook Search) are extremely difficult to implement in a distributedsystem like Unifer.

That’s not to say it’s impossible - see spreddit for a Unifer reddit clone that’s based on friending users you know - butin most of these cases your time would be better spent writing a centralized backend for your site.

It’s also worth noting that Unifer currently doesn’t have native support for uploading files, but that can be relativelyeasily added to the protocol later.

11

Unifer Documentation, Release V1.0

12 Chapter 4. But I don’t care about that

CHAPTER 5

What are these docs?

These docs provide information about writing web apps that use Unifer and its Javascript library, uniferlib-js.

If you’re looking to write your own client library for the Unifer protocol, check out the uniferlib-js source code.

If you’re looking to write your own Unifer provider, check out the Unifer protocol docs.

13

Unifer Documentation, Release V1.0

14 Chapter 5. What are these docs?

CHAPTER 6

Status of the docs

These docs are probably about 10% finished. Check back later, or contact me at matthewsot@outlook.com if you’reinterested.

15

Unifer Documentation, Release V1.0

16 Chapter 6. Status of the docs

CHAPTER 7

Indices and tables

• genindex

• modindex

• search

17