Version: 10.0 / Modifications: 0
Developing Web Applications using the Composable Architecture Platform Framework often requires collaboration between server-side rule writers and client-side web page designers.
The Composable Architecture Platform Framework provides a methodology to make this collaboration as easy and seamless as possible.
This guide provides best practices examples of the various workflows that go into the development of a new application and the maintenance of an existing one.
As a best practice, web applications should be designed from the perspective of function. This means rule writers must have basic HTML and JavaScript skills, but are not required to understand the intricacies of making a web page responsive and attractive once functionality is achieved.
Modern web applications rely heavily on AJAX, functional JavaScript, JavaScript and JQuery libraries and other tools that define functionality, but not necessarily look and feel (which is typically achieved using CSS).
So, a web application should be started by the rule writers and contain the bare minimum of design elements to be functional. After that the role of the web page designers will be to make those pages shiny and friendly.
Throughout this manual we are going to work through a very simple example to illustrate the steps involved. Each section will have either [Rules], [Admin] and/or [Web] in their headlines to denote which role the section applies to. This allows you to quickly skip sections that may not be relevant to your job.
Before you can start on this example, please install the “Web Application Tutorial” repository from the update server and create roles and users for the rule writers and web designers. Then deploy the repository to a proxy server for the users to access.
The web designer role should have:
Server Permissions: VIEW, STOP, START and DEPLOY CONTENT for the Proxy Server
Repository Permissions: VIEW, VIEW CONTENT, EDIT CONTENT and DEPLOY CONTENT for the Web Application Tutorial repository.
The tutorial application is a simple data maintenance app. You can add and delete quotes from your favorite authors. The landing page ([server]/index.html) looks like this:
To create a new quote, enter an author and click on Create:
The new quote is now stored:
And you can add a few:
In turn, to remove a quote, just click on the adjacent Delete button.
So, we now have a fully functional (albeit very ugly) web application.
The repository installed contains a configuration, some basic rules and content for an app that can be learned in a few minutes. We hasten to add that the application is not secure, has no validation and the patterns used can be a reference for functionality only.
The Startup rule set defines the Data Set used, the SubmitManager rule sets determines what happens when a button is clicked and the ContentManager rule set grabs the row snippet from the content files, builds the table rows and inserts them into the page. We will explain the page components in the next section for web designers.
It is now imperative that you train the web designer in the application functionality so that modifications made can be tested by the designer directly.
When you first log into the Composable Architecture Platform console, you are greeted with the following interface:
Before you do anything else, you should change your assigned password to one of your own choice. You do this by clicking on the Password button (top right).
The 8 radio buttons each represent a different desktop. For now, just leave the first one active only.
To get started, click on Start -> Servers:
This will open a new window with the servers you can control:
You can minimize, maximize or close the window using the controls in the top right corner:
To move the window around, click down on the window header and drag it where you want it.
To resize the window, use the resize anchor in the bottom right corner:
Every window you open, and position stays in place if you log out and back in, so it pays to spend a little time organizing your desktop.
In the window you just opened, you can see the Proxy Server. Click on it to see the current state of the server. It should look like this:
You will likely be limited to Stopping and Starting the server and accessing the console. The console window is mainly used by server-side developers but can be useful if you are trying to identify a problem.
In most cases it will show something as simple as this:
Servers are instances of application containers, they are not physical servers. There is normally no risk associated with stopping and starting development servers.
To work with your assigned repositories, click on Start -> Repositories:
You will receive a list of repositories that you can access:
Click on the Web Application Tutorial:
Then click on the View button. This will open the list of content files for you and close the repository window. Here we have expanded all the subfolders to make it easier to see:
So the entire application at this point contains just 2 files and 1 folder: “index.html”, the folder “snippets” and the file “quotefragment.snippet”.
At this stage, to make your life as easy as possible, we suggest you arrange your desktop similarly to the below:
You can (with some difficulty) work with the files directly through the console, uploading and downloading files as you need, but the Composable Architecture Platform console contains a much easier way to manage the lifecycle of you web development using your local file system, which we will discuss next.
Whenever you are assigned a repository where you need to exclusively maintain or modify content files, the simplest and easiest way is to work in a “scratch” folder.
A scratch folder can either contain ALL the content files in the repository or just a sub-set. The benefit of using a scratch folder is that anything you add or change will be synchronized with the target server immediately, allowing you to test your changes without having to perform any form of deployment task.
It is important to understand that those synchronizations are temporary. They will be removed when you either: Restart the server or redeploy the repository to the server. More about this later.
For now, start by clicking on “Content Files” in the repository tree:
Since we are just starting the application, the correct approach now is do download all the artifacts and use them to create our scratch folder. To do this, click on Download. The repository content will download as a zip file:
Create a new scratch folder somewhere in your file system and copy the zip file to it and unzip it:
We now have our artefacts:
IMPORTANT: You MUST unzip the folder even if your file system supports moving into a zip file directly as the synchronization in most cases does not work with a zip file on it’s own.
So, let’s open the folder:
These are our artifacts that we need to edit and make attractive. So now we need to connect the Scratch folder to the server.
To connect the folder to the server, we go back to the Composable Architecture Platform console and click on Live Web Development:
This gives you an option to select a server that you can connect content to:
Select the Proxy Server and click on Live Web Development again.
(Should the Proxy Server be greyed out in the list then it is most likely stopped. In that case open the Servers window, select the Proxy Server and click on Start and wait 30 seconds – then return to the window above and click on Refresh).
You are now ready to link the server and the local folder:
To do this, drag the root folder inside the scratch folder (Web Application Tutorial) into the drop zone in the Window:
Your local folder and the server’s temporary content space will now synchronize. Unless you have a slow internet connection, this happens very quickly. You can see the process of what remains to be synchronized in the Queued section in the window.
If everything went well, you will see this:
IMPORTANT: If you close the window, your session expires, or you log out of the console then you will be disconnected. Do not despair, simply reconnect and the console will only synchronize from where you left off.
Your local folder and the server are now connected. In the next section we will test it.
To test the connection, we are going to open the index.html file and make a very simple change. For this demo we will use the Atom editor, but you can use any tool of your choice as long as it saves to your scratch folder. Here is a listing of the index.html page.
You will notice that it is just basic HTML with one little anomaly: The $QUOTES$ tag inside the table. The reason for the placement of this tag is as a placeholder for when the server generates the list of quotes.
It is EXTREMELY important for the application functionality that you do NOT change the name of any of these tags, nor can you change the name or id attribute of any elements contained in the page.
In most cases you can change the tags (for example turning <span> into <div> or a table into <section> tags). However you must verify that the application remains functional in case there are JavaScript dependencies.
NOTE TO RULE WRITERS: When you create tags that contains snippets, it is important to include a comment about where the snippet can be found.
In our example application, the snippet to include looks like this:
As you can see, this snippet represents a single line in the table that the application can use to control the formatting of that line and even some actions as shown above.
So let’s modify the index.html file with something subtle first. Try changing:
To:
Wait 3 seconds then refresh the application page:
At this stage you can now add sub-folder to your scratch folder, add css files, images, JavaScript libraries, fonts and anything else that can help you style the page.
For example, we created a new folder named css:
Then we added a file named style.css to that folder:
And then we import that style sheet into our main page:
And save the changes. Within seconds the page now presents as:
And you can test that none of your changes have broken functionality.
At this point we hope that it is clear that working on the web design is now just a matter of respecting the developer tags in the pages and using your skills.
It is important to understand that changes in your scratch directory are always ADDED to the server content delivery. If you delete files, they will not be deleted from the server’s temporary content system, but they will be removed when you make the changes from your scratch folder permanent.
The last step in the initial design phase is to make the changes you have made permanent. To do this you must return to the console:
The first thing you should do is disconnect the synchronization by closing the synchronization window and then open the content files window:
Scroll down to the bottom of the page and get ready to upload your changes:
You should set the Upload type to Folder and then click on Choose Files.
Select the application content folder and click on Upload. You will possibly receive a warning:
Confirm by clicking on Upload and then click on the Upload Button:
All your changes will now be uploaded to the master content for the repository:
IMPORTANT: Whatever files you upload will be ADDED to the repository and will only create new files or replace existing files with the same name. Files in the master content with names not existing in your scratch folder will stay in place. This concept is useful for application maintenance which we will discuss in the next chapter.
Once your files finish uploading, the last step is to deploy them to the server’s permanent content delivery system.
To do this, click Content Files and then on the Deploy button:
You will be asked to pick one or more servers to deploy your content to:
Select the Proxy Server and click on Deploy. The server window will open and if you have a lot of content to deploy you will see a progress bar. However, in our case it will probably be so quick that you will not even notice:
So, close the server window, log out and inform the rule writer that you have completed your work.
The maintenance life cycle of a web application’s content files differs from the initial creation in several ways:
It may be performed by the rule writer in isolation
It may involve the web designer styling new features
It may only involve a small subset of the application
For these reasons you may not always wish to create a complete scratch folder with all the required synchronization of image files etc.
If you are working collaboratively with other users, you should ALWAYS download the latest files from the repository before making any changes. Do not rely on an old scratch folder as you will possibly remove someone else’s work.
The good news is that anything you place in the scratch folder will either override or add to the content. Nothing will ever be deleted.
So before you synchronize your scratch folder, you can comfortably delete anything you do not intend to change after you have unzipped the download.
Alternatively you can create a scratch folder by downloading individual files from within the portal and copying them into the right location in the scratch folder (remembering to create the correct matching sub-folders if needed):
Once again, after you have completed your scratch folder you should connect it to the server and make your modifications that way. There are two reasons for this:
You can test your changes instantly
You can verify that you are not accidentally stepping on someone’s toes (see below)
If you just change one or two files you may be tempted to simply upload your file changes and deploy them. We do however strongly discourage that approach because it means you test after deploy (permanent) and you have not performed a collaboration check.
The collaboration check tells you if someone else is also doing work with a scratch folder at the same time as you are. It will show up before you connect for synchronization as follows:
If you see this warning you should NOT connect your scratch folder without communicating with the named user.
The platform contains a rule named “Merge HTML Pages”. This rule is used to merge content into a wrapping page with headers and footers.
For example, consider the following master.html template:
It contains the headers and footers for the pages, but not the actual content. You can have more than one template in the same application if needs be.
The important part is line 18 in the above code. This is where the content for each page will be inserted, although any <head> tags in the content will be appended to the page just before the </head> in the template.
These rules do of course work with live web development, so the web designer can modify them on the fly while testing content.
For example:
When merged with the master.html page will produce:
Notice line 11 where the <title> tag is not inserted and line 18 where the content is inserted.
It is possible to control where precisely the <head> information is inserted into the template. Sometimes this is necessary to give some JavaScript libraries preference over others. To specify a precise spot in the master template where content <head> information should be insert, place the following comment at that location:
If your application needs to be translated into multiple languages and locales, there are tree rules to help you:
This rule is usually placed either immediately after all static content is loaded for any given page, but before any dynamic content is injected into the page. The Content Variable should contain the content to be translated.
The rule can determine if the content is HTML or simply plain text. If HTML, the rule will isolate constants such as plain HTML text, <select> options, input place holders etc., being fully HTML aware.
The rule is capable of recording text that needs to be translated and can write that text out to one or more files (merging it with existing known translations).
Building translation files depends on the content of the global variable BUILD_TRANSLATION, rather than a property. This approach is to enable the easy switching on/off of translation recording between development and production without the need to change the rule structure.
If the BUILD_TRANSLATION global variable is set to “Yes” the X Engine will write out fresh translation files in the format “translation-"+locale+".utf8” to the home folder on the target server.
So to get a translation file that can be handed to a local language expert, let the rule “learn” all the text that should be translated and then have the language expert translate that.
The rule is capable of translation into complex character languages such and Chinese and Japanese. Please see the rule help file for further information.
Use this rule to convert international edited values (currency, numbers, dates) to a usable internal format.
This rule can convert input from any given locale into a consistent US internal format for processing.
All values returned uses US number formatting (. as decimal point) and all dates will be returned in YYYYMMDD format.
This rule is the inverse of the previous rule. It takes US formatted numbers and YYYYMMDD formatted dates and converts them to the appropriate local version (for example: MM/DD/YY for the US.
The framework contains a HTML aware rule that can significantly simplify the co-operation between the rule writer and the web designer.
Using this rule, you can set the value of check radio buttons, checkboxes, select options in lists and input fields in a HTML document. You can also set the value of text areas, output tags, spans, labels and divs. For these tags, the value obviously refers to the innerHTML of those tags.
For checkboxes, the value can either be “on”, “true” or “checked” if no specific value has been defined for the checkbox. For lists (select tag), the options to select must have a value attribute.
Tags to set can be identified by name, ID or class name. If more than one instance of a identifier exists, all will be set.
This approach can in many cases be used to avoid using $TAGS$ in the HTML and the web designer can instead provide a page with sample values that makes visual sense on its own and the rule writer simply overrides those sample values before serving the page to the user.
