INDEX

Spacelet Example

As is discussed in the Spacelet subsection, spacelets comprise of server-side and client-side applications. The client-side application, a web page with JavaScript code, starts and uses the server-side application of the spacelet. In this example the client-side web page is served from Spaceify's server.

Client-side

The client-side web page is in URL https://spaceify.org/hello. Experimenting with the web page file is naturally impossible now because it is in Spaceify's server. Use the example index.html page as a reference to make your own web pages and serve them from your own web server.

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>

The comments go into detail about what is happening on the web page. To summarized the steps

  • Load the application API
  • Wait for the page to be loaded
  • Start the spacelet
  • Get the service the client-side of the spacelet requires (the service provided by the server-side of the spacelet )
  • Call the RPC method of the service.
  • The service returned by getRequiredService is an instance of the Service API class.

Server-side

The server-side application is kept intentionally minimal in this example. Only the essential files are present in the application package. The application package has the following structure with the mandatory application/ directory and manifest file and the optional but essential executable file in it.

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

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 to the Spaceify edge but it would do nothing.

With the provides_services field the spacelet makes itself available to use for others. Other applications can connect to the service and call its RPC methods. The start_command is used to actually start the spacelet running. The 'executable' in this example is a Node.js program. The origins field simply tells Spaceify to allow the spacelet to used only from a web page originating from spaceify.org.

The executable file

hello.js
// The same application class can be used with spacelets
var spaceify = require("/var/lib/spaceify/code/spaceifyapplication.js");
 
// The server-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 server-side code looks simpler but once the client-side code is cleared of all the HTML they look almost the same.

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

vs.

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

In server-side the Spacelet class is unusable because server-side applications can not start spacelets. But this is irrelevant because in server-side sandboxed applications and spacelets are 'applications' and the SpaceifyApplication class suits for both of them. Thus, server-side app can specifically use the SpaceifyApplication class.

One fundamental difference between client- and server-side applications is the use of service. Client-side requires services and calls RPC methods through them and server-side provides services and exposes RPC methods through the service for clients to call.

Installing the spacelet

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

spm install

If you want to save the trouble of creating the application package manually, the whole application package, including the html and JavaScript files, is available in URL https://spaceify.org/hello/hello.zip.

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 read

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