Elements AJAX Web Framework Wiki

An object oriented event driven fully AJAX web application framework

Status: Beta

Brought to you by: neuronworks

quickstart

Home / Elements Quickstart Guide

Elements Quickstart Guide

Thank you for your interest of the Elements AJAX Web Framework. Now if you have already downloaded the latest Elements version, this quick start guide will tell you how to set it up for immediate use.

Platform Requirements

To run properly Elements requires PHP 5 enabled web server, and modern browser that supports Javascript. Elements will not run with Javascript disabled!

Installation Guide

To install, simply extract the files from the distribution archive into a folder in your web server root directory.

For example, if your web root directory is on /app/www, first create a new directory inside it to store the extracted files, i.e. elements
Extract all files from the download archive into that directory (i.e. /app/www/elements)
After all of the files extracted successfully, you may then test the installation by accessing it through your web browser (i.e. from http://localhost/elements), you should see the "Hello world!" page.

Directory Structure

The framework contain directories for specific purposes, explained as follow:

app
Contains the content and logic of your application, you should store your entire application content here, this is the only folder that will not get overwritten during Elements core updates.
- bin
  Put common PHP classes / libraries specific for your application needs here. These then can be included by the GUIs or services.
- cfg
  You may store your application specific configuration here. Also contains the special "bootstrap" file that will be automatically executed during start ups.
- css
  Store stylesheet (.css) files here, it will be automatically loaded for your application.
- gui
  This is where all the GUI and event handler files resides. During start up the "index.php" and "index.js" file is loaded.
- img
  Store media files here.
- lib
  Put Javascript (.js) files / libraries specific for your application needs here.
- svc
  This is where all the service files resides.
bin
Elements server core files.
cfg
Directory to store core configuration files.
com
Contains Elements component library.
- lib
  Contains library required by specific components. If a component is a wrapper (i.e. wrapper of DHTMLX component), then the original library should be stored on this directory.
- res
  Contains resource files required by specific components.
ext
Elements client (GUI) core files.
lib
Contains 3rd party library required by the Elements core (i.e. PHP adoDb library).
tmp
Temporary, required by specific component or library.

Your First Application

Now you're ready to create your first application. For starters, let's open the index.php file on the /app/gui directory using your favorite text or PHP editor, you will find this code:

<p>This is the index GUI!</p>
<form>
  <component class="button" name="cmdhello">
    <text value="Click Me!" />
  </component>
</form>

Any PHP files inside the /app/gui directory defines a GUI page. You can use regular HTML to layout your interface. However, on Elements, there is the \<component> tag to define component as part of the layout. Let's try to add a text component:

<p>This is the index GUI!</p>
<form>    
  <component class="text" name="txthello">
    <placeholder value="Type in something..." />
  </component>
  <component class="button" name="cmdhello">
    <text value="Click Me!" />
  </component>
</form>

Each component must have a class and a name, class defines what type of component it is, and name is to identify a component on a page. The code above will render as follow:

your first gui

As you can see, each component also may have a design properties, for example, the text component have the placeholder design property.

Now open the index.js file on the same directory of the index.php file. A Javascript file having the same name with the GUI file will act as an event handler for the corresponding GUI. You will find this code inside the index.js file:

var elementseventhandler = function() {
  return {
    "page_title": "Home",
    "cmdhello_click": function(evt) {

      alert('Hello world!');
    }
  }
}

On the example above, when a click event occurs on the button component cmdhello, a 'Hello world!' message will be displayed on the screen. All event handler is written in the Javascript languange. Now let's add some more logic to the event handler:

var elementseventhandler = function() {
  return {
    "page_title": "Home",
    "cmdhello_click": function(evt) {

      var data = $page.components.txthello.text();
      if (data.length == 0) {
        alert('You type nothing!');
      } else {
        alert('Hello world! You type: ' + data);
      }
    }
  }
}

Now, when a user clicks on the cmdhello button, the data typed on the txthello textbox is retrieved and validated, lastly a message is displayed on screen: