Coeus Framework  1.0
Coeus Framework Documentation

Table of Contents

  1. Introduction
    1. Purpose
    2. Structure
  2. Getting Started
    1. Copying the framework
    2. Configuration
    3. General Settings
    4. Database Settings
    5. Template Settings
    6. htaccess
  3. The Application
    1. Building Your Application
    2. See The Magic
    3. Script Caching
    4. JavaScript
    5. Adding Data Manipulation
    6. AJAX
    7. Using The Coupon Wallet API
  4. More Documentation

Introduction

Purpose

The purpose of this framework is to provide a framework that is simple, fast, functional, and scalable. Past frameworks have been lacking in one or more of these attributes.

One struggle we've had is the versioning of database structure. There is no easy way to track changes of a SQL database. With new versions of a framework, database structure changes are usually required. With this new framework, MongoDB is used. This allows structure to be handled by the framework data model. Because of this, version control (i.e. git) encompasses database structure.

A challenge every web developer faces is how to marry an MVC model and templating. Best practices dictate a complete separation of not only models, views, and controllers, but also coding languages. The problem is that it's easy to mix PHP inside of HTML, but not very secure. Moreover, HTML developers may not know PHP and vice-versa. However, to get PHP data into HTML required other solutions (like tokens).

A solution to this in this framework is to not use tokens at all. The controller (PHP) can assemble the HTML files by way of Data Object Model (DOM) objects. From there, all view logic is handled by client side languages (i.e. javascript). The only token-like functionality is the ability to inject javascript into the head section of the template. From that point on, the controller's function is mainly to simply output data and let the view controller display it. This solution not only cleans up confusing code, but is extremely fast.

This framework also caches any local CSS and JavaScript file. If there is either of these with a relative link, they are compared (via sha1) to a database of cached files. If there is a change, the framework gets the contents of the file and recaches it into either **/framework/cache/cached.css** or **/framework/cache/cached.js**. The cached files are written in the same order in which they were called within the HTML.

Previous frameworks have been modular. Meaning, the application and all its files are contained in its own folder structure. This seems to be more trouble than its worth. This framework has a single application folder (and standard sub-folders). An "application" is now defined at the file/class level.

Structure

Once copied to a new website folder, for simplicity, there are only three files. The main phar file (coeus_fw.phar), an htaccess file, and a simple config file (config.ini). The "application" folder is the where to develop your app. Moreover, The default (blank) framework has a document reference (located at /coeus_fw.phar/framework/_docs/html/index.html).

The Core Framework

The framework will create all the necessary folders for you automagically.

The framework files.
    coeus_fw.phar - This is the main framework
    config.ini - Configuration
    .htaccess - Apache configuration

The Application Framework

Where you build your application

application/ - This is your home. Develop in here.
    css - Application style sheets
    html - Application HTML files
    images - Application images
    js - Application javascript
    models - Database schema definitions
    php - Application controller files

The Cache Folder

This is the automagically created cache folder

cache/ - The cache folder (if enabled in config.ini)
    cache.json - There should be a cache.json file to keep track of any cached files.
    cached.css - The cached CSS file
    cached.js - The cached JavaScript file

Getting Started

YOU DO NOT NEED TO CREATE ANY FOLDERS!

Copying the framework

