$table_meta = $this->examples_model->table_info();
echo $table_meta['id']['type']; // int
echo $table_meta['id']['primary_key']; // 1 (TRUE)
echo $table_meta['email']['type']; // varchar
echo $table_meta['first_name']['type']; // varchar
echo $table_meta['description']['type']; // text
echo $table_meta['active']['type']; // enum
print_r($table_meta['active']['options']); // array('yes', 'no')
</pre>
<h2>$this->examples_model->form_fields(<var>[values]</var>, <var>[related]</var>)</h2>
<p>Somewhat similar to the table_info method with difference being that the returned array has information for creating a form.
The related parameter is used to conveniently map other model information with this form to create a many to many multi-select form element.
This method is usally used with the <a href="<?=user_guide_url('libraries/form_builder')?>">Form_builder</a> class.
</p>
<pre class="brush: php">
$form_info = $this->examples_model->form_fields();
echo $form_fields['id']['type']; // hidden
echo $table_meta['email']['type']; // text
echo $table_meta['email']['required']; // 1 (TRUE)
echo $table_meta['first_name']['type']; // text
echo $table_meta['description']['type']; // textfield
echo $table_meta['active']['type']; // select or enum
echo $table_meta['date_added']['type']; // datetime (a special field type in the form_builder class)
</pre>
<h1>Inline Editing</h1>
<p>Inline editing allows users to quickly modify module information within the context of the website. This is accomplished by using
either the <a href="<?php
echo user_guide_url('helpers/fuel_helper');
?>
">fuel_edit</a> or the <a href="<?php
echo user_guide_url('helpers/fuel_helper');
?>
">fuel_var</a> function with the latter
specific to pages that are completely editable (and not just module data).
</p>
<p>For inline editing to work, you must be logged into FUEL and have the proper permissions to edit the page or module information.
A <span style="background: transparent url(<?php
echo img_path('ico_pencil.png', FUEL_FOLDER);
?>
) no-repeat; display: inline-block; height: 16px; width: 16px;"></span> pencil icon
will appear over editable areas when the editing for the page is toggled on. Clicking on the icon will overlay a form over your page to edit the values in context.</p>
<h2>Page Inline Editing</h2>
<p>Page inline editing allows you to edit the values of variables used in the page.
A FUEL logo will be displayed in the upper right area of the page that can slide out and provide you
the ability to toggle inline editing, publish status and caching. Clicking the inline editing pencil will toggle inline editing on.</p>
<img src="<?php
echo img_path('examples/page_inline_editing.jpg', 'user_guide');
?>
" class="screen" />
<h2>Module Inline Editing</h2>
<p>For those pages that may not be editible, you can still allow for module data to be edited (e.g. news items).
The top right area <strong>will not</strong> have the controls for page publish status, caching or layouts and will look like the following:</p>
echo user_guide_url('helpers/fuel_helper');
?>
">fuel_model and fuel_block</a> helper functions that could be used instead.</p>
<h3>Inline Editing</h3>
<p>The very last thing we will do is add inline editing to our view. To do this we use the <a href="helpers/fuel_helper">fuel_edit</a> function. We'll
place that function right inside the <h2> tag. </p>
<pre class="brush: php">
...
<h2><?=fuel_edit($article->id, 'Edit: '.$article->name, 'articles')?><?=$article->title?></h2>
...
</pre>
<p>Additionally, you may add items in the context of a page. To do that, you pass <dfn>create</dfn> as the first parameter.</p>
<h2><?=fuel_edit('create', 'Create', 'articles')?><?=$article->title?></h2>
<p class="important"><a href="<?php
echo user_guide_url('general/inline-editing');
?>
">Click here for more on inline editing</a></p>
<p><strong>That's it!</strong></p>
<?php
/* ?>
<h2>Now What?</h2>
<p>If you are wanting to create more advanced modules, <a href="<?=user_guide_url('modules/advanced')?>">click here</a>.</p>
<p><a href="<?=site_url(USER_GUIDE_FOLDER.'/examples/fuel_modules_example.zip')?>">Click here to download the files to the example.</a></p>
<?php */
<p>Add the following module to the <dfn>application/config/MY_fuel_modules.php</dfn> file: </p>
<pre class="brush: php">
$config['modules']['news'] = array(
'preview_path' => 'news/{slug}'
);
</pre>
<h3 id="view_file">View File</h3>
<p>You could use a controller to do the url segment logic but for this tutorial, we will just use a single view.
The following view file uses the <a href="<?php
echo user_guide_url('helpers/fuel_helper');
?>
">fuel_model</a> and
<a href="<?php
echo user_guide_url('libraries/my_model/data_record_class_functions');
?>
">custom record objects</a>.</p>
<pre class="brush: php">
<?php
$slug = uri_segment(2);
if (!empty($slug))
{
$news_item = fuel_model('news', array('find' => 'one', 'where' => array('slug' => $slug)));
if (empty($news_item)) show_404();
}
else
{
$news = fuel_model('news');
}
?>
</p>
<h2>fuel_edit(<var>id</var>, <var>[label]</var>, <var>[module]</var>, <var>[xOffset]</var>, <var>[yOffset]</var>)</h2>
<p>Sets a variable marker (pencil icon) in a page which can be used for inline editing.
The <dfn>id</dfn> parameter is the unique id that will be used to query the module. You can also pass an id value
and a field like so <dfn>id|field</dfn>. This will display only a certain field instead of the entire module form.
The <dfn>label</dfn> parameter specifies the label to display next to the pencil icon.
The <dfn>xOffset</dfn> and <dfn>yOffset</dfn> are pixel values to offset the pencil icon.
</p>
<h2>fuel_cache_id(<var>[location]</var>)</h2>
<p>Creates the cache ID for the fuel page based on the URI.
If no <dfn>location</dfn> value is passed, it will default to the current <a href="<?php
echo user_guide_url('my_url_helper');
?>
">uri_path</a>.
</p>
<h2>fuel_url(<var>[uri]</var>)</h2>
<p>Creates the admin URL for FUEL (e.g. http://localhost/MY_PROJECT/fuel/admin).</p>
<h2>fuel_uri(<var>[uri]</var>)</h2>
<p>Returns the FUEL admin URI path.</p>
<h2>fuel_uri_segment(<var>[seg_index]</var>, <var>[rerouted]</var>)</h2>
<p>Returns the uri segment based on the FUEL admin path.</p>
">allowed by default</a>, however you can use FUEL's
<a href="<?php
echo user_guide_url('parsing');
?>
">parsing syntax</a>. Page variables can be <a href="<?php
echo user_guide_url('general/inline-editing');
?>
">edited inline</a>
if their layout uses the <a href="<?php
echo user_guide_url('helpers/fuel_helper');
?>
">fuel_var</a> function to set the variables locations in the layout.
</p>
<img src="<?php
echo img_path('examples/screen_page_edit.jpg', 'user_guide');
?>
" class="screen" />
<h2>Importing Existing Views</h2>
<p>If you are using <a href="<?php
echo user_guide_url('general/opt-in-controller');
?>
">Opt-in Controllers</a>,
a view file that matches the URI location will trigger a prompt to import that view to edit if the modified date is after the pages last modified date.
This is a convenient way to make edits outside of the admin interface and import them.</p>
<img src="<?php
echo img_path('examples/screen_page_import.jpg', 'user_guide');
?>
" class="screen" />
?>
">Simple Modules</a></li>
<li><a href="<?php
echo user_guide_url('modules/tutorial');
?>
">Creating Simple Modules Tutorial</a></li>
<li><a href="<?php
echo user_guide_url('modules/advanced');
?>
">Advanced Modules</a></li>
<li><a href="<?php
echo user_guide_url('modules/module_forms');
?>
">Module Forms</a></li>
<li><a href="<?php
echo user_guide_url('modules/hooks');
?>
">Module Hooks</a></li>
</ul>
<h2>Installation</h2>
<p>One of the bigger changes in FUEL v1.0 was the removal of all the extra bundled advanced modules. The reason was to keep the initial FUEL install
smaller, as well as provide separate GIT repository versioning and issue tracking for each.
A list of some available modules can currently be found at <a href="https://github.com/daylightstudio" target="_blank">https://github.com/daylightstudio</a>.
Because of this change, it was deemed necessary to make the installation and updating process of advanced modules a little easier going forward. </p>
<h3>Using GIT Submodules</h3>
<p>We like to lean on GIT as much as possible for the updating of advanced modules and so we've added a couple command line tools to make this a little easier.
The first is to use GIT to add a <a href="http://git-scm.com/book/en/Git-Tools-Submodules" target="_blank">submodule</a> to your installation in your <span class="file">fuel/modules/{module}</span> folder.
// !!! IMPORTANT ... NOW ASSIGN THIS TO THE MAIN "layouts"
$config['layouts']['main'] = $main_layout;
</pre>
<p class="important"><strong>What is all this other stuff in the "Sections area"?</strong> We added this to the example just to show how complicated you can get with the layouts. The above is using
several new features including the addition of the class "tabs" which can be applied to a "type" of "fieldset" and creates tabs for your forms automatically. We are also
displaying the new field type of "template", which gives you the power to easilty create complicated repeatable forms that you can reorder and nest inside other forms.
For more details visit the <a href="#">Form_builder</a> page.</p>
<h2 id="layouts_custom_classes">Custom Layout Classes</h2>
<p>Occasionally, you may need a layout that does some additional variable processing before being applied to the page. To accomplish this, you can create your own
Layout class by extending the <a href="<?php
echo user_guide_url('libraries/fuel_layouts#fuel_layout');
?>
">Fuel_layout</a> class and modifying the <dfn>pre_process</dfn> and/or <dfn>post_process</dfn> method hooks. The <dfn>pre_process</dfn>
method gets passed the array of variables used to generate the page (e.g. formatting of dates).
The <dfn>post_process</dfn> method gets passed the final rendered output in case you want to do any post rendering of the final output (e.g. appending tracking scripts).
You can tell FUEL where to look for the class by specifying <dfn>file</dfn>, <dfn>class</dfn>, <dfn>filepath</dfn> and <dfn>filename</dfn> parameters as displayed below:
</p>
<pre class="brush:php">
$config['layouts']['main'] = array(
'class' => 'Main_layout',
'filepath' => 'libraries',
'filename' => 'Main_layout.php',
'module' => 'app',
'fields' => array(
'Header' => array('type' => 'fieldset', 'label' => 'Header', 'class' => 'tab'),
This line will add the menu item in the admin.
</li>
<li>In the constants folder its a good idea to create the following constants (although not required)
<ul>
<li><strong>{MODULE_NAME}_VERSION</strong> - the version number of the module</li>
<li><strong>{MODULE_NAME}_FOLDER</strong> - the folder name of the module</li>
<li><strong>{MODULE_NAME}_PATH</strong> - the full directory path to the module folder</li>
</ul>
</li>
<li>In the routes file, add the fuel routes you want to use. For example, this <strong>user_guide</strong> module has the following routes:
<ul>
<li>$route[FUEL_FOLDER.'/tools/user_guide'] = 'user_guide';</li>
<li>$route[FUEL_FOLDER.'/tools/user_guide/:any'] = 'user_guide/$1';</li>
</ul>
</li>
</ul>
</li>
<li>Create your controller files.
<ul>
<li><strong>Admin Controllers</strong> - Pages that need to be displayed in the admin interface should inherit from the <dfn>fuel/libraries/Fuel_base_controller.php</dfn> and can use the <dfn>_validate_user()</dfn>, protected controller method.</li>
<li><strong>Dashboard Controller</strong> - If you add a controller with the name of <dfn>Dashboard</dfn>, then it can get pulled in to the FUEL admin (if the module is in the fuel $config['dashboards'] configuration)</li>
</ul>
</li>
<li>Create your assets folder and add any specific styles you want to use for that module's admin interface in a <dfn>css/{module_name}.css</dfn> file including your menu item icons.</li>
<li>If you have the <a href="<?php
echo user_guide_url('modules/tester');
?>
">Tester</a> module, you can add your tests to a <dfn>tests</dfn> folder.</li>
<li>If you have this <dfn>user_guide</dfn> module installed, you can add documentation to the <dfn>views/_docs/</dfn> folder. There needs to be at least an <dfn>index.php</dfn> file before it will appear in the <dfn>user_guide</dfn> module.</li>
</ol>
<h3>Common Controller Methods</h3>
<p>There are two main jQX controller methods that you may want to override in your controller:</p>
<ul>
<li><strong>items:</strong> the jQX controller method used for the list view of the module</li>
<li><strong>add_edit:</strong> the jQX controller method used for adding/editing module data (the form view)</li>
</ul>
<p class="important">It's important to call use <dfn>this.super()</dfn> to call the parent method if overwriting.</p>
<h3>jQX Configuration Parameters</h3>
<p>The following jqx config parameters are available for you to use in your jQX controller:</p>
<ul>
<li><strong>jqx.config.basePath:</strong> The equivalent value to the <a href="http://codeigniter.com/user_guide/helpers/url_helper.html" target="_blank">site_url()</a> CI function </li>
<li><strong>jqx.config.jsPath:</strong> The path to the fuel modoules javascript folder which is <span class="file">/fuel/modules/fuel/assets/js/</span></li>
<li><strong>jqx.config.imgPath:</strong> The path to the fuel modoules images folder which is <span class="file">/fuel/modules/fuel/assets/images/</span></li>
<li><strong>jqx.config.uriPath:</strong> The equivalent to the <a href="<?php
echo user_guide_url('helpers/my_url_helper');
?>
">uri_path()</a> function</li>
<li><strong>jqx.config.assetsImgPath:</strong> The path the sites images (e.g. <span class="file">/assets/images/</span>)</li>
<li><strong>jqx.config.assetsPath:</strong> The path the sites images (e.g. <span class="file">/assets/</span>)</li>
<li><strong>jqx.config.assetsCssPath:</strong> The path the sites images (e.g. <span class="file">/assets/css/</span>)</li>
<li><strong>jqx.config.controllerName:</strong> The global name of the controller object which can be used by other scripts after the page is loaded. The default is "fuel"</li>
<li><strong>jqx.config.jqxPath:</strong> The path to the jQX library which is <span class="file">/fuel/modules/fuel/assets/js/jqx</span></li>
<li><strong>jqx.config.controllerPath:</strong> The path to the controller</li>
<li><strong>jqx.config.pluginPath: The path to the jQuery plugins</strong></li>
<li><strong>jqx.config.fuelPath:</strong> The path to the FUEL CMS which by default is <span class="file">fuel/</span></li>
<li><strong>jqx.config.modulePath:</strong> The path to the module which is <span class="file">fuel/{module}</span></li>
<li><strong>jqx.config.cookieDefaultPath:</strong> The server folder path used when assigning cookies</li>
<li><strong>jqx.config.keyboardShortcuts:</strong> The keyboard shortcuts to be used in the CMS</li>
<li><strong>jqx.config.warnIfModified:</strong> Determines whether to warn upon leaving a page that has unsaved field content</li>
<li><strong>jqx.config.cacheString:</strong> A string value that represents the assets <dfn>last_updated</dfn> configuration value and can be used to caching or breaking a cache</li>
/**
* Returns an array with the keys as links and the values as the name of the file
*
* @access public
* @param stirng The name of the folder relative to the MODULES_PATH
* @param string Module folder name (optional)
* @param array An array of files to exclude from the list (optional)
* @return array
*/
function folder_files($folder, $module = NULL, $exclude = array())
{
$this->CI->load->helper('file');
$this->CI->load->helper('directory');
$folder_arr = explode('/', $folder);
if (isset($folder_arr[1])) {
$module = $folder_arr[0];
$folder = $folder_arr[1];
}
if (empty($module)) {
$module = $this->page_segment(2);
}
$module_path = MODULES_PATH . $module . '/';
// force exclude to an array
$exclude = (array) $exclude;
// add PHP extension if it doesn't exist'
foreach ($exclude as $key => $val) {
if (!preg_match('#.+\\.php$#', $val)) {
$exclude[$key] = $val . EXT;
}
}
$exclude[] = 'index.html';
$files = directory_to_array($module_path . $folder, FALSE, $exclude, FALSE, TRUE);
$return = array();
if (is_array($files)) {
foreach ($files as $file) {
if ($module != FUEL_FOLDER) {
$url = user_guide_url('modules/' . $module . '/' . strtolower($file));
} else {
$url = user_guide_url(strtolower($file));
}
$return[$url] = humanize($file);
}
}
return $return;
}
?>
">view the tutorial for more information</a>).
</p>
<ul>
<li>list_items()</li>
<li>tree()</li>
<li>form()</li>
</ul>
<p>Additionally, there are <a href="<?php
echo user_guide_url('libraries/my_model#hooks');
?>
">several hooks</a> you may want to use that allow you to insert functionality during the saving and deleting process of a modules record.</p>
<h2>The Views</h2>
<p>Simple modules are made up of several views:</p>
<ul>
<li><a href="<?php
echo user_guide_url('general/interface#list_view');
?>
"><strong>List view</strong></a> - where you can filter and select from a list and edit, delete or preview.</li>
<li><a href="<?php
echo user_guide_url('general/interface#edit_view');
?>
"><strong>Form view</strong></a> - the form view that allows you to edit or input new records for the module</li>
<li><strong>Tree view (optional)</strong> - provides a tree like hierarchical structure. Requires a tree method on the module's model that follows the hierarchical <dfn>Menu</dfn> structure</li>
<li><strong>Preview view (optional)</strong> - the URO to the website to preview the module</li>
</ul>
<li>{pdf_path('my_pdf.pdf')} - Maps to the <a href="<?=user_guide_url('helpers/asset_helper')?>">pdf_path()</a> function. The <dfn>.pdf</dfn> extension is optional.</li>
<li>{safe_mailto('*****@*****.**', 'text')} - Maps to the <a href="http://codeigniter.com/user_guide/helpers/url_helper.html" target="_blank">safe_mailto()</a> function.</li>
<li>{redirect('my_redirect_page')} - Maps to the <a href="http://codeigniter.com/user_guide/helpers/url_helper.html" target="_blank">redirect()</a> function.</li>
<li>{show_404} - Maps to the <a href="http://codeigniter.com/user_guide/general/errors.html" target="_blank">show_404()</a> function.</li>
</ul>
<h2>Namespaced Functions</h2>
<p>The following are namespaced functions that can be used in your application and will be translated by the templating system.</p>
<ul>
<li>{uri_segment(1, true/false)} - Maps to the <a href="<?=user_guide_url('helpers/fuel_helper')?>">uri_segment(n)</a> function.</li>
<li>{fuel_var} - Maps to the <a href="<?=user_guide_url('helpers/fuel_helper')?>">fuel_var()</a> function.</li>
<li>{fuel_model(model, array(key="val"...)} - Maps to the <a href="<?=user_guide_url('helpers/fuel_helper')?>">fuel_modules()</a> function.</li>
<li>{fuel_block(array(key="val"...))} - Maps to the <a href="<?=user_guide_url('helpers/fuel_helper')?>">fuel_block()</a> function.</li>
<li>{fuel_nav(array(key="val"...))} - Maps to the <a href="<?=user_guide_url('helpers/fuel_helper')?>">fuel_nav()</a> function.</li>
<li>{fuel_edit(id, label, module, xOffset, yOffset)} - Maps to the <a href="<?=user_guide_url('helpers/fuel_helper')?>">fuel_edit()</a> function.</li>
</ul>
<p class="important">Note that several of the functions require an associative array paramter with the <dfn>key="val"</dfn> syntax.</p>
<h2>Blocks</h2>
<p>Tag pairs allow you to loop through arrays of data. The syntax requires an opening <dfn>{my_var}</dfn> and closing <dfn>{/my_var}</dfn> tag.
For example:</p>
<pre class="brush:php">
$my_data = array();
$my_data[] = array('name' => 'Darth Vader', 'weapon' => 'light saber');
$my_data[] = array('name' => 'Han Solo', 'weapon' => 'blaster');
...
{loop $my_data}
{$name} - {$weapon}
{loop}
echo user_guide_url('helpers/my_language_helper#func_detect_lang');
?>
">detect_lang()</a> function detects any specified language settings pulling from the URI, query string and then the user's browser settings.</p>
<h2>Form_builder Class</h2>
<p>The <a href="<?php
echo user_guide_url('libraries/form_builder');
?>
">Form_builder class</a> is used throughout FUEL CMS to create the forms used to manage module data. To allow for the localized labels in the module forms, the <var>lang_prefix</var> property can be used and will look for labels in language files using the format <var>form_label_{literal}{field_name}{/literal}</var>, if not label value is supplied.</p>
<h2>Data_table Class</h2>
<p>Similar to the Form_builder class, the <a href="<?php
echo user_guide_url('libraries/data_table');
?>
">Data_table class</a> also has a <var>lang_prefix</var> property. This prefix is used for localizing the table column headers. The prefix is set in FUEL to be the same as the Form_builder's which is <var>form_label_</var>.</p>
<h2>The js_localized Module Property</h2>
<p>The <a href="<?php
echo user_guide_url('modules/simple');
?>
">js_localized</a> property can be added to your modules if you have have javascript that needs to use some localized text.
You can provide it an array of language key values and it will be added to the list of language keys that get translated into a JSON object for your javascript files to consume.
If you are using a <a href="<?php
echo user_guide_url('general/javascript#jqx');
?>
">jqx</a> type controller that extends the BaseFuelController.js,
there will be a <var>localized property</var> and a lang() method on the controller that provides access to the JSON language object.</p>
<h1>Data Record Class Function Reference</h1>
<p>The Data_record class is the custom record object for the Table Class parent model (MY_Model).
This provides a greater level of flexibility with your models by allowing you to create not only
methods on your model to retreive records from your datasource, but also the ability to create
derived attributes and lazy load other objects with each record returned.
This class is <strong>optional</strong>. If it it doesn't exist, then the Table Class parent model
will use either a standard generic class or an array depending on the return method specified.
</p>
<p class="important">Most module records in FUEL extend the <a href="<?=user_guide_url('libraries/base_module_model')?>">Base_module_record</a>
class which has some extended functionality for module records.</p>
<h2>$example_record->is_initialized()</h2>
<p>This method returns either <dfn>TRUE</dfn> or <dfn>FALSE</dfn> depending on if the record class has been properly intialized.</p>
<pre class="brush: php">
$record = $this->examples_model->create();
$record->is_initialized(); // Returns TRUE
</pre>
<h2>$example_record->set_fields(<var>fields</var>)</h2>
<p>Sets the fields of the oject ignoring those fields prefixed with an underscore.</p>
<pre class="brush: php">
$fields = array('id', 'name', 'email');
$record = $this->examples_model->set_fields($fields);
</pre>
<h2>$example_record->id()</h2>
<p>Returns the id field name.</p>
<h1>Module Forms</h1>
<p>Modules use the <a href="<?php
echo user_guide_url('libraries/form_builder');
?>
">Form_builder</a> class to create the form used to create and edit module information.
You can modify a model's <a href="<?php
echo user_guide_url('libraries/my_model');
?>
">form_fields()</a> method to customize the form.</p>
<h2>Trigger CSS Classes</h2>
<p>There are some special CSS classes that will trigger extra functionality with certain fields:</p>
<ul>
<li><strong>add_edit</strong> - the <dfn>add_edit</dfn> CSS class allows you to add and/or edit another module directly in the module's form. This class works on select fields.</li>
<li><strong>asset_select [pdf, css, js]</strong> - the <dfn>asset_select</dfn> CSS class allows you input asset file names into your form fields.
You can specify an optional second class to specify the specific asset folder (.e.g. 'class' => 'add_edit pdf'). The default asset folder is the <dfn>images</dfn> folder. This class works with text input fields.</li>
<li><strong>multiple</strong> - the <dfn>multiple</dfn> CSS class allows you to add multiple files at a time. Works on file upload fields.</li>
</ul>
<p>Conversely, there are a couple CSS classes that are used to remove certain functionality.</p>
<ul>
<li><strong>no_editor</strong> - the <dfn>no_editor</dfn> CSS class is used when you don't want to apply a MarkitUp editor to your text field.</li>
<li><strong>no_combo</strong> - the <dfn>no_combo</dfn> CSS class is used when you don't want the combo box used and instead want a regular multi-select field.</li>
</ul>
<h1>Backup Documentation</h1>
<p>The Backup module can be used to backup the FUEL database as well as the <dfn>assets</dfn> folder.
It comes with a controller to backup the database with options to include the assets folder as well as email it as an attachment.
The Backup module can be used along with the <a href="<?php
echo user_guide_url('modules/cronjobs');
?>
">Cronjobs module</a> to do periodic backups.</p>
<h2>Backup Configuration</h2>
<ul>
<li><dfn>backup_file_prefix</dfn> - used for the name of the backup file. A value of AUTO will automatically create the name.</li>
<li><dfn>backup_assets</dfn> - determines whether to backup assets by default.</li>
<li><dfn>backup_cron_email</dfn> - the email address to send the cron job notification.</li>
<li><dfn>backup_cron_email_file</dfn> - use the email address to email notifications (seperate from the cron email).</li>
<li><dfn>db_backup_path</dfn> - used for the admin/manage/backup. Beow default looks for folder called data_backup at the same level as the system and application folder</li>
<li><dfn>db_backup_prefs</dfn> - use the email address to email notifications (seperate from the cron email). It is an array with the following options
<ul>
<li><strong>ignore</strong> - list of tables to omit from the backup.</li>
<li><strong>add_drop</strong> - whether to add DROP TABLE statements to backup file. Default is TRUE.</li>
<li><strong>add_insert</strong> - whether to add INSERT data to backup file. Default is TRUE.</li>
</ul>
</li>
</ul>
?>
">fuel_var()</a> function.</li>
<li>{fuel_model('module_name', array(key="val"...)} - Maps to the <a href="<?php
echo user_guide_url('helpers/fuel_helper#func_fuel_model');
?>
">fuel_model()</a> function. The first parameter is usually the name of your model and does not need to include the "_model" suffix (usually the same as the module name).</li>
<li>{fuel_block(array(key="val"...))} - Maps to the <a href="<?php
echo user_guide_url('helpers/fuel_helper#func_fuel_block');
?>
">fuel_block()</a> function.</li>
<li>{fuel_nav(array(key="val"...))} - Maps to the <a href="<?php
echo user_guide_url('helpers/fuel_helper#func_fuel_nav');
?>
">fuel_nav()</a> function.</li>
<li>{fuel_edit(id, label, module, xOffset, yOffset)} - Maps to the <a href="<?php
echo user_guide_url('helpers/fuel_helper#func_fuel_edit');
?>
">fuel_edit()</a> function.</li>
</ul>
<p class="important">Note that several of the functions require an associative array paramter with the <dfn>key="val"</dfn> syntax.</p>
<h3>Blocks</h3>
<p>Tag pairs allow you to loop through arrays of data. The syntax requires an opening <dfn>{my_var}</dfn> and closing <dfn>{/my_var}</dfn> tag.
For example:</p>
<pre class="brush:php">
$my_data = array();
$my_data[] = array('name' => 'Darth Vader', 'weapon' => 'light saber');
$my_data[] = array('name' => 'Han Solo', 'weapon' => 'blaster');
...
{loop $my_data}
echo user_guide_url('general/inline-editing');
?>
">inline editing</a> to our view. To do this we use the <a href="helpers/fuel_helper">fuel_edit</a> function. We'll
place that function right inside the <h1> tag in the article view and inside the <li> in the list view. </p>
<pre class="brush: php">
...
<h2><?=fuel_edit($article)?><?=$article->title?></h2>
...
</pre>
<p>Additionally, you may add items in the context of a page. To do that, you pass <dfn>create</dfn> as the first parameter.</p>
<pre class="brush: php">
<h2><?=fuel_edit('create', 'Create', 'articles')?><?=$article->title?></h2>
</pre>
<p>Next, make sure the FUEL bar located in the upper right of the page has the pencil icon toggled on. You should now see pencil icons that when clicked, will allow you to edit or add article data from within the context of the page.</p>
<p class="important"><a href="<?php
echo user_guide_url('general/inline-editing');
?>
">Click here for more on inline editing</a></p>
<br />
<p><strong>That's it!</strong></p>
<h2>Now What?</h2>
<p>If you are wanting to create more advanced modules, <a href="<?php
echo user_guide_url('modules/advanced');
?>
">click here</a>. If you have any question, <a href="http://www.getfuelcms.com/forums">meet us in the forum</a>.</p>
<h1>Data Record Class Function Reference</h1>
<p>The Data_record class is the custom record object for the Table Class parent model (MY_Model).
This provides a greater level of flexibility with your models by allowing you to create not only
methods on your model to retreive records from your datasource, but also the ability to create
derived attributes and lazy load other objects with each record returned.
This class is <strong>optional</strong>. If it it doesn't exist, then the Table Class parent model
will use either a standard generic class or an array depending on the return method specified.
</p>
<p class="important">Most module records in FUEL extend the <a href="<?php
echo user_guide_url('libraries/base_module_record');
?>
">Base_module_record</a>
class which has some extended functionality for module records.</p>
<h2>$example_record->is_initialized()</h2>
<p>This method returns either <dfn>TRUE</dfn> or <dfn>FALSE</dfn> depending on if the record class has been properly intialized.</p>
<pre class="brush: php">
$record = $this->examples_model->create();
$record->is_initialized(); // Returns TRUE
</pre>
<h2>$example_record->set_fields(<var>fields</var>)</h2>
<p>Sets the fields of the oject ignoring those fields prefixed with an underscore.</p>
<pre class="brush: php">
$fields = array('id', 'name', 'email');
$record = $this->examples_model->set_fields($fields);
</pre>
echo user_guide_url('introduction/opt-in-controllers');
?>
">opt-in controller method</a> for displaying your page. Also, adding an underscore to your
layout or block view file (in the _layouts and _blocks folder respectively), will prevent it from showing up in the selection dropdown list in the CMS.</p>
<h2>Special View Folders</h2>
<p>There are several folders that have special purpose within your views folders:</p>
<ul>
<li><strong>_admin</strong>: contains CMS admin specific views. The application folder uses this folder to hold the <dfn>_fuel_preview.php</dfn>
file which is used for previewing content from the markItUp! editor. You may need to customize to fit your preview needs</li>
<li><strong>_blocks</strong>: contains static <a href="<?php
echo user_guide_url('general/blocks');
?>
">block</a> files.</li>
<li><strong>_docs</strong>: contains <a href="<?php
echo user_guide_url('general/blocks');
?>
">user guide</a> documentation specific for a module. The application folder's _doc folder is used for site specific documentation which
can be viewed from the CMS dashboard</li>
<li><strong>_layouts</strong>: contains <a href="<?php
echo user_guide_url('general/layouts');
?>
">layout files</a></li>
<li><strong>_variables</strong>: contains <a href="<?php
echo user_guide_url('introduction/opt-in-controllers');
?>
">variables files</a></li>
<li><strong>_generate</strong>: contains template files that override the defaults used for generating things like advanced modules. This folder is not there by default and the generate
functionality will work without it.</li>
</ul>
">comments</a>,
<a href="<?php
echo user_guide_url('modules/blog/links');
?>
">links</a> and
<a href="<?php
echo user_guide_url('modules/blog/authors');
?>
">author</a>).
</p>
<p>Below are steps to creating a new theme:</p>
<ol>
<li>Duplicate the default theme and rename the folder</li>
<li>In the <a href="<?php
echo user_guide_url('modules/blog/settings');
?>
">settings</a> module, change the <dfn>Theme location</dfn> parameter to the path to your new theme folder</li>
<li>Edit the files listed below to your liking</li>
</ol>
<h2>View Files</h2>
<p>The following files can be found in your renamed theme folder for you to begin editing to your liking:</p>
<h3>Main View Files</h3>
<ul>
<li><strong>index.php</strong> - the main homepage of the blog. Displays post excerpts (similar to posts.php below)</li>
<li><strong>archives.php</strong> - displays a list of older posts grouped by month</li>
<li><strong>author.php</strong> - displays the authors bio information</li>
<li><strong>authors.php</strong> - displays a list of authors for the blog</li>
<li><strong>categories.php</strong> - displays a list of categories</li>
">Tutorial: Creating Simple Modules</a></li>
</ul>
<?php
if (!empty($modules)) {
?>
<h3>Advanced Module References</h3>
<ul>
<?php
foreach ($modules as $uri => $module) {
?>
<?php
if ($uri != 'fuel') {
?>
<li><a href="<?php
echo user_guide_url('modules/' . $uri);
?>
"><?php
echo $module;
?>
</a></li>
<?php
}
?>
<?php
}
?>
</ul>
<?php
}
?>
<p>Next, for this example, we will have FUEL automatically find the view file. To do that, we will overwrite the fuel <dfn>auto_search_views</dfn>
variable in the FUEL configuration. This is done by changing <dfn>$config['auto_search_views'] = TRUE</dfn> in the <dfn>application/config/MY_fuel.php</dfn> file.</p>
<p class="important"><kbd>$CI</kbd> is a the CodeIgniter super object that FUEL automatically gets passed to the view as the variable <kbd>$CI</kbd></p>
<p class="important"><kbd>content_formatted</kbd> is a magic method. By appending <kbd>_formatted</kbd> to the end of a string type field, it will format
the field using CI's <a href="http://codeigniter.com/user_guide/helpers/typography_helper.html" target="_blank">auto_typography</a></p>
<p class="important">Check out <a href="<?=user_guide_url('helpers/fuel_helper')?>">fuel_model and fuel_block</a> helper functions that could be used instead.</p>
<h3>Inline Editing</h3>
<p>The very last thing we will do is add inline editing to our view. To do this we use the <a href="helpers/fuel_helper">fuel_edit</a> function. We'll
place that function right inside the <h2> tag. </p>
<pre class="brush: php">
...
<h2><?=fuel_edit($article->id, 'Edit: '.$article->name, 'articles')?><?=$article->title?></h2>
...
</pre>
<p>Additionally, you may add items in the context of a page. To do that, you pass <dfn>create</dfn> as the first parameter.</p>
<h2><?=fuel_edit('create', 'Create', 'articles')?><?=$article->title?></h2>
<p class="important"><a href="<?=user_guide_url('general/inline-editing')?>">Click here for more on inline editing</a></p>
<p><strong>That's it!</strong></p>
<?php /* ?>
<h2>Now What?</h2>
<p>If you are wanting to create more advanced modules, <a href="<?=user_guide_url('modules/advanced')?>">click here</a>.</p>
<p><a href="<?=site_url(USER_GUIDE_FOLDER.'/examples/fuel_modules_example.zip')?>">Click here to download the files to the example.</a></p>
<?php */ ?>
<ul>
<li><strong>FALSE</strong> - no optimization</li>
<li><strong>TRUE</strong> - will combine files, strip whitespace, and gzip</li>
<li><strong>inline</strong> - will render the files inline</li>
<li><strong>gzip</strong> - will combine files (if multiple) and gzip without stripping whitespace</li>
<li><strong>whitespace</strong> - will combine files (if multiple) and strip out whitespace without gzipping</li>
<li><strong>combine</strong> - will combine files (if multiple) but will not strip out whitespace or gzip</li>
</ul>
<p class="important">A writable <span class="file">assets/cache</span> folder must exist for asset caching to work. Also, cached asset files must be deleted either manually or by the CMS's <dfn>Clear Cache</dfn> utility.</p>
<h2>Cache Clearing</h2>
<p>Sometimes you may make changes and not see them reflected on the site. If so, you may need to clear your site's cache.
To do that, click on the <strong>Page Cache</strong> menu item under manage and then click the <strong>Yes, clear cache</strong> button to clear your sites cache files.</p>
<p>Alternatively, you can use the command line to clear the cache:</p>
<pre class="brush:php">
php index.php fuel/manage/clear_cache
</pre>
<h2>Web Hooks</h2>
<p>The <a href="<?php
echo user_guide_url('installation/configuration');
?>
">FUEL configuration's <dfn>webhook_remote_ip</dfn> parameter</a> gives you the ability to set one or more IP addresses
that can be used to remotely call the fuel/manage/clear_cache. For example, say you use <a href="http://beanstalkapp.com" target="_blank">Beanstalk</a> to manage your GIT repositories and you would like to automatically clear the cache upon
commit. You can set this configuration value to the IP address ranges <a href="http://support.beanstalkapp.com/customer/portal/articles/68153-ip-addresses-for-access-to-beanstalk" target="_blank">provided here</a>.
Then, in Beanstalk you can set up your <a href="http://support.beanstalkapp.com/customer/portal/articles/68163-web-hooks-for-deployments" target="_blank">web deployment post hook</a>. In this case you would set it in Beanstalk to be the full URL path:</p>
<pre class="brush:php">
http://www.mysite.com/fuel/manage/clear_cache
</pre>
<h3 id="testing_redirects">Testing Redirects</h3>
<p>If you are needing to check the redirects, you can utilize <a href="<?php
echo user_guide_url('libraries/fuel_redirects');
?>
">Fuel_redirects::test method</a> and create a simple view file at <span class="file">fuel/applications/views/redirects_test.php</span> with the following:</p>
<pre class="brush:php">
<?php
echo '<pre>';
print_r($CI->fuel->redirects->test());
echo '</pre>';
?>
</pre>
<p class="important">Regular expressions and shorthand :any will not be properly translated and will return errors.</p>
<h3 id="hooks">Redirect Hooks</h3>
<ul>
<li><strong>pre_redirect</strong>: Called right before a page is redirected</li>
<li><strong>pre_404</strong>: Called right before a 404 error page is displayed. You must use the <a href="<?php
echo user_guide_url('helpers/my_url_helper#func_redirect_404');
?>
">redirect_404()</a> function instead of the show_404() function for this hook to be executed.</li>
</ul>
<h3>Custom 404 Page</h3>
<p>You can create a custom 404 page by either creating a page in the CMS or a view file named <dfn>404_error</dfn>.</p>
<p class="important">If you are having trouble with a redirect, check that you don't have any routes, or pages with assigned views at the URI path in question.
Additionally, if you have the FUEL configuration setting <dfn>$config['max_page_params']</dfn> with a value greater then 0, then you may run into issues where
the rendered page is passing a segment as a parameter instead of redirecting. In that case, you may want to change the <dfn>$config['max_page_params']</dfn>
value to a key value pair with the keys being the URI paths and the values being the number of segments to accept at those URI paths (e.g. $config['max_page_params'] = array('about/news' => 1);)
</p>
<pre class="brush:php">
'class' => array(FUEL_FOLDER => 'Fuel_custom_fields'), // key is the module, and the value is the class
'function' => 'template', // the method to execute. If no class is specified, then it will call it like a normal function
'filepath' => '', // if no file path is provided, it will look in libraries folder
'js' => array(
FUEL_FOLDER => // the module in which assets/js folder to look in
'jquery/plugins/jquery.repeatable', // the path to the javascript file relative to the assets/js folder
),
'js_function' => 'fuel.fields.template_field', // the name of the javascript function to execute upon rendering of the form
'js_exec_order' => 0, // the execution order of the javascript function
'css' => '', // the path to the css file relative to the assets/css folder
</pre>
<h2 id="representatives">Representatives</h2>
<p>Also new to the <a href="<?php
echo user_guide_url('libraries/form_builder');
?>
"> Form_builder</a> class is the concept of <dfn>representatives</dfn>.
Representatives allow you to assign a field with certain attributes (e.g. type, name, etc) to a specific field type.
For example, FUEL will automatically set a field with a name of 'pwd' or 'passwd' to be the 'password' type field.
Or, if you have a field of type 'int', 'smallint', 'mediumint', 'bigint', it will be assigned the 'number' field type. When assigning
a representative, the key is the field type to be the representative and the value is either an array or string/regular expression to match for fields to represent.</p>
<p>There are several ways to assign representatives to a field type:</p>
<p>The first is to add them to the $config['representatives'] array in the <span class="file">fuel/application/config/custom_fields.php</span>:</p>
<pre class="brush:php">
// will assign any field of type 'int', 'smallint', 'mediumint' or 'bigint' to be represented by the 'my_field' type
$config['representatives']['my_field'] = => array('int', 'smallint', 'mediumint', 'bigint');
<ul>
<li><strong>restrict_to_remote_ip</strong> - restrict FUEL to only certain IP addresses (array only value so can include multiple).</li>
<li><strong>default_pwd</strong> - default password to alert against. The default password is <dfn>admin</dfn>.</li>
<li><strong>admin_enabled</strong> - allow use of the CMS admin. The default is <dfn>FALSE</dfn>.</li>
<li><strong>num_logins_before_lock</strong> - the number of times someone can attempt to login before they are locked out for 1 minute (or whatever is set for the <dfn>seconds_to_unlock</dfn>). The default is <dfn>3</dfn>.</li>
<li><strong>seconds_to_unlock</strong> - the number of seconds to lock out a person upon reaching the max number failed login attempts. The default is <dfn>60</dfn>.</li>
<li><strong>dev_password</strong> - if you set a dev password, the site will require a password to view. Testing your site may not work if a dev password is set. Default is no password.</li>
</ul>
<h2>Module Specific Security Settings</h2>
<p>Additionally, the following module specific security settings exist:</p>
<ul>
<li><strong>sanitize_input</strong> - cleans the input before inserting or updating the data source.
A value of <dfn>TRUE</dfn>, will apply the <a href="http://ellislab.com/codeigniter/user-guide/helpers/security_helper.html" target="_blank">xss_clean</a> function.
A value of <dfn>FALSE</dfn>, will apply no sanitation functions.
You can use an array to appy more then one function to sanitize your input.
The list of functions to sanitize the input is set by the <dfn>module_sanitize_funcs</dfn> <a href="<?php
echo user_guide_url('general/configuration');
?>
">FUEL configuration</a> value under the security settings.
The default values are listed below:
<ul>
<li><strong>xss</strong> = xss_clean</li>
<li><strong>php</strong> = encode_php_tags</li>
<li><strong>template</strong> = php_to_template_syntax</li>
<li><strong>entities</strong> = entities</li>
</ul>
<li><strong>sanitize_files</strong> (was sanitize_images) - uses <a href="http://ellislab.com/codeigniter/user-guide/helpers/security_helper.html" target="_blank">xss_clean</a> function on images.</li>
</ul>
echo user_guide_url('libraries/form_builder');
?>
">Form_builder</a> and <a href="<?php
echo user_guide_url('libraries/validator');
?>
">Validator</a> classes and so code control is important</li>
<li>The integration with other classes made it crucial to be bundled up as an object that could be shared</li>
</ol>
<p class="important">Unlike CI's helper, this Form class will automatically insert an ID attribute for most of the fields. This can be overwritten with <dfn>id="[custam_value]"</dfn> passed to any of the methods below that have an <dfn>$attrs</dfn> parameter.</p>
<h2>Configuring Form Information</h2>
<p>There are several public properties you can use to configure the Form Class:</p>
<ul>
<li><strong>attrs</strong> - The form tags attributes. Default is <dfn>method="post" action=""</dfn></li>
<li><strong>validator</strong> - The <a href="<?php
echo user_guide_url('libraries/validator');
?>
">validator</a> object to be used during the validation process</li>
<li><strong>focus_highlight_cssclass</strong> - The focus css class. Default is <dfn>field_highlight</dfn></li>
<li><strong>error_highlight_cssclass</strong> - The error highlight class. Default is <dfn>error_highlight</dfn></li>
</ul>
<br />
<h1>Function Reference</h1>
<h2>$this->form->open(<var>[attrs]</var>, <var>[validator]</var>)</h2>
<p>Will create a form open tag.
The <dfn>$attrs</dfn> parameter will be the attributes of the form (can be an array also).
The <dfn>$validator</dfn> parameter is a Validator Class object (optional).
</p>
<h1>Forms Module Documentation</h1>
<p>This Forms module documentation is for version <?php
echo FORMS_VERSION;
?>
.</p>
<p>The Forms module provides a flexible way to create simple to complex forms. This is what you can do with it:</p>
<ul>
<li>Create forms in the CMS, as static views or a combination of the two</li>
<li>Use one of the additional <a href="<?php
echo user_guide_url('general/forms');
?>
">custom field types</a> to combat SPAM including a <a href="http://www.dexmedia.com/blog/honeypot-technique/" target="_blank">honeypot</a>, a simple equation, <a href="https://www.google.com/recaptcha/intro/index.html" target="_blank">reCAPTCHA</a>, <a href="http://www.stopforumspam" target="_blank">stopforumspam</a> or <a href="http://akismet.com/" target="blank">Akismet</a></li>
<li>Email specified recipients upon form submission</li>
<li>Save entries into the database which can be exported as a CSV file</li>
<li>Validate required and common field types like email as well as setup your own custom validation</li>
<li>Submit and validate forms via javascript as well as server side</li>
<li>Specify a return URL</li>
<li>Automatically will attach uploaded files to the recipient email</li>
<li>Hook into various parts of the processing of the email that gets sent</li>
</ul>
<h2>Hooks</h2>
<p>There are a number of hooks you can use to add additional processing functionality during the form submission process. You can pass it a callable function or an array with the first index being the object and the second being the method to execute on the object.
Additionally, you can specify an array of <a href="http://ellislab.com/codeigniter/user-guide/general/hooks.html" target="_blank">CodeIgniter hook parameters</a>.
The hooks must be specified in the config file to be run upon processing and not on the object during rendering unless the form is submitting to the same page in which it is rendered.
A hook gets passed 2 parameters—the first is the form object instance, the second is the $_POST parameters as a convenience.
The following hooks are:
</p>
<ul>
