INDEX

Spacelet Example

This example demonstrates the client-side and edge-side applications required to make a spacelet. Refer to the Spacelet subsection, if refreshment of spacelet fundamentals is required.

Client-side

The client-side application, or more specifically the web page it runs on, is at URL https://spaceify.org/hello. The file is naturally not available to developers, because it is in Spaceify's server. The file can be served from any server. If it is, the manifests origins field must list that servers hostname. The client-side application web page looks like this.

index.html
<!DOCTYPE html>
<html>
 
<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=100%, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
 
	<!--  Use Spaceify's JavaScript API. -->
	<script src="https://spaceify.net/libs/spaceify.api.js"></script>
 
	<title>Spacelet - Hello</title>
 
	<script>
	var hiDiv;
	var spacelet;
 
	window.addEventListener("load", function()
		{
		hiDiv = document.getElementById("hi");
 
		// Use the Spacelet class from Spaceify API
		spacelet = new Spacelet();
 
		// Start the spacelet having unique_name "hello"
		var hi = new Hi();
		spacelet.start(hi, "hello");
		}, false);
 
	// The client-side spacelet application
	function Hi()
		{
		var self = this;
 
		// The required service
		var service = null;
		var serviceName = "spaceify.org/services/hello";
 
		// This method is called if the spacelet was started succesfully
		self.start = function()
			{
			// Get the service and call "hello" RPC method of the spacelet (pass href as name)
			service = spacelet.getRequiredService(serviceName);
			service.callRpc("hello", [window.location.href], self, hello);
			}
 
		// This method is called if starting the spacelet failed
		self.fail = function()
			{
			hiDiv.appendChild(document.createTextNode("Failed to start the spacelet."));
			}
 
		// Print the response from the hello RPC call
		var hello = function(err, response)
			{
			hiDiv.appendChild(document.createTextNode(err ? err.message : response));
			}
		}
	</script>
</head>
 
<body>
	<div id="hi" style="font-size: 1.4em; font-weight: bold;">
	</div>
</body>
 
</html>

Summary of the phases.

  • Load the application API.
  • Wait for the page to load.
  • Start the spacelet.
  • Get the service the client-side of the spacelet requires (the service provided by the edge-side of the spacelet). The service returned by getRequiredService is an instance of the Service API class.
  • Call the RPC method of the service.
  • Output the return value of the RPC call to the web page.

Edge-side

The edge-side application is kept intentionally minimal. Only the essential files are present in the application package.

The application package

application
├── spaceify.manifest
└── hello.js

The application package has the mandatory application/ directory, manifest file and the optional but essential executable file.

The manifest

spaceify.manifest
{
  "provides_services": [
    {
      "service_name": "spaceify.org/services/hello",
      "service_type": "open"
    }
  ],
  "name": "Hello",
  "unique_name": "hello",
  "version": "1.0.0",
  "type": "spacelet",
  "category": "educational",
  "start_command": "node hello.js",
  "shared": true,
  "origins": [
    "spaceify.org"
  ],
  "short_description": "Spacelet example.",
  "appstore_description": "Spacelet example.",
  "developer": {
    "name": "Spaceify Oy",
    "url": "http://spaceify.net",
    "email": "admin@spaceify.net"
  }
}

The manifest contains all the mandatory fields which make the spacelet unique among other spacelets. The optional provides_services and start_command fields make the spacelet functional. Without them the spacelet would be installable but unusable.

Applications can connect to the service listed in the provides_services field and call its RPC methods. The start_command is used to start the spacelet running. The executable is a Node.js program in the root of the application directory. The spacelet can be used only from spaceify.org origin.

The executable file

hello.js
// The same application class can be used with spacelets
var spaceify = require("/api/spaceifyapplication.js");
 
// The edge-side spacelet application
function Hello()
	{
	var self = this;
 
	// The provided service
	var service = null;
	var serviceName = "spaceify.org/services/hello";
 
	// This method is called if spacelet is started succesfully
	self.start = function()
		{
		// Get the provided service and expose the RPC method
		service = spaceify.getProvidedService(serviceName);
		service.exposeRpcMethod("hello", self, hello);
		}
 
	// This method is called if starting the spacelet fails
	self.fail = function()
		{
		}
 
	// Say hello to the caller of this RPC method
	var hello = function(name, callObj, callback)
		{
		callback(null, "Hello, " + name + ".");
		}
	}
 
// Start the spacelet
var hello = new Hello();
spaceify.start(hello);

Comparison

At first look the edge-side code looks simpler than the client-side code. Once the client-side code is cleared of all the HTML they look almost the same.

Client-side

<script src="spaceify.api.js"></script>
...
var hello = new Hello();
spacelet.start(hello, "hello");

Edge-side

var spaceify = require("/api/spaceifyapplication.js");
...
var hello = new Hello();
spaceify.start(hello);

In the edge-side the Spacelet class is unusable because edge-side applications can not start spacelets. This is irrelevant because edge-side spacelets are equivalent to applications. The SpaceifyApplication class can be therefore used by the spacelets also.

Installing the spacelet

Method 1 - Manual package creation

Create the application package manually based on the instrutions above. Install it to Spaceify edge from the current working directory (where the application/ directory is) with the spm command.

spm install

Method 2 - Quick installation

If you want to save the trouble of creating the application package manually, download this ready-made package hello.zip and install it with spm.

spm install hello.zip

Testing the spacelet

The spacelet can be tested by browsing to URL http://spaceify.org/hello/. The web page should now display

Hello, http://spaceify.org/hello/.
Close
copyright © Spaceify.org 2014