By default, the framework will create all the folders you need. If you choose SCRIPT_CACHE in the config file, it will also create a cache folder.

  1. Check out the files in the git **/build/** folder. These file are:
    • coeus_fw.phar
    • config.ini
    • .htaccess
  2. Delete any .git folders or files
  3. Clone your new project into your working folder
  4. Copy the framework files into the root of the working folder
  5. Configure via the config.ini file

Configuration

The framework configuration is in the config.ini file. The structure of the configuration file is as follows.

General Settings
    ERROR_REPORTING - (True or false) This sets wether a stack trace is displayed on errors.
    LIGHTTABLE - (True or false) This enables the debugging connector for LightTable.
    SCRIPT_CACHE - (True or false) Turns the script cache engine on or off.
    DEFAULT_APP - This is the default class to call when none is specified

Database Settings
    DB_HOST - MongoDB hostname
    DB_PORT - Database port
    DB_NAME - The database name

Template Settings
    TEMPLATE_EXTENSION - The file extension of the templates
    TEMPLATE_DEFAULT_MASTER - THe name of the master html template file

General Settings

ERROR_REPORTING will turn on or off displaying a stack trace on errors thrown. The stack shows the class names, file names and line numbers of the errors. The main error message is displayed reguardless of this setting. While in development, it may be handy to turn on.

LIGHTTABLE wil add a JavaScript file to the HEAD tag of the HTML. This file connects to the LightTable debugger and live editing mode.

SCRIPT_CACHE - turns the script caching engine on or off. While on (true), the framework will compile a single css and a single js file to reduce server requests.

DEFAULT_APP Will set the the class used if none is specified in the URL. In your class __construct, you can handle what method is called by default.

Database Settings

DB_HOST specifies the database host can be either a FQDN or an IP address. Make sure MongoDB is running on the host.

DB_PORT is the port on which the MongoDB server is running. You should not have to change this as its set to the defaul port.

DB_NAME is the name of the MongoDB database itself. Note that one server can have many databases served.

Template Settings

TEMPLATE_EXTENSION defines the file extension the template class uses for html file. By default, temapltes are .html.

TEMPLATE_DEFAULT_MASTER is the name of the file that serves as the main template. This is what provides the html, head, body, etc. tags.

The Application

Building Your Application

The first step is to create a php file in the **application** folder.

The file name and class name must be identical.

Here's an example file called "example.php"

<?php
namespace application\php {
use framework\core\template as template;
class example {
function __construct($default = false){
if($default) $this->home();
}
function home(){
$tpl = new template;
$tpl->add("main", "home.html");
}
}
}

Note the namespaces. We are using the core template in this example. We are shortening the name by using the use directive. This allows you to call template without having to type the entire namescpace each time.

In this example, there is a default function calling home() if nothing has been specified.

The next step is to create the HTML content. In the application/html folder, create a master.html file. Here's an example.

<!doctype html>
<html>
<head>
<title>My App</title>
</head>
<body>
<template name="main"/>
</body>
</html>

Note the template tag. This is where your sub-template will go.

Lastly, create a sub-template. In this example, we'll call it home.html.

<div>
Hello world!
</div>

See The Magic

Point your browser to http://your-site/example/home and you will see a hello world message from your sub-template.

Here is what the output should look like:

<!DOCTYPE html>
<html>
<head>
<title>My App</title>
<link rel="stylesheet" type="text/css" href="/framework/cache/cached.css">
<script type="text/javascript" src="/framework/cache/cached.js"></script>
</head>
<body>
<div>
Hello world!
</div>
<script type="text/javascript" src="/js/post-00-operations.js"></script>
</body>
</html>

Note the automagically added a cached Javascript and CSS files.

Script Caching

This framework cahes both CSS and JavaScript into single files (cached.css and cache.js). This can be turned off by setting the SCRIPT_CACHE to false. The caching engine will only cache a file if certain conditions are met.

  1. The file must be a relative path (i.e. not "http://...")
  2. The tag must be either a link or srcipt in the HEAD of the HTML
  3. Each tag must have three components:
    1. Tag itself (i.e. link or script)
    2. The file location (i.e. src or href)
    3. the file type (i.e. text/css or text/javascript)

JavaScript

There are three ways to add javascript to your application.

  1. Add a script in the HEAD tag of the HTML
    • This file is for application-wide functionality.
    • Every page will include this script.
  2. Add javascript in your sub-template file.
    • This will localize your javascript to the specific page viewd.
  3. Use the post-00-operations.js file.
    • This file is for application-wide functionality.
    • Every page will include this script.

Adding Data Manipulation

Creating A Data Model

To create a database collection (table), you must create a child class within the **application** folder. Here is an example model object. You should also notice the required "_id" field.

You must extend the framework core model.

<?php
namespace application\models { // <--- Requred
class companies extends \framework\core\model { // <--- Requred
private $_id; // <--- Requred
private $name;
private $www;
private $logo;
private $address_street;
private $address_city;
private $address_state;
private $address_zip;
}
}

Using Your Data Model

In your PHP code, you can utilize database calls. Typically, you would simply use PHP to output JSON to the HTML/JS for Ajax queries. Complete explinations of these methods are found on the Framework Documentation.

Put this in between the namespace and class definitions.

use application\models\(your-model-name) as (your-model-name);

Within your function:

function getAll(){
$myVar = new your-model-name;
print( $myVar->find()->getAll(true) );
}

Available database methods are:

  1. find - Find a document based on search filters
  2. addNew - Adds a new (blank) document
  3. save - Saves the current document as-is
  4. remove - Deletes the current document
  5. getAll - Returns all documents in the cursor
    • (There is an option to return it as JSON)

See the model function documentation, go here: model_functions Class Reference

AJAX

Adding data to the HTML is a simple process. Create a container defined as a dataContainer and the data-call should point to your PHP function. Then you can bind a field name using a data-bind attribute.

<div class="dataContainer" data-call="/example/getAll">
<span data-bind="<field_name>"></span>
</div>

A more detailed use of the JQuery data templates used can be found at https://leonidas.github.io/transparency/

Using The Coupon Wallet API

To use the CW API, a library has been included in the **framework** folder called cw_api. This library makes a curl request wiith an API key to the api server. It is suggested to write a single function to handle any api method needed.

Here is an example function:

function cw($method){
print( \framework\lib\cw_api::get($method, (object) $_REQUEST) );
}

Using this function in your php, you can point your browser to /(your-class-name)/cw/(api-method-name)/?($_get data here). This function will output the JSON data from the Coupon Wallet API call. To call this from HTML, use an AJAX dataContainer (see above).

There must be a trailing slash at the end of the url method name, before the _GET string

More Documentation

The are the external libraries used in this framework and example. Here are the links to each used: