MCP Directory Overview 

* Directories are NOT version controlled and must be created by developer for now.

----------------------------------------------------------------------------------------
* mcp_cache (read/write permissions)
  - images

Directory contains cache resources. At this point in time image requests are the only items being stored to this directory.

----------------------------------------------------------------------------------------
* mcp_config
  - Main.xml

Directory contains a single file Main.xml. This XML file will host each individual sites database connection credentials and domain name.

Main.xml example:

NOTE: The site attribute makes it possible to map the domain or multiple domains to a site. Site 0 is the default
site when no site can be determined or no site exists. This will be the only required site by default so a database
connection can be established for a new install.

Adapter: database adapter
- MySQL, MySQLi and PDO adapterr are compatible with each other. The only thing to note is that due
to the nature of replicating  variable binding for the MySQL adapter using the feature will incur 
a performance cost. For this reason most of the core program has been written using standard
escaping, rather variable binding. Though, standard escaping and binding are supported, it will just
changes some of the workflow around.

Salt: sensitive data SALT
- This value may be used to encrypt sensitive data. Within any MCP resource such as; module, DAO, template
the value may be retreived via: $this->_objMCP->getSalt();.

<?xml version="1.0"?>
<main>
	<site id="0">
		<domain>www.xxxx.com</domain>
		<db>
			<pass>pass</pass>
			<user>user</user>
			<host>localhost</host>
			<db>dbname</db>
			<adapter>App.Resource.DB.PDO</adapter>
		</db>
		<salt>d784rghjkd5890dfg12234cbcndpoq0dgdga</salt>
	</site>
	<site id="1">
		<domain>www.yyy.com</domain>
		<domain>www.yyyxxx.com</domain>
		<domain>www.yyybbb.com</domain>
		<db>
			<pass>pass</pass>
			<user>user</user>
			<host>localhost</host>
			<db>dbname</db>
			<adapter>App.Resource.DB.MySQL</adapter>
		</db>
		<salt>qgvrghjkd5890dfg1bjla78ndpoq0yuAp</salt>
	</site>
</main>

----------------------------------------------------------------------------------------
mcp_root
  - App (version controlled)
  - Component (version controlled)
  - * PlatForm (needs to be created)
  - * Site (needs to be created)

Directory contains all vital framework resources such as; class, template and configuration files.

The root directory will also contain a Site and PlatForm directory. Although these directories are not included by default they must be created. The Site directory will contain Site specific modules, templates and client-side entities such as; images, pdf files, etc.

The PlatForm directory has similar purpose to the Component directory residing inside the root. The primary difference is usage. The Component directory is meant to organize global level modules and templates. For example, the Blog component isnÕt designed for any specific site. So component directory is the perfect place for it.

On the other hand, the PlatForm directory may be used to organize components that are application focused. For example, creating a SocialNetWork PlatForm and placing all files that are specific to that application inside.

In either case the Component and PlatForm directory may be used in the same way. The only difference is really organization. 

Component - Global functionality not specific to an individual application
PlatForm - Application level hierarchy of components

----------------------------------------------------------------------------------------
www (http site root)
  - * lib (needs to be created) - hosts JavaScript libraries
    - JQuery (example)
      - pkg (pkg directory always required)
        - ... (framework files)
  - base.xml
  - css.php
  - dao.php
  - file.php
  - img.php
  - index.php
  - js.php
  - mod.php

Directory contains all public access points for back-end functionality, third-party JavaScript APIs, MCP JavaScript API and base configuration file. The base configuration file base.xml makes it possible to override the default path to primary framework directories listed above. By default the directories are placed one directory above the site root for security purposes. However, you can modify the paths within the public access base configuration file to your needs.

base.xml default:

<?xml version="1.0"?>
<base>
	<config>../mcp_config</config>
	<root>../mcp_root</root>
	<site>../mcp_site</site>
	<cache>../mcp_cache</cache>
	<pkg>.</pkg>
	<ds>/</ds>
</base>


  Public Access Entry Point Overview:

  - base.xml: Declare paths to primary framework directories
  - css.php: Serve up style sheet
  - dao.php: Access any DataAccess layer method through public API - useful for javaScript API request - under development
  - file.php: Access site download directory 
  - img.php: Serve up site or database image
  - index.php: Main entry point for navigating site
  - js.php: Serve up site JavaScript file
  - mod.php: Same as index.php but doesnÕt wrap request in master template. This is useful for making AJAX requests and dumping content to screen without worrying about having the master template dumped again.


-----------------------------------------------------------------------------------------------------
Base directory and file structure:

/

mcp_cache (read and write permissions) *
  - images
  
