Anatomy of an extension - RelationalExtend/RelationalExtend GitHub Wiki

The fuel/extensions folder

This folder holds the code and structure for each extension. It contains the same default folders as a FuelPHP MVC component, which includes:

  • /extension_name/classes
  • /extension_name/classes/controller
  • /extension_name/classes/model
  • /extension_name/classes/view
  • /extension_name/views

However, a RelationalExtend extension has additional files.

  • /extension_name/classes/extension_name/Extension.php (Extension Lex Variables)
  • /extension_name/classes/extension_name/Info.php (Extension Info)
  • /extension_name/classes/extension_name/Plugin.php (Extension Lex Plugins)
  • /extension_name/classes/extension_name/Setup.php (Extension Setup Logic)

Extension.php

Is the extension's execution point. It is used to execute variables to place within the Lex Parser before the Lex Parser render's its contents.

Example for its use (follow this strict structure):

<?php
/**
 * Extension class for the Sample extension
 *
 * @author     Ahmed Maawy
 * @copyright  2011 - 2012 Ahmed Maawy
 */

namespace sample;

class Sample_Extension implements \IExtension {

	/**
	 * Execute the extension
	 * @return void
	 */

	public function execute_extension()
	{
		return array(“sample_var” => 21, “sample_var_2” => “Sample”);
	}
}

The example above will return the following variables to the lex parser:

  1. sample_sample_var = 21
  2. sample_sample_var_2 = “Sample”

Normally the name of the extension's folder is created as a prefix before the main variable name is passed back to the Lex Parser.

###Info.php

Follows the following sample (strict structure):

<?php
/**
 * Info class for the Sample extension
 *
 * @author     Ahmed Maawy
 * @copyright  2011 - 2012 Ahmed Maawy
 */

namespace sample;

class Sample_Info extends \ExtensionInfo implements \IInfo {

	private $install_folder;

	/**
	 * Constructor
	 */

	public function __construct()
	{
		$this->install_folder = $this->get_base_folder(__DIR__);
		parent::__construct();
	}

	/**
	 * Supply meta data
	 * 
	 * @return array
	 */

	public function info()
	{
		$this->build_extension_data("Sample", "Implements the sample module", 
		$this->install_folder, "1.0");
		return array($this->extension_data);
	}
}

The build_extension_data function structure:

protected function build_extension_data($name, $description, $install_folder, $version = "1.0")

###Plugin.php

<?php
/**
 * Plugin file for the Sample extension
 *
 * @author     Ahmed Maawy
 * @copyright  2011 - 2012 Ahmed Maawy
 */

namespace sample;

class Sample_Plugin implements \IPlugin {
	public function addfunction($name, $attributes, $content)
	{
		return intval($attributes[“num1”]) + intval($attributes[“num2”]);
	}
}

The plugin above will be run once the {{ sample:addfunction num1=”21” num2=”22” }} theme tag is hit. Whatever other subtags get hit will constitute other functions within this class.

###Setup.php

<?php
/**
 * Setup class for the Sample extension
 *
 * @author     Ahmed Maawy
 * @copyright  2011 - 2012 Ahmed Maawy
 */

namespace sample;

class Sample_Setup extends \ExtensionSetup implements \ISetup {

	const TABLE_SAMPLE = "sample";

	/**
	 * Install the extension
	 * 
	 * @return array
	 */

	public function install_extension()
	{

	  // Each table is supplied in a tables array returned to the caller of this function

		$tables = array();

	  // The table name segment of the meta data

		$meta_data[self::META_TABLE_NAME] = self::TABLE_SAMPLE;
	  
	  // The fields for the table

		$meta_data[self::META_FIELDS] = array(
			new \DBFieldMeta("Blog title", "blog_title", \DBFieldMeta::FIELD_VARCHAR, 200, \DBFieldMeta::CONTROL_SIMPLE_TEXT, ""),
			new \DBFieldMeta("Blog slug","blog_slug", \DBFieldMeta::FIELD_VARCHAR, 200, \DBFieldMeta::CONTROL_HIDDEN, ""),
		);

	  // Settings fields (to be stored in the database)

		$meta_data[self::META_SETTINGS] = array(
			new \DBFieldMeta("Default number of posts to display per page", "posts_per_page", \DBFieldMeta::FIELD_INT, 0, \DBFieldMeta::CONTROL_SIMPLE_TEXT, "20"),
		);

		$tables[] = $meta_data;

		$sample_info = new Sample_Info();

		parent::install($tables, $sample_info->info());

		return $tables;
	}

	/**
	 * Uninstall the extension
	 * 
	 * @param $extension_id
	 * @return void
	 */

	public function uninstall_extension($extension_id)
	{
		$tables = array(self::TABLE_SAMPLE);
		parent::uninstall($extension_id, $tables);
	}
}

The structure of the DBFieldMeta function:

public function __construct($field_name, $field_slug, $field_type, $field_size, $control_type, $control_values);

###Constants

Field constants

  • FIELD_INT
  • FIELD_BIGINT
  • FIELD_VARCHAR
  • FIELD_DATE
  • FIELD_DATE_TIME
  • FIELD_TIMESTAMP
  • FIELD_TEXT
  • FIELD_LIST

###Control constants

  • CONTROL_SIMPLE_TEXT
  • CONTROL_NUMERIC
  • CONTROL_CALENDAR (Not yet fully implemented on admin panel).
  • CONTROL_MULTI_TEXT
  • CONTROL_RICH_EDIT
  • CONTROL_LIST
  • CONTROL_TABULAR_LIST (Used to get fields from external database tables). You will need to supply field values that are specifically formatted to get this info from the tables. For instance: "table=blog_category|id_field=id|description_field=blog_category". Seperate each parameter and value pair with a pipe (|) character.
  • CONTROL_HIDDEN
  • CONTROL_CHECKBOX
  • CONTROL_FILE (File upload field)

###How the constants work:

The Extension System is automatically designed to render these fields according to the logic supplied in the setup table – be it on front end or in the admin panel (on a tabular view for navigation or record view).

The field constants are important when creating tables and meta data items for these tables when the table is being created during the extension setup process.