INDEX

Application example

This example implements an application that returns random integers through an exposed RPC method. The example implements an dynamic tile. The logic in the tile calls the RPC method every five seconds and outputs the result to the tile. This example also implements an application web page. Clicking the tile opens the web page into a new tab or window (see window.open). This example demonstrates how to make the web pages and tiles remote operation safe.

Edge-side

The manifest

spaceify.manifest
{
  "provides_services": [
    {
      "service_name": "spaceify.org/services/random",
      "service_type": "open"
    }
  ],
  "name": "Random",
  "unique_name": "random",
  "version": "1.0.0",
  "type": "sandboxed",
  "category": "educational",
  "start_command": "node random.js",
  "short_description": "Application example.",
  "appstore_description": "Application example.",
  "developer": {
    "name": "Spaceify Oy",
    "url": "http://spaceify.net",
    "email": "admin@spaceify.net"
  },
  "implements": [
    "WEB_SERVER"
  ]
}

The manifest contains all the mandatory identifying fields. The provides_services field makes the service available and the start_command tells Spaceify how to start the application.

The application package

application
├── spaceify.manifest
├── random.js
└── www
    ├── tile.html
    ├── index.html
    ├── random.js
    ├── logo.png
    └── css
        └── tile.css
        └── index.css

The applications manifest must be directly below the application directory. The executable could be somewhere else, as long as the start_command finds it (for example, "node js/random.js" instead of "node random.js").

The www directory is required for the tile and application web page. When Spaceify finds the tile.html file, it knows the application supplies its own tile. The random.js contains the JavaScript code the tile uses. The index.html file contains the applications web page Notice how the file is specifically named index.html to support the remote operation system.

The logo image is displayed on the web page. The css files required by the tile and web page are placed to a directory of their own just to make things tidy.

Edge-side

Applications do not have to have edge-side and client-side application code. Applications can function perfectly fine within the edge-side. Other applications can call its methods and it can call theirs, or it just provides services for others. However, It is not impossible to connect to the services of an application from the client-side (web pages) code. The services just have to be open so that web pages can connect to them. In this application we use the client-side edge-side approach.

The executable file

The SpaceifyApplication class is used for controlling the application. After the application is started and its start method is called, the provided service is used to expose the "get" RCP method. The get method generates an random number between the [-1024, 1024] range and returns it to the caller.

random.js
var spaceify = require("/api/spaceifyapplication.js");
 
function Random()
	{
	var self = this;
 
	// The provided service
	var service = null;
	var serviceName = "spaceify.org/services/random";
 
	// This method is called if app is started succesfully
	self.start = function()
		{
		// Get the provided service and expose the RPC method
		service = spaceify.getProvidedService(serviceName);
		service.exposeRpcMethod("get", self, get);
		}
 
	// This method is called if starting the app fails
	self.fail = function()
		{
		}
 
	// Send random integer to the caller of this RPC method
	var get = function(name, callObj, callback)
		{
		var sign = (Math.random() >= 0.5 ? 1 : -1);
		var number = Math.floor(Math.random() * 1024) * sign;
 
		callback(null, number);
		}
	}
 
// Start the app
var random = new Random();
spaceify.start(random, {webservers: {http: true, https: true}});

The client-side tile and web page

As discussed above this application implements a tile and web page. The tile is dynamic and has external JavaScript file. Web pages can be dynamic, but in this example it is static and only displays text and a logo image.

The tile.html and random.js files

tile.html
<!DOCTYPE html>
<html>

<head>
	<meta charset="utf-8">

	<title></title>

	<link rel="stylesheet" sp_href="css/tile.css">

	<!-- Remote operation | Spaceify's API | Tiles app code -->
	<script src="libs/spaceify.loader.js"></script>
	<script spe_src="libs/spaceify.api.js"></script>
	<script sp_src="random.js"></script>

	<script>
	var app;
	var unique_name ="random";

	<!-- Wait before doing anything -->
	window.addEventListener("spaceifyReady", function()
		{
		// Use this class when working with applications
		app = new SpaceifyApplication();

		// Init this app and connect to the application on the edge
		var random = new Random(app, "rdiv");
		app.connect(random, unique_name);
		}, false);

	<!-- Open the applications web page -->
	window.addEventListener("click", function()
		{
		window.open(unique_name, "index.html", "_blank");
		});
	</script>
</head>

<body>
	<div class="tile">
		<div class="tileText" id="rdiv">
		</div>
	</div>
</body>

</html>
random.js
function Random(app, id)
	{
	var self = this;
 
	var rdiv = document.getElementById(id);
 
	// The required service
	var service = null;
	var serviceName = "spaceify.org/services/random";
 
	// This method is called if connection to the app was succesfull
	self.start = function()
		{
		// Get the service and call "get" RPC method of the app
		service = app.getRequiredService(serviceName);
		service.callRpc("get", [], self, got);
 
		// Call "get" every five seconds
		setInterval(function()
			{
			if(service)
				service.callRpc("get", [], self, got);
			}, 5000);
		}
 
	// This method is called if connecting to the app failed
	self.fail = function()
		{
		var node = document.createTextNode("Failed to connect to the app.");
		rdiv.appendChild(node);
		}
 
	// Print the response from the get RPC call
	var got = function(err, response)
		{
		rdiv.removeChild(rdiv.lastChild);
 
		var node = document.createTextNode(err ? err.message : response);
		rdiv.appendChild(node);
		}
	}

Tile uses the remote operation system to initialize itself; the sp_* and spe_* properties for resources in the tags. The loader loads the resources dynamically and after the resources are loaded the "spaceifyReady" event is emitted. The SpaceifyApplication class, the same one used in the edge-side example, is used to connect to the edge-side application.

(It is possible to use app.start(… because connect is an alias of start. This is a matter of preference. It can be said that the client-side application is started. However, nothing is started, only connections to the edge-side application are made.)

The Random class is used to handle the client-side connection. After the connection is established the getRequiredService method of the SpaceifyApplication class is called to get the open service of the application. The "get" method is initially called once and then every five seconds. The result is printed to the rdiv DOM element.

The application web page

Clicking the tile opens the application web page. The web page contains text and an logo. This example could be extended to display the random number. Following the tile implementation gives great starting point for this.

index.html
<!DOCTYPE html>
<html>

<head>
	<meta charset="utf-8">

	<title>Random</title>

	<!-- Load web pages stylesheet -->
	<link rel="stylesheet" sp_href="css/index.css">

	<!-- Load resources to the elements having sp_* and spe_* properties -->
	<script src="libs/spaceify.loader.js"></script>
</head>

<body>
	<img sp_src="logo.png">

	<div>
		Random
	</div>
</body>

</html>

Installing the application

Method 1 - Manual package creation

The application requires also the resources listed in the directory structure. They are downloadable from the links below.

logo.png tile.css index.css

Create the application package manually and copy the files to their directories. Install the application to the Spaceify edge from the current working directory (where the application/ directory is) with the spm command like this.

spm install

Method 2 - Quick installation

Download this ready-made package random.zip and install it with spm.

spm install random.zip

Testing the application

The application can be tested by browsing to the Spaceify edges landing page in URL edge.spaceify.net. The random tile displays the random integer and nothing else. Clicking the tile opens the application web page.

Close
copyright © Spaceify.org 2014