Libraries: Master: Unterschied zwischen den Versionen

← Zum vorherigen Versionsunterschied Zum nächsten Versionsunterschied →

Version vom 20. Juni 2015, 16:38 Uhr

In contrast to the basic CodeIgniter framework, every output of a controller will be surrounded by a master-template. All the handling will be driven by the library "Master" (accesible via $this->master). This library will be autoloaded. This page will explain every single element of the master template and all the members and methods of this library.

HTML Structure

Basic Structure

The Basic structure looks like this:

<!DOCTYPE [CONFIGURED DOCTYPE] />
<html class="no-js" lang="[CONFIGURED LANGUAGE]" >
   <head>
   ...
   </head>
   <body>
   [LEGACY BROWSER HINT]
   ...
   </body>
</html>

The doctype and the language of the template are configurable. The default value of the doctype is <!DOCTYPE html>.

The <html> tag includes a class named no-js in order to allow you to more easily and explicitly add custom styles based on whether JavaScript is disabled (.no-js) or enabled (.js). Using this technique also helps avoid the FOUC.

Head section

The order of the elements are very important. Here will be the order and the meaning of each element within the head section explained.

1. A charset definition, which is configurable. The default value is utf-8. The charset declaration must be included completely within the first 1024 bytes of the document and should be specified as early as possible (before any content that could be controlled by an attacker, such as a <title> element) in order to avoid a potential encoding-related security issue in Internet Explorer. More informations:

<meta charset="[CONFIGURED CHARSET]" />

2. A <meta> tag for compatibility mode to force IE to use the latest rendering engine and using chromeframe if possible. This tag needs to be included before all other tags except for the <title> and the other <meta> tags. More informations:

<meta http-equiv="x-ua-compatible" content="ie=edge,chrome=1">

3. A script, which set a cookie with screen resolution and pixel density informations. This allows the framework to send images to the browser adapted to the current environment. Devices with a low resolution will be delivered with automatically downscaled imagesizes. This script have to be included as high as possible and before any other script.

<script>document.cookie='resolution='+Math.max(screen.width,screen.height)+("devicePixelRatio" in window ? ","+devicePixelRatio : ",1")+'; path=/';</script>

4. The base will be set for portable linking ressources. In CodeIgniter you always had to call the function base_url to make your application moveable into subdirectories. With this setting you hopefully do not have to use base_url anymore:

<base href="<?= base_url() ?>" />

5. Setting "viewport" for normalizing and building responsive designs. More informations:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

6. Now basic meta information will be included that can be configured:

<title>[CONFIGURED TITLE]</title>
<meta name="description" content="[CONFIGURED DESCRIPTION]">
<meta name="author" content="[CONFIGURED AUTHOR]">

7. Last but not least all the dynamic informations will be included. You can add static content appearing on all pages, add content via code and by enabling components.

Body Section

If IE 7 or older will be used to display your pages a browser upgrade prompt will be shown. This is included in the beginning of <body>.

<!--[if lt IE 8]>
<p style="margin: 0.2em 0;background: #ccc;color: #000;padding: 0.2em 0;">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> to improve your experience.</p>
<![endif]-->

How to work with the template

The basic layout of the master template looks roughly like this:

<doctype>
<html>
	<head>
		[PREDEFINED AND CONFIGURABLE META INFORMATION]
                HEAD_INIT:   [STATIC, DYNAMIC AND COMPONENTS CONTENT]
                HEAD_MAIN:   [CUSTOM AND AUTOMATICALLY LOADED STYLES AND SCRIPTS]
                HEAD_FINISH: [STATIC, DYNAMIC AND COMPONENTS CONTENT]
	</head>
	<body>
		BODY_INIT:   [STATIC, DYNAMIC AND COMPONENTS CONTENT]
		BODY_MAIN:   [YOUR CONTROLLER OUTPUT]
		BODY_FINISH: [STATIC, DYNAMIC AND COMPONENTS CONTENT]
	</body>
</html>

