Libraries: Master: Unterschied zwischen den Versionen

Aus CodeCoupler Wiki
Zur Navigation springen Zur Suche springen
← Zum vorherigen VersionsunterschiedZum nächsten Versionsunterschied →
Tm (Diskussion | Beiträge)
447 Bearbeitungen
Tm (Diskussion | Beiträge)
447 Bearbeitungen
Zeile 160: Zeile 160:
=== Static Content ===
=== Static Content ===


Into the following files, located in the folder '''application/views/master/static''', you can add content to include into the master-template statically.  
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>:
Static content at the beginning of <head>:

Version vom 2. Dezember 2013, 00:58 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

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.

Adding new Components

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

  • Create a new subdirectory within the folder components. Name it like the component you want add followed by a dash and a version number. Using a version number enable the system to use long term caching while updating correctly new versions of the component.
  • Within this folder you are free to place assets however you want. You can create subfolders or place all into the root of this folder. Put here only the minimum you need, and only minified versions of the library if possible.
  • Create a new subdirectory within the folder codecoupler/views/components named as the component you want to add, without any version information. Place in there four files including the HTML-code needed to for your component. 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.
  • Add in the file application/config/components.php two configuration variables as follows:
    • $config['master_components_config']['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_config']['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.
  • Add in the file application/config/master.php two configuration variables as follows:
    • $config['master_components']['NAME_OF_YOUR_COMPONENT']['enabled']: Set this to TRUE, if you want to be your component enabled by default. Otherwise set it to FALSE.
    • $config['master_components']['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).

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.

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);
  1. Do not use the extensions ".js" and ".css". They will be appended automatically!
  2. 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/main.php. Within the sourcecode of this file you can read all accessible variables.

Abgerufen von „https://archive.codecoupler.org/index.php?title=Libraries:_Master&oldid=252“