Covert Tomato

Using the translation plugin of Yusef, and the appropriate {%trans%} and {%endtrans%} tags along with some JSON, localizing an application is a breeze.¹ The only problem is with pluralisation. So if you follow the documentation, you should get something like this

{%trans with
   "{{myData1}}" as counter and
   "{{myData2}}" as other   and
   "{{moreData}}" as etc %}
   There is {counter} foot
{%plural%}
   There are {counter} feet
{%endtrans%}

This won't work unless you fix the translation thing. The first problem lies within the underscore function: when variables are fetched, they are retrieved as string. However, when testing for plural, the following line does the wrong thing:

if (variables && variables.counter && variables.counter !== 1) 
{ /* plural stuffs */ } 
else 
{ /* singular */

Since the "!==" comparison is used, the test fails. Instead, we can rely on javascript conversion and use != 1

On a side note, there seem to be no support for localizing Date related strings. Even the so nice humanReadable addon of the datelibrary has no support for anything else than English.

1. Except if many hardcoded stuffs are in your code.

The UI plugin adds by default a password protection to the application. This feature stands in the sidebar section "Privacy options for [Application Name]". In this post, I explain the mechanism allowing for such security features, which is implemented by the acl plugin of Yusef.

Overview

Basically, the ACL plugin does nothing more than associating a clearance level with each URL of the application. The clearance level is technically named "access type", while the URL is referred to as a "Resource". Furthermore, the association between an URL and an access type is called an "Access Node".

The acl plugin offers the following access types:

• accessTypes.public: Unlimited access to the resource.
• accessTypes.limited: The resource is only available if you have the password.
• accessTypes.private: The resource is restricted to the owner of the application.

Apart from associating URL to access types, an access node has also a strictness parameter. If an access node is strict, the access type of a resource cannot be changed. Ever.

Getting Started: a Page for the Almighty Owner

Defining a Section
Now that the main terms are defined, we will build a owner-only option page as a practical example. This page will actually be a section of the application. The following code builds such a page and restricts the access to the sole owner:

Yusef.addSectionListener
(
  'options',
  function(connection) { /* render the options page */ },
  {acl: {
    type: 'private', 
    strict: true
  }}
);

This way of adding options may remind one of how the ui plugin is used. Indeed the registration process is roughly the same, except for the recognized options.

I also introduced the strictness parameter earlier. For our option page, we only want the owner to change parameter and never should it be a user. Since we should never change this access type, it makes sense to set a strict access node.

Defining an Action
Of course, this option page will be used to set options. For this purpose, we will use a Yusef Action. Actions are only associated with an access type (level) and are not considered as resources. The following code sets an action for the options page:

Yusef.registerUniteAction
(
  'set-options',
  function (connection) { /* handle the [URL=http://www.cgisecurity.com/xss-faq.html#vendor]user input[/URL] here */ },
  { acl: { 
      level: Yusef.plugins.acl.getAccessTypes().private
  }}
);

We may further wonder how an action can be made available to public or to limited users depending on whether the corresponding section access. One possible way is to set the level to public and check in the action handler whether the section is accessible. For this we can use the hasAccess function of acl, which takes as arguments the connection, and optionally the section and the path within the section. The following code demonstrates this, allowing for only allowed users to save the options:

Yusef.registerUniteActionListener("set-options", 
  function(connection)
  {
     /* Do we have access to the "option" section ? */
     if (!Yusef.plugins.acl.hasAccess(connection))
     {
        /* bad guy. In the actual code, you may want to record this event in some log */
        return false;
     }
  
     /* Clearance check OK; proceed with actually saving the options */
     /* ... */
  
  }, { "acl": Yusef.plugins.acl.getAccessTypes().public });

Changing the Access Type

We defined the strictness of an access node earlier, but nothing was said about how to actually change the access type. For this purpose, Yusef.acl provides functions to read and write an access node: setAccessNode, getAccessNode and hasAccess. These respectively define the access node of a resource, retrieve the current access node of a resource, and determine whether the user has access to a resource. These functions are defined as follows:

setAccessNode = function( serviceWidePath, type, strict )

• serviceWidePath: The path to the resource relative to the application root, including a leading '/'.
• type: A string representing the access type ('private', 'public', 'limited).
• strict: The strictness of the access node.
• Returns true if the access node could be set, as requested or false otherwise.

getAccessNode = function( connection, section, path )

• connection: The connection from which the resource path is to be retrieved.
• section: (optional) The application section of the resource.
• path: (optional) The path under the application section of the resource.
• Returns the function returns the accessNode corresponding to the path.

hasAccess = function( connection, section, path )

• Arguments have the same definition as for getAccessNode.
• Returns true if the user has access to the resource

While most of the parameters are clear, the actual meaning of the path to the resource may be discussed. The most obvious definition is the url to an actual page of the application. However, some applications (e.g. like Fridge) use the index page for various purposes (e.g. displaying user posts and application settings). However, posting new messages, deleting messages, and setting the maximum number of messages can require very different access. In such case, "virtual" urls can be associated to features requiring different security tokens. For example, using access nodes over /security/post, /security/delete and /security/options would solve the problem.

Integration with the UI

In this last section, we get back to where we started this post, and study how the acl and ui plugins are integrated. The UI plugin has indeed some interaction with acl: when a new user navigates to a limited page, a message is shown requiring him/her to provide a password. Another integration, provided in the right side of the default template, allows the owner to change the access type of a page.

To provide ui with these features, acl registers the following actions:

• Yusef_plugins_acl.unlock: checks that the password provided by the user is right. In that case the user goes from "public" privileges to "limited" ones.
• plugins.acl.actions.change: allows the owner to set the access type for the current page

As with any action, the proper unite-action and unite-nonce fields must be set. The other fields needed for these features can be found in the main.html file of default ui template.

Yusef is a nice toolkit, but there are times where it simply won't cut it. One of the things I dislike about yusef is its promise to load every script in the serverScripts directory. Sure, I want each of my script of my app loaded. But I also need some parts loaded before some others (e.g. some utility functions before fetching data off the disk).

Because yusef is all javascript, hacking one's way through it is fairly easy. So let's force yusef to load your application component using the total order imposed by the file name.

Finding yusef's serverScripts loading procedure

One question I asked myself when I first started using yusef was "How does it know that my application is in serverScripts?". It turns out that it knows the directory because of some magic constant set in its configuration:

_config.serverScriptsPath       = '/serverScripts/';

Searching for this constant in the core will show the _loadServerScripts procedure up easily. This is indeed the one procedure we want to hack.

Ordering the files

The _loadServerScripts procedure fetches the script files in the serverScripts {File} variable. This variable is then iterated to load each script in turn.

From this point, ordering the files is a breeze. For my use, simply ordering them by name is enough, but smart coders out there may prefer to order them using some hyper sophisticated comparator. So here's the hack:

serverScripts.refresh();
        
serverScripts.sort(); /* Added: sort scripts by name */
        
for( var i=0,currentFile; currentFile=serverScripts[i]; i++ )

All that's left is to properly name files. For this task, I tend to use a two digits code which goes as follows:

• 0x: utils and or models
• 1x: controllers or views
• 2x: Sorry, i'm very binary, i can't count up to 2

With x chosen to resolve other dependencies that may occurs, or to add some layering semantic.

Extending the system

Sometimes, extending your application with our hack is not enough. Some functionalities that are used over and over, are better fit for a library. It turns out that yusef provides a libraries loader that can be used for that purpose. On a side note, this libraries loader takes care of dependencies between libraries; therefore the naming hack won't be necessary here.

One library yusef does not provide you with is uuid generation. Adding such a library can be done as follows:

1. Get some nice uuid script or write one yourself.
2. Create a uuid subdirectory of the libraries folder and put your uuid script. We suppose in the following that the script is named uuid.js.
3. Add a new file in your uuid subdirectory named setup.xml containing the following:
   

   <setup id="uuid">
       <script>uuid.js</script>
   </setup>

Setup.xml files describes how your library is to be loaded. It takes the following format:

<setup id="your-library-id">
    <script>script_1.js</script>
    ...
    <script>script_n.js</script>
    <depend>library_1</depend>
    ...
    <depend>library_n</depend>
</setup>

When parsing this file, the libraries loader will first resolve all libraries specified in depend. Then all script files will be loaded.

Extending yusef is cool!

I spent the last few days building a new application for Unite. So I read all the nice articles, downloaded the full hello world , and found myself stuck with more questions than answers. Maybe I missed some documentation, but for sure the libraries in the example app offer a helluva lot features. I plan to go over some of these libs in the next few post; hopefully, some official documentation/articles will get available soon. Generally speaking, while this may seem a bit rough for a first post, I plan to use this blog as a way of writing memos about technical stuffs; I'm not too sure about blogging, but since everyone else (and their dog) do so...

Anyway, let me get started by pointing out the PSO lib, used for debugging purposes. This lib acts as a wrapper around opera.postError, which gets error messages straight to the error console. PSO messages are required to have an ID, which is a string identifying the message origin or category.

One can subscribe to messages of interest by specifying IDs:

PSO.sub(id1, id2, ...)

where id1, id2 are the ids. This effectively filters messages out, when no subscription has been made.

Debug messages are published using:

PSO.pub(id, msg)

where id is the message ID, and message is the actual debug information.

Subscribing to the special 'new pub' id, one can subscribe to get a list of new message ids. Other predefined ids in use throughout Yusef can be found at the beginning of yusef/core.js, right under switch( opera.io.webserver.userName ). Some of these are useful when debugging/adding new features to Yusef, while others can tell you important information about why your code fail. Did you register your section properly? Subscribe to 'Yusef.addSectionListener' to know. Which section is requested when you click that link? Subscribe to 'yusef request handle'.

I personally found it useful to express ids as a hierachy (e.g 'fpicalausa.myapp.feature42'), in order to keep code clean component-wise. Going along with this convention, I also modified PSO (see attachment at the end), so that it allows me to subscribe to messages higher in the hierarchy (e.g. 'fpicalaua.myapp' to get all messages in myapp).

Enjoy!

pso.js