mcp_files (read and write permissions) *
- images
- files

mcp_config *
  - Main.xml
  
mcp_root
  - App
  - Component
  - PlatForm *
  - Site *
  
www (site root)
  - lib *
  - base.xml
  - css.php
  - dao.php
  - file.php
  - img.php
  - index.php
  - js.php
  - mod.php

------------------------------------------------------------------------------------------------------
MCP Base Database Tables

see install.sql file

All current application dependent table definitions are defined within dump file.

Outline:

Node

Inspired by Drupal a node represents a single piece of content such as; blog entry, artcile or product. Most physical
content is stored as a node within the system.

Node Type

Inspired by Drupal a node type groups nodes together to be used in a certain context such as; product, blog entry. Node types
determine the context of a node. Furthermore, node types may have additional fields added to them that propogate to all nodes
of the type. In concept the abiity to define "meta" fields by node type is similiar to Drupal Field Module.

Comment

All nodes may have comments. Comments stores the comments for a node.

User

Manages all registered users. User names and emails must be unique per site that the user
is registered. Like nodes dynamic fields may be added to users to store additional information
such as; profile or avatar image.

Taxonomy (consist of two tables at this time)

Vocabulary

All vocabularies within system - a vocabulary organizes a set of terms. For example,
Categories is a common example of a vocabulary. Vocabularies may have dynamic fields added to them
that propogate to all terms within the vocabulary.

Terms
All terms within the system. A common example of terms are the the actual category names such as;
boot, sweaters, shorts, etc.

Terms is hieriachial whereas; vocabularies are not.

Navigation (consist of two tables)

Navigation
Stores all navigation menus and settings specific to those menus such as; whether to display the title
or position of menu on page.

Navigation
The individual links associated with the menu. 

Navigation links are stored as tree whereas menus are not.

Site
All available sites.

All entities within system will be assigned to a site unless globally available. There are not
many instances of entities that are shared. The primary example at this time is the countries
Vocabulary. All sites will use the same countries vocabulary.

For the most part all data is assigned to a site. This makes it possible to easily manage
multiple sites using the same database and code base. 

Sessions (internal use only)
manages client past and present sessions. All sessions management resolves to this table. This will
make it possible to easily track hits, patterns, etc in future feature enhancements.
 
Config
Stores all site global configuration overrides. Site connfiguration variables such as; heading, banner, etc
are stored in two parts. One part is an XML and another is within this table. The definitions that exist
within the XML file (mcp_root/App/Config/Config.xml) are the global defaults. The settings within the XML
are those that a new site starts off with initally. Than when changes are made the changes are stored
in the database for the site. So the Config table contains all config settings that have been updated
from the provides XML file defaults. 

Any configuration setting saved/updated without a value will resolve back to the default
defined in the config XML file.

Data Cache
Stores cached values as serialized string or flat value. Can be useful when displaying a vocabulary
often, so that the entire vocabulary doesn't need to be rebuilt every request (buildng a full vocabulary
is a recursive query process).

Image Cache
Paths to cached versions of images. The mappings are resolved based on the image and a set of options
for the image that change the way the original is displayed such as; resizing, grayscale, etc. All of
which transformations are process intensive, so the end result is cached.

Field
Fields may be used to extend table and content types with user defined form elements/fields. For example,
a product node type could be extended with a price field. When this is done a price field will become
available when entering new nodes of type product, just as price was an actual column in the database.
Fields provide a method of creating "virtual columns" separate from the a tables actual schema yet, mixed
in as if they were part of the schema on the application end. Items that support fields are:
Users, Config, Nodes and Terms. 

Views

Displays will provide a User API to launch pages as navigation links using a variery of
information within the database. Using the API non-programmers will be able to build basic
to intermediate SQL statements, style, add pagination, permeissions and even actions using
the primary entities within the system

- Node
- Site
- User
- Vocabulary
- Term
- Node Type
- *Field

Virtual displays may be used to create a products page, navigation menu, navigation sub menu or
single node page with nested virtual displays. Displays will able to be embedded within one
another and overrided at any level of the tree.

proposed tables:

vd_arguments
define variables to make available to the display using unique names. Variables may be defined
based on POST, GET, URL Agruments, PHP snippet or static value. Once an argument is used in a filter
,sort or field it may not be delted until removed from all of its references within the query.

vd_fields
The fields to select. The query will be derived from what is being selected including automated
logic to handle necessary joins. Joins for dynamic fields is one thing that is going to come
pre-built, so there is no need to declare joins through the API, they will happen automatically
based the what needs to be shown.

