Unifer Documentation Release V1.0 Matthew S July 28, 2014
Contents 1 Unifer Tutorial - Notes Web App 3 1.1 Setting up................................................. 3 1.2 Getting the Template........................................... 3 1.3 Layout of the Template.......................................... 3 1.4 app.js................................................... 4 1.5 index.html................................................ 5 1.6 ucallback.html.............................................. 5 1.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 a consistent 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 sites as 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. Any web server capable of displaying HTML files will work fine! If you don t already have one set up, you have a lot of options. You ll need a place to put your site, so create a folder somewhere (let s call it ~/notes-app). Now set up your web server to display the contents of ~/notes-app as a site on localhost. If you have Python installed, this is as simple as navigating in a command prompt to ~/notes-app and running python -m SimpleHTTPServer 8000. Now that you ve got the server set up, open a browser and go to http://localhost:8000. You should see either an error message or a directory listing, but that s good! It shows that your server is up and ready, you just need to give it something to show. OK, now we re past the simple stuff, you should know that there are a few prerequisites for this tutorial. You should have a working knowledge of Javascript and HTML, as well as an understanding of how most web apps work. If you 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 use this 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 the contents 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 where the user is redirected after signing in with their Unifer provider. It redirects to home.html. home.html is the home page for 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 s Unifer access token. app.js provides an app object with basic functions for using Unifer, like app.logout() and app.getuniferclient(). The template grabs the latest version of uniferlib-js from Github, but if you d rather ensure a stable version (which is probably 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 always modify 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 to the Github source of your app (if applicable), or the final domain where you ll host it. You can not change the appid after using your app. For now, just set it to Your-Name-Notes-App-Tutorial-Date, or a random 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 is called directly after the user signs in with their Unifer provider, and can be used to initalize all the buckets you might use. 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 define within that array will be created when the user first signs in to your app. There should already be an example entry in the 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 be handy. 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 are done with tokens. You must define a token on the bucket before you can use it to grant permissions on individual items within that bucket. For now, we ll add a token with the access token public and the maximum possible access levels as READ and UPDATE. 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 the bucket 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.js is cookiename, which you can use to set the name of the cookie that stores the Unifer access token data (it s set to udata by default). 1.5 index.html Index.html provides a login UI for your users. Change the <title> to something that represents the app, like Welcome to your Notebook!. When #start is clicked, uniferlib is called to validate that the Unifer provider exists and works. If it does, the template 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 needed to sign in. 1.6 ucallback.html After the user auths your application, they ll be redirected to ucallback.html along with a few GET request parameters - 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, it redirects 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 to use. 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 be used to host user data, test against, or use as a reference to create other providers. Note that while unifer-server is the reference provider, it s by no means the only possible provider. Thanks to the protocol, any server that responds in a similar 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 without taking 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 brings us 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 page without having to sign up again. Unifer allows you and your users to seamlessly try out multiple different forks of the same 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 blog posts they re the one who pays for it, not you. It also means you can spend slightly less time worrying about sysadmin and 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 you need 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 like site-wide search of user generated content (think Facebook Search) are extremely difficult to implement in a distributed system 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 - but in 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 relatively easily 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 re interested. 15
Unifer Documentation, Release V1.0 16 Chapter 6. Status of the docs
CHAPTER 7 Indices and tables genindex modindex search 17