There are six areas where code can be injected: head_init, head_main, head_finish, body_init, body_main, body_finish

In every area except body_main you can manipulate the content via three options:

Enable/Disable components
Add static content
Add dynamic content via code

The first option will insert code into the areas head_init, head_finish, body_init and body_finish. Components are sets of codesnipets that can be enabled or disabled. Every component keep it's own configuration what code will be inserted in which area. Read more about components here: #Components_Concept

The second option will be controlled by the files within the folder codecoupler/views/master. Content defined in these files will be included in every page. It's possible to define if the content will appear before or after content of components. You can read further details abaout the static files here: #Static_Content

The third option is the most flexible. The library offers methods to insert content at runtime in every area and specify the exact position like before or after content of components or static content. Although with this option you have all the power to make everything within your code it should be used thrifty. It could break every MVC concept.

The area body_main is has a special role. Into this area will be putted the outpu of the controller itself. Therefore it's not needed to have methods to manipulate content here.

Components Concept

Components are sets of content for the <head> and/or <body> section, that can be enabled or disabled by config or by code. Components can depend on each other. Enabling one component will enable all depending components, too. Disabling a component, will disable all other depending components, if not used otherwise. Components will always be included before other components depends on it. Supplied components by codecoupler are for example "jQuery", "jQuery-UI", "yaml", "normalize.css" and many others.

You can find an overview of all components, their keys and their configuration options here: Libraries: Master: Components Overview
If you want to add your own components you should the HowTo here: Libraries: Master: Adding New Components

Enable/Disable by Configuration

Components can be enabled in application/config/master.php. Every component have it's own variables like this:

$config['master_components']['NAME_OF_COMPONENT']['enabled']
$config['master_components']['NAME_OF_COMPONENT']['config']

Setting 'enabled'-variable to TRUE, will enable the component. With 'config' you can finetune the component. Please read the chapter Libraries: Master: Components Overview for further details.

Enable/Disable and Configure Dynamicaly

Everywhere in your code you can enable and disable components or set a new configuration of them. Use the following functions to handle components:

//Enable component. Use the name of the component as $key:
$this->master->enable_component($key);

//Disable component. Use the name of the component as $key.
$this->master->disable_component($key);

//Disable all components:
$this->master->disable_all_components();

//Returns TRUE if the component is enabled, otherwise FALSE. Use the name of the component as $key:
$this->master->is_component_enabled($key);

//Set a new Configuration for the component. Use the name of the component as $key:
$this->set_component_config($key,$config);

Advanced Configuration

Normally you do not have to modify these setting. But in some situation it could be inevitable. Components can be also configured in application/config/components.php. Every component will be described in one array with the following keys:

depends: This array tells the framework on what components this one depends. Depending components will be enabled automatically.
after: This array tells the framework after of what enabled components this one should be included.

Configuration

Basic configurations can be done in application/config/master.php. The configuration option are:

master_doctype: Defines the HTML-Documenttype. Can be one of the following: xhtml11, xhtml1-strict, xhtml1-trans, xhtml1-frame, html5, html4-strict, html4-trans, and html4-frame. Values are saved in the doctypes config file (application/config/doctypes.php).
master_author: Set the author.
master_autoload_scripts: Array of scripts that should be loaded by default. Do not use the extension '.js'. The fileshave to be placed into the folder application/assets/js.
master_autoload_styles: Array of styles that should be loaded by default. Do not use the extension '.css'. The files have to be placed into the folder application/assets/css.

Furthermore you can setup the default components configuration as described above and modify some basic constants (with the configuration options starting with master_path_).

Any language specific configurations can be done in language/LANGUAGE/master_lang.php. The configuration options are:

master_charset: Set charset of the page.
master_lang: Set the attrinbute "lang" of <html>.
master_title: Set the <title> of the page.
master_description: Set the description of the page.

You can read or manipulate all configuration values dynamically from everywhere in your code by accessing the following variables:

$this->master->config->doctype
$this->master->config->charset
$this->master->config->lang
$this->master->config->title
$this->master->config->author
$this->master->config->description

