Libraries: Master: Unterschied zwischen den Versionen
Tm (Diskussion | Beiträge) |
Tm (Diskussion | Beiträge) |
||
| Zeile 274: | Zeile 274: | ||
== Extended Usage == | == 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 | 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. | ||
Version vom 13. Februar 2014, 16:44 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.
The basic layout of the master template looks roughly like this:
<!DOCTYPE [CONFIGURED DOCTYPE] />
<html lang="[CONFIGURED LANGUAGE]" >
<head>
<title>[CONFIGURED TITLE]</title>
[PREDEFINED AND CONFIGURABLE META INFORMATION]
[STATIC, DYNAMIC AND COMPONENTS CONTENT (head_init)]
[CUSTOM AND AUTOMATICALLY LOADED STYLES AND SCRIPTS (head_main)]
[STATIC, DYNAMIC AND COMPONENTS CONTENT (head_finish)]
</head>
<body>
[STATIC, DYNAMIC AND COMPONENTS CONTENT (body_init)]
[YOUR CONTROLLER OUTPUT (body_main)]
[STATIC, DYNAMIC AND COMPONENTS CONTENT (body_finish)]
</body>
</html>
Default Structure
Adapted from HTML-Framework "HTML5 Boilerplate": The class of the <html> tag contains lt-ie9, lt-ie8 or lt-ie7 depending on the browser used. Here is how the <html> tag looks in detail:
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7" lang="<?= $master_lang ?>"> <![endif]-->
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8" lang="<?= $master_lang ?>"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9" lang="<?= $master_lang ?>"> <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="<?= $master_lang ?>"> <!--<![endif]-->
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 deliviered with automatically downscaled imagesizes:
<script>document.cookie='resolution='+Math.max(screen.width,screen.height)+("devicePixelRatio" in window ? ","+devicePixelRatio : ",1")+'; path=/';</script>
Setting <base> for portable linking ressources. You do not have to use <?=base_url()?> anymore:
<base href="<?= base_url() ?>" />
Basic meta information can be configured and will always be included:
<meta charset="[CONFIGURED CHARSET]" />
<title>[CONFIGURED TITLE]</title>
<meta name="description" content="[CONFIGURED DESCRIPTION]">
<meta name="author" content="[CONFIGURED AUTHOR]">
Adapted from HTML-Framework "HTML5 Boilerplate" and recommendations of the CSS-Frameworks "YAML" and "Bootstrap": Meta tags for "X-UA-Compatible" and "viewport" used, for cross-browser compatibility, normalizing, building responsive designs and using chromeframe if possible:
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
Adapted from HTML-Framework "HTML5 Boilerplate": Show legacy info if IE7 is used. This is included in the beginning of <body>:
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
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 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.
- 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.
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.
Class Reference
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_afterStaticDebugging 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.