Here is how to implement “data-if”, some debugging-tips and a patched Markuper amongst others.

Introducing a basic “data-if” in Markuper

The Markuper has a great, simple method of adding custom attributes to determine whether or not keep an arbitrary element and it’s content. You may already know the “data-keep-if“-attribute, now – here is “data-if“, a tad more flexible:

/**
Author: Michael Odden
Email: me@michaelodden.com

A simple example of an extension of Opera's Markuper - a Unite JavaScript template-library:
Implementing the "if"-operator, allowing for boolean expressions, and does only show
the element if the value is true.

To allow variables in the expressions, you'll have to download the patched Markuper, currently found at:

http://michaelodden.com/files/unite/template.js

See blogpost for details:

http://michaelodden.com/opera-unite/opera-unite-convenient-tips-and-snippets-for-developers

NB! You should not include data in the attribute which you don't controll 100%, as the method
is currently using "eval". Yup, bad, I know. I'm working on a better approach.

= USAGE:

- In the server side JavaScript, where you initiate the Markuper:

var data = {"sum":101};
var template = new Markuper("path/to/template.html", data);
template.registerDataAttribute('if', dataAttrIf);

- In the template:
<div data-if="{{sum}}>100">
<p>The sum is more than 100</p>
</div>

*/

function dataAttrIf(node, data, key) {
	node.removeAttribute("data-if"); // Remove the attribute, leaving no trails
	if(!eval(key)) {
		node.remove(); // remove the node
		return false; // avoid processing the contents of the node
	}
}

NB! I’m currently using JS’ eval-method, which – in short – is not recommended if you don’t have 100% control of the code being evaluated. While it gives you extreme flexibility, it will probably also affect security. It is amongst others a very common source of XSS-vulnerabilities.

I am working on a better expression-parser, perhaps built upon Markuper’s “operatorsRegExp”, which is used for some neat interpretation of the “data-keep-if”-values. As far as possible I will for now recommend data-keep-if as long as it’s possible, and this is mostly an example of how easy it is to expand the Markuper, and making a little more flexible option needed for an application of mine.

You will also need the patched Markuper found at the bottom of this post (template.js) if you want to allow variables in the expressions. See my previous Unite-post for details.

Check if files exists

I came across a situation where I preferred to use the _request event-handler, which is a “fetch-all” event, this mean that I won’t need to dispatch events for every single action, but rather take care of the logics in one gateway-method. But there is a problem: when using the _request-handler, Unite won’t dispatch through to any publicly available files either, unless explicitly told so. In my case this meant my .css og client-side .js-files wasn’t loaded.

To work around this, I created a function which checks if there is a file matching the current request – and if so serve this instead of continuing with the regular logic.

Remember to include access to the file i/o by adding the following in your config.xml (inside the widget-element):

    <feature name="http://xmlns.opera.com/fileio"></feature>

/**
 * @author	Michael Odden
 * @email	me@michaelodden.com
 * @url		http://michaelodden.com/
 * @description
 * 		Checks if the requested path can be mapped to an existing static file (underneath public_html).
 *		If so: server the static file, otherwise continue the normal flow. Intended used with the _request event handler.
 *
 *
 * @return	mixed - true / false regarding if file exists, or the result of response.closeAndRedispatch ()
 * @param	OperaEvent - e - The event-object as sent to the eventhandler (required)
 * @param	boolean - dispatch - should the method autmaticly dispatch to load the file, or just return true / false.
 */
function requestedFileExists(e, dispatch) {
	var fileExists = true;
	var uri = e.connection.request.uri;
	var dir = opera.io.filesystem.mountSystemDirectory('application');
	dispatch = typeof(dispatch)!="undefined" ? dispatch : true;

	if(dir) {
		try {
			var relPath = uri.replace(new RegExp(e.target.currentServiceName,"i"), "public_html");
			var stream = dir.open(dir.resolve(relPath ), opera.io.filemode.READ);
		} catch(err) {
			fileExists = false;
		}
	}

    return (dispatch && fileExists) ? e.connection.response.closeAndRedispatch() : fileExists;
}

I found it necessary to also have a function which simply checks if there is a public file with a given name, and simply returns true or false.

/**
 * @author	Michael Odden
 * @email	me@michaelodden.com
 * @url		http://michaelodden.com/
 * @description
 * 		Checks if a given file exists under the public_html folder. Returns true / false accordingly.
 *
 *
 * @return	Boolean - true / false regarding if file exists
 * @param	OperaEvent - e - The event-object as sent to the eventhandler (required)
 * @param	String - file - path relative to public_html to look for
 */