Static Content

Into the following files, located in the folder application/views/master, you can add content to include into the master-template statically.

Adding Static Content

Static content at the beginning of <head>:

head_init_beforeComponents.php: Before code of components.
head_init_afterComponents.php: After code of components.

Static content at the end of <head>:

head_finish_beforeComponents.php: Before code of components.
head_finish_afterComponents.php: After code of components.

Static content at the beginning of <body>:

body_init_beforeComponents.php: Before code of components.
body_init_afterComponents.php: After code of components.

Static content at the end of <body>:

body_finish_beforeComponents.php: Before code of components.
body_finish_afterComponents.php: After code of components.

Adding Dynamic Data to Static Content

You can pass data to the static content, exactly as you pass data to a CodeIgniter-View, by way of an array or an object. Just set the following variable:

$this->master->static_view_vars

Now you can use within the static content variables that correspond to the array keys.

Further Class Methods

Enabling/Disabling

You can of course disable the templating completely. This is important for example if writing Ajax-Controllers returning only json or xml. Use the following functions:

$this->master->disable(): Disable the master-templating.
$this->master->enable(): Enable the master-templating.
$this->master->is_enabled(): Returns TRUE if master-templating is enabled.

Alternatively you can create a file named .nomaster in the directory of the controller. The master-template will be disabled for all controllers in this directory.

Add Links to Scripts and Style Sheets

To add a link to a stylesheet-file:

$this->master->add_styleheet($style);

To add a link to a javascript-file:

$this->master->add_script($script);

Do not use the extensions ".js" and ".css". They will be appended automatically!
The parameter will be prefixed by the value of the configuration variable $config['master_prefix_styles'] respectively $config['master_prefix_scripts'] in the file application/config/master.php.

Add Meta Informations

To add a <meta> tag:

$this->master->add_meta($name,$content);

Adding any Content by Code

You can use the following functions to add content to the master-template from everywhere in your code:

//Add Content into the head_main Area:
$this->master->add_content_head($content);

//Add Content into the body_main Area - always after the conroller output:
$this->master->add_content_body($content);

Advanced Content Adding

You can use the following funtion to inject code into a specific place within the structure:

$this->master->add_content($position, $content);

$postion can be one of the following values - which are self-explanatory:

MasterPosition::head_init_beforeComponents_beforeStatic
MasterPosition::head_init_beforeComponents_afterStatic
MasterPosition::head_init_afterComponents_beforeStatic
MasterPosition::head_init_afterComponents_afterStatic
    
MasterPosition::head_main
    
MasterPosition::head_finish_beforeComponents_beforeStatic
MasterPosition::head_finish_beforeComponents_afterStatic
MasterPosition::head_finish_afterComponents_beforeStatic
MasterPosition::head_finish_afterComponents_afterStatic
    
MasterPosition::body_init_beforeComponents_beforeStatic
MasterPosition::body_init_beforeComponents_afterStatic
MasterPosition::body_init_afterComponents_beforeStatic
MasterPosition::body_init_afterComponents_afterStatic
    
MasterPosition::body_main
    
MasterPosition::body_finish_beforeComponents_beforeStatic
MasterPosition::body_finish_beforeComponents_afterStatic
MasterPosition::body_finish_afterComponents_beforeStatic
MasterPosition::body_finish_afterComponents_afterStatic

Debugging Features

Depending on the variable "ENVIRONMENT" (defined in index.php in the root) the variable $this->master->_DEBUG will be set to TRUE or FALSE. In development environment it is TRUE, otherwise FALSE. You can set this variable everytime to the value you want.

If the variable $this->master->_DEBUG is TRUE, every single section of the master template output will be surrounded by html-comments. Here an example:

<!-- - - - - -body_main_controller - - - - - -->
<h1>Hello World</h1>
<!-- - - - - - - - - - - - - - - - - - - - - -->

Extended Usage

