How to write your own Aukyla Frontend
Introduction
This is a tutorial on how to write your own Aukyla Frontend. Frontends serve as entry points for applications in the Aukyla Platform. Here's how it works: Within the Aukyla Platform, page requests are handled by the index.php script that's provided by the platform. This script performs some initialization tasks and then passes control to one of possibly many frontends. When you have a fresh installation of the Aukyla Platform, you will have exactly one frontend installed, which will also be set as the default frontend. This frontend is called the Aukyla Administration Area, which allows you to perform certain administration tasks when logged in. To make some good use of the platform however, you will likely either want to install additional frontends from someone else or create and install your own frontend. Installing frontends is covered briefly in the next section. Creating new frontends is what the rest of this tutorial is about, and I will describe the process by showing you how to create a Hello World frontend.
Getting Started
Installation of frontends, like any new component you want to install on the Aukyla Platform, is done by deploying an Aukyla Application Package (AAP). In this section I will describe how you can create a basic AAP.
We start by creating an empty directory to put our little project in. We call this directory helloworld. Now all that's needed to create an installable package from this directory is to put a file called package.xml inside the directory which describes the package. At the very minimum, this file will look like this:
<?xml version="1.0" encoding="utf-8"?>
<package>
<shortName>helloworld</shortName>
</package>
This will just define a package named helloworld with no contents or additional meta-data whatsoever. If you've created this file you can call the utility create_package.php from this same directory, as so:
# create_package.php Created package helloworld.aap.
This will have generated a package file that should be identical to this file: helloworld1.aap. You can try to install this file in the Aukyla Administration Area under the Packages tab, or you can install it from the console using the following command:
# install_package.php helloworld.aap Package installed.
Now we add a file in which we will create the actual frontend. Frontends are located in the plugins/Frontends directory, so you should create that directory. Within that directory, you then create a file named HelloWorld.php. Put the following contents in the frontend file:
<?php echo 'Hello World!'; ?>
We will have to register this file in the package.xml file, and with some added meta-data the package.xml file will come to look like this:
<?xml version="1.0" encoding="utf-8"?>
<package>
<shortName>helloworld</shortName>
<name>Hello World Example</name>
<description>This package is used as an example of how
to create a Hello World frontend.</description>
<supplier>Your Name</supplier>
<version>1.0</version>
<files>
<file>plugins/Frontends/HelloWorld.php</file>
</files>
</package>
If you now recreate the package with the earlier command, you will get a package like this one: helloworld2.aap. You should be able to install the file now as well, and your frontend will be available immediately.
Now that the frontend is installed, how do you access it? Just type in the address of the server you're working on in your webbrowser, and add the query ?frontend=HelloWorld. So, if you're working on your local machine, just go to http://127.0.0.1/?frontend=HelloWorld. If everything is alright, you should now see the message "Hello World!" in your webbrowser and you have yourself a working frontend!
If you get a 403 Access Forbidden error, you should try to log in to the Aukyla Administration Area and try again. By default, new frontends are shielded from anonymous users. If you get a different error, there's probably some configuration problem. If you can't get it to work, we'd like to hear from you, so maybe we can resolve your problem.
Configuring access to frontends
With a default installation, anonymous users (anyone who is not logged in) only get access to the default frontend and frontends which are explicitly whitelisted. To set the Hello World frontend as default, also making it available to anonymous users, just set the Default frontend setting in the Server tab of the Aukyla Administration Area to "HelloWorld". You can also edit the file config/global.conf directly and adjust the setting like this:
frontend = HelloWorld
At this point, you won't need the ?frontend=HelloWorld query anymore to access the Hello World frontend. To get back to the Administration Area frontend however, you will have to use the query ?frontend=Admin now.
Making use of widgets
The Hello World message we have seen thus far hasn't been very interesting, moreso because the message is just plain text and not even HTML as expected. To help you with building HTML interfaces, the Aukyla Platform provides a set of widgets. To create a new HTML interface showing just a single label with the message Hello World, we modify the file HelloWorld.php to look like this:
<?php
require_once('GUI.php');
$mainWindow = new MainWindow();
new Label($mainWindow, "Hello World!");
$mainWindow->show();
?>
If you recreate and install the package you will notice that when requesting the Hello World frontend, you will get the same message. But this time, if you look at the source, you will see that a nice HTML document has been created for you.
Discussing all the available widgets is beyond the scope of this how-to, but if you take a look at the class hierarchy in the API reference, you will quickly spot the available widgets. (Hint: They're all the classes that inherit from the base class Widget.)
Accessing user information
I will show some more examples to give you an idea on how to use various aspects of the functionality offered by the Aukyla Platform. Let's assume we want to change the message "Hello World" into "Hello <name of current user>!". We will now have to find out the name of the currently logged in user. As of version 2.1 of the Aukyla Platform, we have two main classes that come into play here. These are the Login class and the CredentialManager class. The Login class is responsible for the actual logging in part of user management, performing authentication, keeping track of sessions, etcetera. The CredentialManager is responsible for user and group credentials, it knows about user passwords, attributes, etcetera. Again, both are described in more detail in the API reference.
In this case, we are interested in the name of the currently logged in user. This is an attribute of a user, and we will ask the CredentialManager for it using the function CredentialManager::personalAttribute(). Note that both the Login and the CredentialManager classes are singletons, meaning we need to get an instance of the CredentialManager using the instance() function, before we can use it.
The code of HelloWorld.php now comes to look like this:
<?php
require_once('GUI.php');
$credentialManager = CredentialManager::instance();
$fullName = $credentialManager->personalAttribute('full-name');
$mainWindow = new MainWindow();
new Label($mainWindow, "Hello $fullName!");
$mainWindow->show();
?>
If you have a sharp eye, you'll notice that I start using the CredentialManager class, but I'm not including any new files as I did to get access to the GUI widgets. This is because you can rely on the index.php script having initialized the Login and CredentialManager instances. This makes handling of logging in and out of users fully transparent and frontends don't need to worry about this. They can just query who is logged in and act on that, all the details are handled by the Aukyla Platform.
Making your frontend friendly to multiple languages
The frontend we have now produces a Hello World message in English, but maybe we'd like to support other languages as well. For that purpose we have the Locale class, which is again a singleton. This class takes care of loading translations and translating messages using these translations. The function for loading translations is called loadTranslation(), and for convenience there's a short-named global function called i18n() that uses the Locale class to perform translating of messages. You can see it in action in the following snippet:
<?php
require_once('GUI.php');
Locale::instance()->loadTranslation('plugins/Frontends/HelloWorld');
$credentialManager = CredentialManager::instance();
$fullName = $credentialManager->personalAttribute('full-name');
$mainWindow = new MainWindow();
new Label($mainWindow, i18n("Hello %1!", $fullName));
$mainWindow->show();
?>
This code will work, but we don't have any translations yet. So, let's add a Dutch translation now by creating a translation file. The file should be placed in the directory locale/plugins/Frontends/HelloWorld, where the last part matches the string in the path given in loadTranslation(). The file should be named nl.po indicating it is the Dutch translation. Translation files use a subset of the PO file format. Now, all the file needs is a translation for the string in the source code, as follows:
msgid "Hello %1!" msgstr "Hallo %1!"
Of course, the file should be registered in the package.xml using a line like this:
<file>locale/plugins/Frontends/HelloWorld/nl.po</file>
You can now recreate and install the package and the translation will work automatically. Assuming a default configuration of your Aukyla Platform, every visitor who has set his webbrowser to use the Dutch language will automatically see the translated string rather than the English one. In the General tab of the Aukyla Administration Area you can also force the default language for all users.
Escaping strings
There's still a small error in our frontend which should be addressed. We are building an HTML interface, but we're also adding arbitrary strings as content into the output. Ask yourself, what would happen if a user's full name contained characters that have special meaning in HTML? While in this example the strings are coming from reliable sources (our own translation file and the credential database), in many cases it is possible for users to supply the strings that should be displayed. In fact, even the credential database can't be blindly trusted, because another frontend might allow users to change their own name, in which case our frontend would gladly include this string in its output. The solution is to escape all strings that might possibly come from an unreliable source when including them the interface we create. You may use the PHP function htmlspecialchars() for this purpose, or use the function String::safe() which is provided by the Aukyla Platform and which also handles different character set encodings.
Here's an example of the code of our frontend with safe strings:
<?php
require_once('GUI.php');
Locale::instance()->loadTranslation('plugins/Frontends/HelloWorld');
$credentialManager = CredentialManager::instance();
$fullName = $credentialManager->personalAttribute('full-name');
$mainWindow = new MainWindow();
new Label($mainWindow, i18n("Hello %1!", String::safe($fullName)));
$mainWindow->show();
?>
Final notes
You should now have a good starting point on how to create an Aukyla Frontend, which will hopefully get you up to speed before you start programming your own full-blown applications upon the Aukyla Platform. The final package containing all the sources of this tutorial is here: helloworld3.aap. If you want a bigger application to learn from on how the Platform works, you should try and check out ADMS.
For further reading on how to construct a package.xml file, see the document The Aukyla Application Package Format.
Remember, if you go on your way digging into what the Aukyla Platform has to offer, the API reference is your friend.
If you have any remaining questions or you think you got stuck somewhere, please do not hesitate to contact us.