function publicFileExists(e, file) {
	var fileExists = true;
	var dir = opera.io.filesystem.mountSystemDirectory('application');

	if(dir) {
		try {
			var relPath = "public_html/" + file;
			var stream = dir.open(dir.resolve(relPath ), opera.io.filemode.READ);
		} catch(err) {
			fileExists = false;
		}
	}

	return fileExists;
}

Usage

window.onload = function() {
	var w = opera.io.webserver;
	if(w) {
		w.addEventListener("_request", onRequest, false);
	}
}

function onRequest(e) {
	// Demo 1: requestedFileExists()
	// Check if the requested URI can match to an existing file under public_html.
	// If so, dispatch directly to that file, and cancel further load
	requestedFileExists(e);

	// Demo 2: publicFileExists()
	// this demo as a whole does the same as Demo 1, but the publicFileExists does
	// only return true / false, and the developer has to decide action herself.
	if(publicFileExists(e, "tesfile.html")) {
		e.connection.response.closeAndRedispatch();
	}
}

Notes to self

window.onload is only run when the application is started (through the Unite Control Panel), and not on each page-load as some would believe.

Markuper does of course need access to the filesystem.

Try-catch is my best friend. If you have some weird situations where your application doesn’t load, it might be because a missing library (not including the file-io through your config.xml etc) then you’ll have to start debugging. By wrapping essential parts in try-catch and check the error-object as passed to the catcher you might save yourself quite some time debugging in the darkness. It is a matter of best-practice to use try-catch on parts of your code that might fail, but it will also come handy as a debugger tool just for checking large or small parts of your code.

JavaScript on both sides

It seems to be a common source of confusion for some: it’s important to remember that – in Unite – JS is used both on the server-side as well as on the client-side. Methods like “alert()”, won’t work on the SSJS (the ones included in the main index.html-file, either directly or indirectly). Pretty obviously, but I remember my first debugging-action was to try an “alert()” .

Recommended

• template.js – patched version of the Markuper, fixing the bugs as mentioned in my previous Unite-article. Thanks goes to António.
• Offical Opera Libraries – Opera does have some really skilled developers, and it’s worth checking out the libraries.
• JavaScript for hackers – a great article, and the title says it all – well worth read for everyone working with JavaScript.

Related posts:

• Adventures in Opera Unite
• Tip of the day: Loose comparisons in PHP gives edgy behaviour

What is Opera Unite

Opera Unite is the latest member in the Opera-family and brings some new ideas to the table. Opera calls it “Reinventing the web” – those kinds of claims will of course provoke a lot of people (especially the know-alls). It does perhaps not reinvent the web, but it does give the users more power and controll of their own data again, as was intended in the – oh so far away – beginning of the web

Opera’s idea is that you should be able to share your own data easily and with whoever you want, and to achieve this Opera has bundled the browser with a web-server. The applications you can share with Opera Unite is closely related to the Opera-widgets, but gives a little more power – i.e. access to the server and file-system through JS. So by using standard web-technologies (SVG, HTML5, CSS, JS…) you can now pretty easily develop server-applications as well.

A popular rant-attack is against the fact that you have to create an opera-account to get this up and running, as Opera uses a proxy (operaunite.com) to organize the traffic and getting through your router. A lot of people complain of this as “Opera monitoring our data” (like this isn’t possible for Google and Facebook already) – so listen: as long as you’re connected to the Internet, your data will pass through quite some servers no matter what. Though luck. Now, if this is a service that will stand the test of time and users, I will expect the possibility for users to either run their own proxy-services or bypass it all together.

Now, what concerns me the most right now, is the security-aspect. A lot of people will by running Opera Unite give any bad people out there (yup, I know you’re out there!) one more frontier to fight on – they can now attack the Opera Unite-server running on your computer, as well as attacking the browser. This means that Opera has to be extremely thorough to eliminate any security-issues that surely will come.

Beside of this, I’m very excited in seeing how this will evolve. They have released some developer-resources already, and I’m sure more will come – so I’m eager to see how developers out there will develop creative tools to run under Unite.

Developer-experiences so far

As this is still in alpha there are a lot of issues I assume will get better when getting closer to release-date. This is meant as tips to other developers more or less new to Unite-development.

Initiating your app

You will need a config.xml, index.html and a javascript-file to get started. Your app can have a setup like this:

• myapp/
• config.xml
• index.html
• script.js

