uvicate/webapp

Creating and manage Ajax-Translatable Applications

v1.0.5 2014-05-20 19:27 UTC

MIT

• Victor Quiroz

• ajax
• translate
• webapp

README

AJAX WebApp handler.

Create AJAX web apps with translation support

How to use it?

The first thing to do is initialize an object and tell it the modules you are going to use in your platform.

var modulesApp = {
	module1: {url: 'modules/', nombre: 'module1'},
	module2: {url: 'modules/', nombre: 'module2'}
}

the previous code is a JSON with the modules that the platform will have. Then, proceed to create the Object.

var j = {name: 'My App', modules:modules, div:'#content'};
App = new AppSystem(j);
App.init(function(){});

The main object is initialized now. This object will hold all the neccesary variables for us. Although the main object is all set up an ready to rumble, the modules have not yet been initialized, so you may want to create a menu to tell the user about your modules or start a module right away, in any case you have to start a module.

App.getModule('module1');
App.current.start()

getModule will set the current module to the one you searched, and then you have to start it. The start process will call this files in order:

1. The CSS file
2. The main HTML file
3. The XML file of the current language
4. The main JS file

Setting up the ftp Structure

A modules folder will hold all the client side (JS, HTML, CSS) called "modules" or a custom name. Inside that folder all the existing modules will be put.

Each module will have 3 folders with the following files:

• css/style.css
• html/main.html
• js/main.js

For the languages, you have to create a folder called "language" and within will have all the supported languages of your platform. For default the main language is English, the "English" language folder must be called with the language code "en", for spanish would be "es" and so on.

• language/
  • en
  • es

Each language folder must contain a main xml file called "main" and must have all the modules in folders aswell. Each module in the language folder must have a "content.xml" as following:

• en/
  • main.xml *module1/ *content.xml *module2/ *content.xml

The main xml of the language is intended for all the texts you may repeat in some or all the modules, like name days or month names, etc. And the content xml of each module is for that module specifically.

All the xml files must be as following

<content>
		<dom>
			<title>Hello, I'm a web app</title>
			<change-language>Change language</change-language>
		</dom>
		<exra-text>Oh noes!</exra-text>
</content>

1. An optional utf encoding at the beginning of the file http://www.w3schools.com/xml/xml_encoding.asp
2. The "content" node must exist, although the name is not mandatory.
3. the "dom" node is mandatory.

Linking the HTML with the Language

It is advised that you don't use any text in your HTML files or the translation will not be possible. The desired DOM nodes to be translated must have a tag called "data-ltag" which will have the name of the tag in the XML file.

<h1 data-ltag="title"></h1>

The h1 tag will call the "title" node in the XML explained before. The translation will happen automatically when starting the module. All the tags within the "dom" tag in the XML file will be searched in the HTML file each time the module is translated.

But if you create dom dinamically you have two options of calling Language text.

1. Re-translating the site.

App.current.translate()

This will read the current dom and re translate all that matches

1. Calling the nodes manually.

var text = App.current.language.getText('exra-text');

the "getText" method will search only in the current XML file, but if you want to get text of the main XML of the language, use this.

var mainText = App.current.language.getMainText('main-text');

the text variable will hold the "Oh noes!" string, doesn't matter that it is outside the "dom" tag of the XML, and it is better that it is outside, because this string will be used dynamically and only in certain cases, not every time the html is called.

Translating the app to another language

If the application is English and the user wants it in Spanish, this is done as following

App.current.translateTo('es');

Setup

For easy startup I added a Python script that helps to create all the needed directories, which can be a very repetitive task if you have many projects.

The first thing to do is to configure the setup.json

{
	"project":"foo",
	"project_path":"bar",
	"modules":["login", "backend", "frontend"],
	"module_path":"modules",
	"languages":["en", "es"]
}

First of all, the project will specify the root path of the project, if you are starting a new project the name of the project will be the new directory in which all the modules and languages will be stored. Inside this new path, you will have to create the index.html and all that. See the demo for a better example :)

The modules are inside an array, in this case there are three of them: login, backend and frontend every module will have all required files. The module_path will be the path for all the modules, in this case it will be to bar/modules/

The languages work the same way, in this case my application will support english and spanish.

After all the configuration is ready then go to the terminal and type

python setup.py

All the files will be created after that, now you are ready to go!

Requirements

Modern Browser:

• Firefox
• Google Chrome
• Safari
• Opera
• IE > 9