README

================================
Elation PHP/JavaScript Framework
================================

This is the Elation PHP/JavaScript framework.  It's designed to be lightweight
and easy to use, allowing the developer to build pages out of reusable
components which can be called in from any template file with {component
name="foo.bar"}


Prerequisites:
--------------
    To run elation, you will need a webserver (Apache 2.x recommended, but Apache
    1.3, Lighttpd, etc. should work as well).  You will also need PHP>=5.2, and by
    default you will also need the php5-sqlite module (can optionally be replaced by
    or used in conjunction with mysql, postgresql, etc)

Initializing Web Environment:
-----------------------------
    $ git clone http://github.com/jbaicoianu/elation.git
    $ cd elation
    $ ./elation web init
    $ sudo cp config/apache-elation.conf /etc/apache2/sites-available/elation
    $ sudo a2enmod rewrite
    $ sudo a2ensite elation

OPTIONAL: Integrating with Zend Framework
-----------------------------------------
    The framework can take advantage of Zend Framework components, although it will not use
    Zend for the MVC structure. It also extends certain components (currently only Zend_Form ->
    Elation_Form) to use with elation. If ZF is present, it'll autoload ZF classes automatically.
    All it needs is a symlink to the /library/Zend directory. (Or you can copy the files in there
    but that's a bit crude and only necessary on systems that do not support symlinks or hardlinks).
    
    $ cd elation/lib
    $ ln -s path_to_Zend_Framework/library/Zend/ Zend

Creating a component:
---------------------
    $ ./elation component create <name>
    $ ./elation component enable <name>


Editing a component:
--------------------
    Components are organized in the ./components directory, and can have any number
    of subcomponents.  Every component consists of a PHP file containing the
    component class and directories for any templates, scripts, CSS, images, or other media
    belonging to this component.  Optionally, there may be a "components" subdirectory which
    can contain any number and depth of subcomponents.  

    For example:

    - elation/
      '- components/
         '- foo/
            |- foo.php
            |- css/
            |  |- bar.css
            |  |- common.css
            |  |- foo.css
            |  '- things.css
            '- images/
            |  |- bar.png
            |  `- whatever.png
            '- scripts/
            |  |- bar.js
            |  |- common.js
            |  '- things.js
            '- templates/
               |- bar.tpl
               |- foo.tpl
               '- things.tpl


    In this example, the templates and PHP would be set up as follows.  This setup
    allows access to the main foo page via http://domain/foo, which sets up a basic
    HTML page structure and then calls in the subcomponents foo.bar and foo.things
    with specific arguments to render them in the correct location on the page.

./components/foo/templates/foo.tpl:
-----------------------------------
    {component name="html.header"}
    {dependency type="component" name="foo"}
    <div id="foo">
      <p>Blah blah blah</p>
      <div id="foo_bar">{component name="foo.bar" barid=$args.barid}</div>
      <div id="foo_things">{component name="foo.things" color="blue"}</div>
    </div>
    {component name="html.footer"}


./components/foo/templates/bar.tpl:
-----------------------------------
    {dependency type="component" name="foo.common"}
    {dependency type="component" name="foo.bar"}
    <div class="bar">
     <h2>{$bar->name|escape:html}</h2>
     <address>{$bar->address|escape:html}</address>
     {component name="foo.things" things=$bar->cocktails}
     </ul> 
    </div>

./components/foo/templates/things.tpl:
-----------------------------------
    {dependency type="component" name="foo.common"}
    {dependency type="component" name="foo.things"}

    <ul class="things">
     {foreach from=$things item=thing}
      <li>{$thing->name}: ${$thing->price}</li>
     {/foreach}
   </ul>


./components/foo/foo.php:
-------------------------
    <?
    class Component_foo extends Component {
      function init() {
        $this->outlet = Outlet::getInstance();
      }

      function controller_foo($args) {
        $response = $this->GetComponentResponse("./foo.tpl");
        $response["args"] = $args;
        return $response;
      }
      function controller_bar($args) {
        $response = $this->GetComponentResponse("./bar.tpl");
        if (!empty($args["barid"])) {
          $response["bar"] = $this->outlet->load("Bar", $args["barid"]);
        } else {
          $response["error"] = "Expected id for bar object";
        }
        return $response;
      }
      function controller_things($args) {
        $response = $this->GetComponentResponse("./things.tpl");
        if (!empty($args["things"])) { // If things are passed in as an argument, use those
          $response["things"] = $args["things"];
        } else if (!empty($args["color"])) { // Otherwise, if we passed a color then get all matching objects from the DB
          $response["things"] = $this->outlet->select("Thing", "WHERE color = ?", array($args["color"]));
        } else {
          $response["error"] = "Expected color parameter, got nothing";
        }
        return $response;
      }
    }  
    ?>

Full Component Structure:
=========================
|- demo
| `- blog
|- elation
| |- orm
| |- component
| `- notes
|- html
|- index
|- ui
`- utils