See the config.xml-link for details of the setup of this. The index.html can be a very simple HTML5-file, ie like this:

<!DOCTYPE html>
<script src="script.js"></script>

Now we’re getting started, I’ll give an excerpt of a script.js-file, and give an idea of how it can look:

window.onload = function () {
    w = opera.io.webserver
    if (w)
        // the default page, kind of like index.html : )
        w.addEventListener('_index', showMainPage, false);
        // And two common
        w.addEventListener('newEntry', newEntry, false);
        w.addEventListener('editEntry', editEntry, false);
    }
}

function showMainPage(e) {
    var response = e.connection.response;
    var myhtml = "<!DOCTYPE html><head><title>AppTitle</title>/head><body><h1>Welcome!</h1></body></html>";
    response.write(myhtml);
    response.close();
}

- As you probably can see, we are adding event-listeners to the webserver to listen for actions, and every page/action of an application requires it’s own method which takes care of the logics and displays any contents by writing the necessary HTML. This is good explained in Opera’s documentation so I won’t dive further into that here.

What I’d rather like to mention is those things that will “crash” your app:

Every action-method must accept a named argument for the event-object – which in turn will give access to the response and request-objects. If not specifically named, then the app won’t load.

You will also have to write something (response.write(“something”)) _and_ close the response (response.close()) in the current action, otherwise the app won’t load.

Markuper

Opera does also give out a template-helper, which is just a JS-library which will come handy. I haven’t found a place that distributes it in an organized manner, but you may download it as a part of the barebone-example in the previous link, or you may dissect any of the existing apps (download the .us-file, rename to .zip and extract). It seems there are some different versions out there so beware.

The templater doesn’t currently seem to allow variables in attributes

This is cumbersome, as I’d like to do something like this:

<div id="content" data-import="templates/{{page}}.html"></div>

I assume this will be fixed, as it seems – when skimming through the library – that it should have been taken care of in the XPath-expression looking for the variables. I’m working on a patch.

Imported files through the templater can’t be empty

If you try do something like this:

<div id="content" data-import="templates/content.html"></div>

and the “content.html”-file is empty, then the app won’t load :p.

404 Not found

If you get the “404 Not found – Resource not found” it’s propably a JS-error. Unfortunately you won’t get any better debug-messages by now if you haven’t implemented it yourself (see the “Notifications”-part of this post). Take a close look at your code, and I assume Opera will fix integration with dragonfly in upcoming releases.

POST and GET

GET: e.connection.request.queryItems['id'][0]

POST: e.connection.request.bodyItems['title'][0]

Custom fonts

@font-face {
    font-family: MyFancyFont;
    src: url('fonts/MyFancyFont.ttf');
}
/* Use like this: */
body {
    font-family: MyFancyFont;
}

This is pretty obvious of course, as the new Opera-engine, Presto, has support for a lot of snacks when coming to HTML, CSS and SVG – and hopefully soon more JS-snacks will come as well.

Notifications

You will more than once want to give some kind of notifications, either to yourself as developer or to the end-users. Notifications can ie be debug-messages, or event-messages like incoming message in an IM-app.

opera.postError() will let you post a message which only will appear in the error-console.

widget.showNotification() will pop up a message in the lower right corner of the screen. It’s possible to attach a callback-function which will be called when/if the user clicks on the message.

void opera.postError( <String> message)
void widget.showNotification( <String> message, <Function> callback )

Quick tips

If you want to test any changes made to the javascript-files, you will have to restart the app. If you’ve just changed any HTML-files ie for the Markuper, you can just reload the page as you’d normally do. If none of them seem to work, you might have to remove the app and install it again. Remember to empty the trash as well before installing!

Packaging the app

The app-packages are simply zipped folders, renamed to the prefix “.us” (Unite Service), and to install it it’s only to drag-drop the file onto an Opera Unite-able browser, or if you want to share it online, give it a link like this:

<a type="application/x-opera-uniteservice" href="url/to/myapp.us">Install myapp</a>

Possibly related reading

• Opera Unite Official Site
• Opera Unite Developer Resources
• Unite API Overview
• Opera Unite Howto’s
• Is Opera Unite a revolution, or is it just the fat lady singing?
• Opera breathes down Firefox’s and Chrome’s Necks
• Setting up custom domains for Opera Unite
• How to debug JavaScript problems with Opera
• API: The widget-class
• Unite: Some questions and answers

Related posts:

• Opera Unite: Convenient tips and snippets for developers