Libraries: Master: Adding New Components

To add new components you have to follow the following steps:

Naming the Component

First of all think about a key and a namespace for your component. Namespaces can be divided into further subnamespaces. Root namespaces are at this time:

• frameworks: Basic CSS and JS Libraries.
• polyfills: Components for legacy browser support.
• gui-libraries: Components displaying GUI-Widgets or animate GUI-Elements. This namespace will be further divided into logical groups like "sliders", "grids" etc.

Prepare Folders

Now you have to create three times a new subdirectory hierarchy within the folders components/views, components/assets and components/config according to your namespace hierarchy.

Place Assets

Create a new subdirectory hierarchy within the folder components/assets according to your namespace hierarchy.

Into this subfolder you are free to place assets however you want. You can create subfolders or place all into the root of this folder.

Remarks/Conventions:

• Put here only the minimum you need, and only minified versions of the library if possible.

Create Views

Create a new subdirectory hierarchy within the folder components/views according to your namespace hierarchy.

Place into this subfolder a maximum of four files including the HTML-code needed to for your component. You can use the folder components/views/_empty_template as template to copy from. The files have the following meanings and have to be named as follows:

• head_init: HTML-Code to include into the start of the head.
• head_finish: HTML-Code to include before the end of the head.
• body_init: HTML-Code to include into the start of the body.
• body_finish: HTML-Code to include before the end of the body.

You do not have to add one of these files if it has no content. Links to your assets have to be declared as follows:

<link href="components/assets/PATH_TO_COMPONENT/YOUR_OWN_SUBPATHS/YOUR_ASSET_FILENAME" rel="stylesheet">
<script src="components/assets/PATH_TO_COMPONENT/YOUR_OWN_SUBPATHS/YOUR_ASSET_FILENAME"></script>

Remarks/Conventions:

• The links to the javascript files of the component should be placed into body_finish. This should done to display the page faster to the user. Components using javascript using javascript libraries like jQuery can only be placed there, because jQuery will be loaded at the end of the body first.

Setup Configuration

Create a new subdirectory hierarchy within the folder components/config according to your namespace hierarchy.

Place into this subfolder a file named setup.php. Add into this file two configuration variables as follows:

• $config['master_components_setup']['FQN_NAME_OF_YOUR_COMPONENT']['depends']
  Set here a string or an array of strings, if your component depends other components. Otherwise set it to NULL. The strings are the names of the components your component depend on. Your component will loaded then after the components noted here and the depending components will be enabled automatically.
• $config['master_components_setup']['FQN_NAME_OF_YOUR_COMPONENT']['after']
  Set here a string or an array of strings, if your component should be loaded after other components, if they are enabled. Otherwise set it to NULL. The strings are the names of the components your component should be loaded after.

Place into this subfolder a file named config.php. Add into this file one configuration variable as follows:

• $config['master_components']['FQN_NAME_OF_YOUR_COMPONENT']['config']
  Set here an assoziative array of objects if you want to be your component customizable. Otherwise set it to NULL. You can access the values of the keys in your views created at the step before. Just reference to it like a normal variable (Example: The value of theme within the configuration-array array('theme'=>'dark') can be accessed with $theme).

The file config.php should be used by the developer to modify the configuration options. The file setup.php should not be modified if possible.

Sometimes the file setup.php have to know what options was set in the config.php. For example if a component depends only on jquery if an option is set to TRUE. In this case you could use the following pattern:

$CI =& get_instance();
$master_config=$CI->config->item('master_components');
$config['master_components_setup']['FQN_NAME_OF_YOUR_COMPONENT']['depends'] = (
	$master_config['FQN_NAME_OF_YOUR_COMPONENT']['config']['SOME_OPTION']===TRUE ? 'frameworks.jquery' : NULL
    );