Creating Your First Saito Application

It takes two minutes to create an application on Saito. In this tutorial, we’ll introduce you to app development by building an application that lives inside the Saito email client, and then add a separate webpage to it so it can run directly in the user browser just like our email client itself.

1. STEP ONE: Visit our Online Development Environment


Click the button that says “new module” and give your module a name. We called our test app “SaitoRocks”. Remember not to put space or special characters in your name.

2. Congratulations, you now have a basic application!

You will see something that looks like this:

You don’t need to change any of these lines of code. The only thing to notice is that we’ve told your module the name of your application. Later on we will come back to the Constructor and tweak a settings. For now, scroll down to the onConfirmation function:

This is going to be the heart of your application: this function runs every time a transaction belonging to this module gets a confirmation. This function gets access to the block containing the transaction, the transaction itself, the confirmation number, and a reference to the entire Saito application itself so we can do anything we want from within a module. But for now we just check to make sure this transaction is for us, and then format a javascript object into a message that our Email module will understand.

If you want to see this application, you can try clicking “deploy” and see what happens, but you’ll be disappointed. Because while this application is valid, there is no way for anyone to SEND transactions that were created by your module yet, so this onConfirmation function will never run. The easiest way to fix that it to give your app an email interface.

3. Adding the Email Interface

Click on the “Add Email Callbacks” in the right-hand column. Wham! We’ve just added the two basic functions you need to make the Saito email client recognize that you are writing an email application. Scroll down and you’ll see these two functions we have added:

The first function (displayEmailForm) gets run whenever the user wants to look at your application in their email client. In this demo we just display a text message, but we could display a form that collects data (check out our registry module for an example) or have our browser create cryptographic keys and generate signatures for complex things like email-mediated payment channels.

The second function (formatEmailTransaction) is also important — it gets run when the user clicks “send” in their email. What it lets us do is add whatever information we want TO THE SAITO TRANSACTION. In this case, we just add a tiny bit of data, but if you have done something like create a form or generated cryptographic data, this is basically where you want to take the contents of that form or that cryptographic data and ADD it to the transaction. Unless you do this, the module that receives the transaction will not have access to it.

Final note? Look back up at the Constructor. We’ve added two tiny bits of data that tell your application that it wants to offer an email interface. You should probably change the variable emailAppName so that your application won’t just show up as “New Application” in the email client.

Ready to test it out? Click the “deploy” button and our server will compile your application and give you a link you can use to check it out. Load the application and click “compose” in the Email client. Click on the “select” box and you’ll see your application listed. If you click on it, you’ll see the text that we provided above. If you want to test the onConfirmation function and have tokens in your browser, you can send yourself an email (a transaction!) and your onConfirmation function will run when it receives that transaction from the blockchain.

4. Developing More Complex Web Applications:

Click on “Deploy WebApp Callbacks” in the right-hand column and life gets more interesting. You’ll notice that we added a new tab in your browser that will let you edit the HTML of a webpage:

You can tweak the HTML to create any kind of interface you want. From the perspective of the user your application will look and feel exactly like a webpage — most will probably not even notice they are using a blockchain application instead of surfing the web. Advanced programmers might notice that we’ve added an empty DIV with an id field that references the name of our app (i.e. SaitoRocks_browser_active). Including this is a convention we use when building Saito Applications so that the modules can tell which web-app is interacting with the user and we can only run the relevant UI callbacks. The rest of the HTML is pretty self-explanatory.

Go back to the javascript tab and look at the two extra callbacks we have added to your application. These are the functions you use to build the meat of your app:

The first callback is initializeHTML. It runs when the user loads this module for the first time. In this case, our demo code just looks for a specific item in the HTML and puts our address there (fetching it from our wallet — a useful reminder that we are running in the user browser and not the remote website!). In practice you can do whatever you want here. For more complicated examples check our our Email or Facebook modules, which load saved messages from long-term storage and add them directly into the interface as if they have just arrived over the blockchain.

The attachEvents function is where we add interactivity to the webpage. Right now we just make a button clickable and show a message. But you can do anything you want. We keep this function separate from initializeHTML mostly for convenience — as sometimes we want to refresh the events on the DOM without reloading the entire module.

Done? Click on “deploy” and you can click on the link that says “Saito web application”. This will load the web application and you can see that it works.

5. This is what our app looks like:

Open the email client and you can see that the Saito app is installed.

When we select it our app shows us the HTML form content we have asked to display. Note that we’re about to send this transaction out onto the network, addressed to ourselves so that we can see what happens when we receive one of these transactions.

It worked! Our onConfirmation function ran and added this message to our Email inbox.

And what’s in the email? Nothing special for now, but you can make the application display anything you’d like. And you can make it totally interactive. Google has nothing on Saito….

6. Moving Forward — What are the Next Steps for Real-World App Development?

If you’re interested in building more complex modules, you should look at the file lib/modules/template.js for a list of all of the callbacks that you can extend with your modules. We expect to add more callbacks over time so if you run into problems you don’t know how to solve contact us.

The best environment for actual development is a version of Saito running locally on your own computer and sending and receiving transactions from a local blockchain. You can get this running reasonably quickly by downloading a copy of Saito and getting it setup on your own laptop. All Saito deployments come with a default set of modules installed in the lib/modules/mods directory, so you can see exactly how the existing modules work and use them as templates for writing your own programs.

And when you finish your application? You can run your own Saito node and distribute it to all of your users by default (anyone who installs your module can distribute it to users) but if you get in touch with us and we can also host it and distribute it from our servers, at least to users who wish to run it.

In the long-term, we believe users will install Saito modules the same way they install Desktop applications. We ‘re planning to roll out a curated “App Store” for Saito modules that will host curated apps so that we can combine the flexibility of the Saito approach with a basic security review to ensure that modules aren’t doing malicious things.