In some cases maybe you have to modify the basic structure of the master template. Or you want to define what else then a html-document. In this case you can modify the file application/views/master/main.php. Within the sourcecode of this file you can read all accessible variables.

@@ Zeile 96: / Zeile 96: @@
 	<head>
 		[PREDEFINED AND CONFIGURABLE META INFORMATION]
-                 [STATIC, DYNAMIC AND COMPONENTS CONTENT (head_init)]
+                 HEAD_INIT:   [STATIC, DYNAMIC AND COMPONENTS CONTENT]
-                 [CUSTOM AND AUTOMATICALLY LOADED STYLES AND SCRIPTS (head_main)]
+                 HEAD_MAIN:   [CUSTOM AND AUTOMATICALLY LOADED STYLES AND SCRIPTS]
-                 [STATIC, DYNAMIC AND COMPONENTS CONTENT (head_finish)]
+                 HEAD_FINISH: [STATIC, DYNAMIC AND COMPONENTS CONTENT]
 	</head>
 	<body>
-		[STATIC, DYNAMIC AND COMPONENTS CONTENT (body_init)]
+		BODY_INIT:   [STATIC, DYNAMIC AND COMPONENTS CONTENT]
-		[YOUR CONTROLLER OUTPUT (body_main)]
+		BODY_MAIN:   [YOUR CONTROLLER OUTPUT]
-		[STATIC, DYNAMIC AND COMPONENTS CONTENT (body_finish)]
+		BODY_FINISH: [STATIC, DYNAMIC AND COMPONENTS CONTENT]
 	</body>
 </html>
@@ Zeile 112: / Zeile 112: @@
 In every area except '''body_main''' you can manipulate the content via three options:
+* Enable/Disable components
 * Add static content
 * Add dynamic content via code
-* Enable/Disable components
-The first option will be controlled by the files within the folder '''codecoupler/views/master'''.
+The first option will insert code into the areas '''head_init''', '''head_finish''', '''body_init''' and '''body_finish'''. Components are sets of codesnipets that can be enabled or disabled. Every component keep it's own configuration what code will be inserted in which area. Read more about components here: [[#Components_Concept]]
+The second option will be controlled by the files within the folder '''codecoupler/views/master'''. Content defined in these files will be included in every page. It's possible to define if the content will appear before or after content of components. You can read further details abaout the static files here: [[#Static_Content]]
+The third option is the most flexible. The library offers methods to insert content at runtime in every area and specify the exact position like before or after content of components or static content. Although with this option you have all the power to make everything within your code it should be used thrifty. It could break every MVC concept.
+The area '''body_main''' is has a special role. Into this area will be putted the outpu of the controller itself. Therefore it's not needed to have methods to manipulate content here.
 == Components Concept ==

Libraries: Master: Unterschied zwischen den Versionen

Version vom 20. Juni 2015, 16:38 Uhr

Inhaltsverzeichnis

HTML Structure

Basic Structure

Head section

Body Section

How to work with the template

Components Concept

Enable/Disable by Configuration

Enable/Disable and Configure Dynamicaly

Advanced Configuration

Configuration

Static Content

Adding Static Content

Adding Dynamic Data to Static Content

Further Class Methods

Enabling/Disabling

Add Links to Scripts and Style Sheets

Add Meta Informations

Adding any Content by Code

Advanced Content Adding

Debugging Features

Extended Usage

Navigationsmenü

Libraries: Master: Unterschied zwischen den Versionen

Version vom 20. Juni 2015, 16:38 Uhr

HTML Structure

Basic Structure

Head section

Body Section

How to work with the template

Components Concept

Enable/Disable by Configuration

Enable/Disable and Configure Dynamicaly

Advanced Configuration

Configuration

Static Content

Adding Static Content

Adding Dynamic Data to Static Content

Further Class Methods

Enabling/Disabling

Add Links to Scripts and Style Sheets

Add Meta Informations

Adding any Content by Code

Advanced Content Adding

Debugging Features

Extended Usage

Navigationsmenü

Suche