DCAF follows the Model - View - Controller methodology of separating files. DCAF allows for every step in the final page construction to be interruptable. Any page created can use as much or as little of DCAF. DCAF aims to be easy and flexible.
To continue with the demo right away, jump to the Setup section.
Document root folder
Webapp folder
Every page starts with its own main PHP file. This file contains setup information about how the page will continue through DCAF. The title, CSS, Javascript and database calls are defined here. The file then passes off to the controller.
The controller file checks for a form post first. If there is a form post, the post file runs - the name of the main file is used for the name of this file (index.php). The controller then checks if there were database calls defined in the main PHP page. If there are database calls, these are run. Finally, the controller determines if this page request was for a full page or a partial page (AJAX navigation). The 'template.php' is used for a full page and 'partial.php' is used for a partial page.
Both the 'template.php' and 'partial.php' will pull in CSS and/or Javascript files if they were defined in the main PHP page.
At the very end, the unique content of the page from the folder 'inc' is pulled in and the final page is displayed.
File: common.inc.php
This is the first file you'll want to edit. It's located in the document root folder. It sets the variables that defined the location of your files. There are 4 constants you need to set:
File: template.php
This is the template file that is used to display every page. Design this page with the standard elements across all pages.
If you would like to use Google Analytics to track page views, the 'template.php' file has a Javascript section for you to enter your analytics web property ID (UA-XXXXX-X).
File: db_conn.inc.php
If you will be using a database, you will need to edit this file. It's located in the 'webapp' folder. It sets the variables that define your database connection. The sample file provided uses mySQL, but this can be changed for another database.
File: mysql_sample.txt
If you will be using a database, this is SQL that matches the DCAF demo. It was created using mySQL. Run this SQL on your database to create the matching table and fields. The database name used in the demo is 'db', but you can change this in the 'db_conn.inc.php' file mentioned above.
<?php
// page vars
$page = new stdClass();
$page->title = "Page Title";
$page->inc = "page_name";
$page->css = array();
$page->js = array();
// page data
function pageData() {
global $page, $err;
// optional, but function must exist
// use this to pull in data (e.g. database calls)
// best practice to store to $page->data
}
include("controller.php");
?>
Styling across all pages
The 'common.css' file is already included in the 'template.php' file, so you may add on to that. Or you can add a link to a different stylesheet inside of the 'template.php' file.
<link rel="stylesheet" type="text/css" href="/common.css">
Styling only one page
In the main PHP file for the page, add the name of the CSS file to the '$page->css' array and create the CSS file in the document root folder. Do not include '.css' in the name. The actual CSS file must be created in the document root. There is no 'css' folder.
In this example, the files 'file-1.css' and 'file-2.css' would be added to the page.
$page->css = array("file-1.css", "file-2.css");
Scripting across all pages
You can add a link to a javascript file inside of the 'template.php' file.
<script type="text/javascript" src="/js/global.js"></script>
Scripting only on one page
In the main PHP file for the page, add the name of the Javascript file to the '$page->js' array and create the Javascript file in the 'js' folder of the document root folder.
In this example, the files 'file-1.js' and 'file-2.js' would be added to the page.
$page->js = array("file-1.js", "file-2.js");
Internal Page Links
This is done just as you would normally link a page in HTML, but to enable AJAX, partial page load navigation to the link, add the class 'lnk' to the tag. If you have set up Google Analytics, this link will automatically be tracked with the 'lnk' class added.
Example AJAX navigation link to 'page-2.php':
<a href="/page-2.php" class="lnk">Page 2</a>
Internal Resource Links
If you are linking to a JPG, PDF, ZIP file or other file that isn't an HTML page, you link as your normally would in HTML. However, if you have set up Google Analytics and would like to track this link, you must add the class 'trk' to the anchor tag.
Example AJAX navigation link to 'page-2.php':
<a href="/cool_photo.jpg" class="trk">See My Cool Photo</a>
External Links
If you are linking to another website, you link as your normally would in HTML. However, if you have set up Google Analytics and would like to track this link, you must add the class 'trk' to the anchor tag.
Example AJAX navigation link to 'page-2.php':
<a href="http://www.google.com" class="trk">See My Cool Photo</a>
See Linking Pages for instruction on how to add tracking to pages.
The function 'pageData()' is called for every main PHP file. Place calls to your database here. It's recommended that you place the resulting data inside the object '$page->data' as a means of standardization, though nothing in DCAF requires this. You can then reference '$page->data' inside your page's 'inc' file.
Nothing in DCAF enforces you to call your database in a specific way either, but the following approach is recommended.
Inside the 'pageData()' function of your main PHP file:
function pageData() {
global $page;
include(BASE . "sql/database.sql.php");
if (sizeof($results) != 0) {
$page->data = $results;
}
}
Create the database file inside the 'sql' folder of the 'webapp' folder. The following is the recommended format, specifically the include for the database connection and the return of the results into the variables '$results':
(see more on naming standards)
include_once(BASE . "db_conn.inc.php");
$results = array();
$sql = "SELECT field AS field
FROM my_table";
$resultSet = mysql_query($sql);
if ($resultSet && mysql_num_rows($resultSet) != 0) {
while ($row = mysql_fetch_array($resultSet, MYSQL_ASSOC)) {
$results[] = $row["field"];
}
mysql_free_result($resultSet);
}
The 'action' attribute for a form should be the same page of the form. Pages POST to themselves. Form processing is automatically detected by the controller.
On detection, a file with the same name of the page is executed in the 'post' folder of the 'webapp' folder. So if the 'action' attribute is 'post.php' in the form tag, the file 'post.php' will be included in the 'post' folder (see file flow). The 'method' attribute must be 'post' in the form tag. There's no setup needed in the main PHP file for form posting.
Similar to database usage, there's no required way to handle the form processing; however, the following is the recommended way. The $_POST variables are left unaltered from the original input as they are used in the 'value' attribute of form input in case of an error. A validator include file is part of DCAF zip and contains some common for validation methods. Finally, 2 array variables are available for displaying form success or failure messages, $_MSG and $_ERR, respectively (see more on naming standards).
Form page example:
<form method="post" action="/post.php">
<div>
<? if ($_ERR) { ?>
<ul class="err">
<? foreach ($_ERR as $desc) { ?>
<li><?=$desc?></li>
<? } ?>
</ul>
<? } ?>
<? if ($_MSG) { ?>
<ul class="msg">
<? foreach ($_MSG as $desc) { ?>
<li><?=$desc?></li>
<? } ?>
</ul>
<? } ?>
<div class="field">
<label class="email" for="field1">Type Here</label> <br/>
<input type="text" id="field1" name="field1" size="35"
value="<?=$_POST["field1"]?>">
<br/>
</div>
<div class="field">
<input type="submit">
</div>
</div>
</form>
Form processing example:
// fetch the input
$field1 = $_POST["field1"];
// __________________________________________________________
// validate the input
include_once(BASE . "validator.inc.php");
validateAlpha($field1, 10, 'Field 1', true);
// __________________________________________________________
// validation functions above add to an error array, check if that array is empty
if (sizeof($err) > 0) {
include(BASE . 'error_log.inc.php');
$_ERR = $err; // $_ERR is used for displaying form errors
unset($err);
} else {
// form passed validation
// populate the success message
$_MSG = array();
$_MSG[0] = 'Your form submitted.';
// run some code that processes the input here
// e.g. save $field1 to a database
}
Some helper form validation methods are included in the DCAF zip as an optional starter for your own validation. This is not required by DCAF and you may change or remove the 'validator.inc.php' file.
The following methods are part of the validation include:
DCAF provides error reporting of its own, outside of PHP and web server errors. This is optional and can be configured in the 'common.inc.php' file. This should be used more for debugging DCAF and not as a robust error reporting system.
// DCAF Error reporting - off is false, on is true
// Your web server must be able to write to 'error_log.txt' in the folder 'BASE'
define("ERROR_REPORTING", false);
DCAF writes to the file 'error_log.txt' inside of the 'webapp' folder. You must give your web server permission to write to this file for reporting to work.