vd_filters
Filters will be used to limit the result set passed on a certain set of criteria such as;
nodes that are products or terms within a certain vocabulary. 

vd_sorting
Similiar to fields one will be able to select any field and sort by it using ascending, descending
or specific priority. Additionally, any fields selected may be marked as sortable. Making a field
selection sortable will provide a up and down arrow for sorting that specific column without
defining it here. The items explicitly declared for sorting will always be added to the query where as
items makred as sortable will be controllable by the user using up and down arrows.

vd_displays
Display table will host all of a sites available dsiplays in a tree format. Each display
will be required to have a unique name amoung its siblingings. Displays may be named
the same thing unless they are siblings of one another. Displays will be siblings when
they extend an existing display slightly modifying some aspect inheriting the primary
definition.

Actions

Two primary actions exist for any given entity within the system: edit and delete. When
creating or editing a display it may be checked as editable or deletable. When that occurs the
users with permissions to delete or edit the base entity shown such as; node will be shown inputs
to carry out those tasks. Addionally, it may be possible to edit the data directly within the view
using AJAX, though a little far fetched at the moment but we'll see.

------------------------------------------------------------------------------------------------------

MCP Core Concepts

Throughout the evolution of the MCP a standard set-up of patterns and work flow have been developed
to ease the process of maintaining, updating and reducing replicated code. While it is not a functional
requirement to adhere to many of the patterns, it is highly advised. The primary patterns and work flows
of concern will be outlined below.

-----------------------------------------------------------------------------------------------------

* Class Instantiation

The MCP makes use of a central method that instantiates all classes. When instantiating 
classes NEVER use new. ALWAY use the below method in place of new.

$this->_objMCP->getInstance('Component.Node.Module.DAO.DAONode',array($this->_objMCP));

The first argument being the path to the class relative to the mcp_root directory.
The second argument being an array of arguments to pass to the constructor, simple. 

* Single Action Method Controllers

The MCP does not stuff a bunch of actions into a single class. Instead controllers have 
a single action; execute. Also, rather than using term controller MCP refers to its controllers 
as modules. From an MVC pov though, a module is a controller with a single action. Related modules
are grouped within the same package or directory. 

* Models

The base Model is DAO. Always extend MCPDAO when creating new DAOs. ALL business oriented code
should be placed in models. NEVER run queries witin modules or god have mercy on your 
soul - templates <shivers>. Templates and Modules may call methods on a DAO that return data
but never skip creating a DAO method running queries directly within modules or templates.

* Drawing User Interface Elements

Initailly, using straight HTML seemed to work fine in templates. However, with the emergence
of table, list and pager builders it become very clear that either HTML for form controls
would either need to be hardcoded in closures defined in a module or separated out into
an additional layer. So going with the lesser of evils a completely new, separate layer
was developed with the purpose of drawing User interface elements. What I am coining
as the User Interface Library has been written completely separatly of the MCP. It may
be pulled away from the MCP, but the MCP may not be pulled away from it (unless on were
to write there own UI library handler). 

The purpose of the UI library is to make is to provide snippets of reusable code for drawing
common HTML elements such as; headings or building of complex elements such as; forms, tables
etc. Most templates have been updated to use the UI library to result in more bug proof code
and provide a common, consistent interface to draw UI elements.

The way to draw any UI element is to provide the path relative to the elements directory and pass
in the required items as an associative array. Required items are defined in the settings() method
for any UI element. Anything with 'required' => true is an item that is required. When a required
item is not passed as expected an exception will be thrown. Similarly when an element doesn't exist, that
was required an exception will thrown.

A single method has been added to the MCP facade to allow direct interfacion with the UI library: ui().

That method is a direct gateway to UI->draw() method, wile allowing the MCP to react or possibly change
how something is drawn in the future, or even pull away the entire UI library completely using something
else, though logic would be necessary to do so, for the namespace mappings of each drawn element.

Drawing UI example:

echo $this->_objMCP->ui('Common.Field.Link',array('url'=>'#','label'=>'Hello'));

Within any template the ui method may be used directly without referencing the MCP, facade:

echo $this->ui('Common.Field.Link',array('url'=>'#','label'=>'Hello'));

Where this becomes mostly useful is inside modules, when defining table configuration with a field
mutation, for example changing a title of a node to a link or displaying the form control. Instead
of writting HTML within the closure, inside the module one should draw elements through the UI library.

More will be written on that later, but for the most part all HTML elements should be drawn through the UI
library. This will also allow future theme overriding to be added (in the works).

The UI library may be found under: /mcp_root/App/Lib/UI
Example of module usage: /mcp_root/Component/Site/Module/List/List.php (~line 72) - only other way would be HTML there