System Structure

##Introduction

After reading this document, you should have a basic understanding of the following:

• Programming/architecture style for the system as a whole
• How the class autoloader works
• Basics of how the App system initializes the website, parses the request URL and loads the appropriate data.
• What the concepts of Apps, Modules, Views and Themes mean in the context of this system.
• What the purpose is for each of the main system folders.

Please note that this system is constantly evolving and nothing is really set in stone. Feel free to submit issues and/or pull-requests for any improvements that can be made.

If you would like to get started building new features, click here.

If you would like to create new themes, click here.

##Framework

Tokenly CMS uses its own basic PHP MVC framework using OOP, tentatively called Slick Framework. Slick is quite simple and primarily consists of base configuration, a class autoloader, a database wrapper and a collection of helper classes and libraries. Most of these files are located in the /slick directory.

####Autoloading

The autoloader allows us to call functions that may be included in other files, but not have to explicitly call something like require_once(my_file.php) every time. The autoloader can be used alongside other autoloaders (perhaps with an alternative framework or system), however it will load any classes which fit the correct pattern and have an existing file.

Classes follow a naming structure that looks like this: \App\Account\Home_Model.

The name and namespace of the class tells the autoloader where it is located. It first looks in the folder slick/, and then each word separated by a backslash corresponds to a directory folder, with the final word before the underscore being the final folder, and the word after the underscore being the name of the actual class file.

So \App\Account\Home_Model translates to the path /slick/App/Account/Home/Model.php which itself contains

<?php
namespace App\Account;
use Core;
class Home_Model extends Core\Model
{

####MVC

MVC stands for "Model, View, Controller", and is the style of choice for code architecture in Tokenly CMS. The basic idea is a separation of duties for your code, keeping the request/control, data processing and output logic distinct from one another. This helps in keeping things extendible and maintainable. You can learn more about these concepts here

Typically, most features are organized into their own folders or modules, and contain at least a Controller.php and a Model.php file, as well as sometimes a View.php or set of view files in the /slick/App/views folder (more on that later).

Models
These files are where most of your data processing and database calls should live. Things such as grabbing lists of data from the database, manipulating that data or parsing it in preparation for display/output to the user.

Any model class which interacts with the MySQL database should extend off of \Core\Model, which is our database wrapper class. Click here to learn more about database interaction.

Views
view files are where display logic and specific HTML output are stored, usually using data obtained from models.

Controllers
A controller is the file that handles the URL request, loads the models, figures out what to do with the request data and spits out a response, usually in the form of passing data to and displaying a view file or invoking a page redirect.

##App System

This is where the meat of the system really begins.

Our journey starts on www/index.php...

<?php
require_once('../conf/config.php');
include(FRAMEWORK_PATH.'/autoload.php');
session_start();
ob_start();
$app = new \App\Controller;
$app->init();
$outputSite = trim(ob_get_contents());
ob_end_clean();
echo $outputSite;

First, the configuration file is loaded which contains the base folder paths, database credentials, etc. Next, the autoloader is included in and both browsing session and output buffers started. A class called \App\Controller is loaded and initialized. Finally, the outputted result of that initialization is captured, buffer ended and final results/content displayed.

The App Controller is where most of the magic happens. There is a fair amount going on here, but basically when the $app->init() function is called, it takes the following steps:

• Parses the request URL into a series of arguments/parameters (example.com/app/module/param1/param2)
• Checks and loads data from the DB for this particular website domain
• Checks to see if system is in maintenance mode or not
• Loads system settings and user account info (if logged in)
• Compares the parameters obtained from the request URL against the list of Apps & Modules as well as the Page Index. Looks to see if the URL matches up to any possible locations (and the user has appropriate access permissions), otherwise a 404 not found (or a 403) error is displayed.
• Loads an instance of the appropriate App and passes relevant data to it, then calling its init() function.
• Takes the data results from the App and passes it into the class \App\View via calling $view->load($data). This is what outputs the final response / HTML to the end user.

Let's go over a few specifics:

####Domains

The CMS allows for multiple websites to operate under a single system installation, which is also sometimes referred to as sub-sites. In order for it to load the appropriate theme, pages, content etc., the domain name it is being accessed from must match up to an entry in the sites database table. The domain field in the sites table should look like example.com (no http://, "www." or other parameters), while the url field should be like http://example.com (the full URL, used for redirects).

####URL Structure

Most URLs in the system are in the simple format /{app_slug}/{module_slug}/param1/param2.... For example, a URL for editing a forum thread might look like /forums/post/my-first-topic/edit.

In addition to this standard structure, there is also the Page Index. This allows for completely custom URLs to be used, which can point to and load any app/module/parameter combo. For example, you could have a URL of /ltb-special-episode which loads a blog post as if you went to /blog/post/ltb-special-episode. This feature is primarily used for simple CMS Pages, but can also be useful for such things as saving old links for content imported in from a different system (e.g importing WordPress posts but keeping the links the same).

####Apps & Modules

The Tokenly CMS uses the concepts of Apps and Modules for how specific features and functionality within the system are organized. An App is basically a set or group of features, while a Module is usually a specific component or feature within that.

For instance, Forum and Blog are two individual Apps, and within them they each have their own modules such as Boards, Post and Category. All Apps are located in the folder /slick/App.

Each App typically consists of 1 Controller.php file, and then each Module consists of both a Controller.php and a Model.php. An App can also technically be by itself and have no modules.

Click here to learn about this in further detail.

####Views & Themes

The theme system is quite simple, but also very free-form and flexible. Display logic is done via free-hand PHP coding (with most relevant variables already included, passed in from whatever Module loaded).

Before the final HTML output is displayed, only 3 data variables need to be set, based on what page you are on etc.. theme, template and view. Other variables relevant to the display logic are automatically included.

The theme variable tells it what directory to use in the folder /www/themes. template tells it what main template file to load from /www/themes/my_theme/templates (always falling back to default.php if none other is found). Finally, view determines what "content view" to load into the template file's content area.

Every module has it's own default view files located in the special folder /slick/App/views, which follows the exact same directory structure found in /slick/App. Each view can be overridden as needed by creating a /www/themes/my_theme/views folder and following the same structure + file names. This means that when creating a new theme, only very minimal (if any) display logic needs to be created and you can keep focus on CSS styling and the outer template HTML. Or, you can go the full nine yards and customize every piece of display logic.

Click here to learn more about using and creating Views & Themes.

##Folder Structure Overview

Here is a brief outline of the general folder structure of the CMS:

• /conf - stores base configuration settings and DB + external API credentials
• /data - folder for storing things like database dumps/upgrades. Not necessarily required.
• /scripts - stores useful scripts - also not required.
• /www - this is where your document root should be, nothing above this should be accessible via browser.
• /slick - contains the framework and most of the system code
• /slick/App - contains the App system, holding all Apps and Modules
• /www/themes - where all theme and view files are located
• /slick/App/views - special folder (not a theme) that has all default views
• /www/files - folder for storing uploaded files (cover images, avatars etc.), should be writeable
• /www/resources - contains some additional libraries and other misc. resources for general use.