Libraries: Master

Aus CodeCoupler Wiki
Zur Navigation springen Zur Suche springen

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]
                [STATIC, DYNAMIC AND COMPONENTS CONTENT (head_finish)]
	</head>
	<body>
		[STATIC, DYNAMIC AND COMPONENTS CONTENT (body_init)]
		[YOUR CONTROLLER OUTPUT]
		[STATIC, DYNAMIC AND COMPONENTS CONTENT (body_finish)]
	</body>
</html>

Details of the Structure

Adapted from HTML-Framework "HTML5 Boilertemplate": 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]-->

Adapted from HTML-Framework "HTML5 Boilertemplate" and recommendations of the CSS-Framework "YAML": Meta tags for "X-UA-Compatible" and "viewport" used, for cross-browser compatibility, normalizing 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">

Basic meta information can be configured and will always be included: 

<meta charset="[CONFIGURED CHARSET]" />
<meta name="description" content="[CONFIGURED DESCRIPTION]">
<meta name="author" content="[CONFIGURED AUTHOR]">

Setting <base> for portable linking ressources. You do not have to use <?=base_url()?> anymore: 

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

Adapted from HTML-Framework "HTML5 Boilertemplate": 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 more details to this topic, an overview of all components, their keys and how to add you own components here: Libraries: Master: Components

Enable/Disable by Configuration

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

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

Setting this variable to TRUE, will enable the component.

Enable/Disable Dynamicaly

Everywhere in your code you can enable or disable components. Use the following functions to handle components:

  • $this->master->enable_component($key): Enable component. Use the name of the component as $key.
  • $this->master->disable_component($key): Disable component. Use the name of the component as $key.
  • $this->master->disable_all_components(): Disable all components.
  • $this->master->is_component_enabled($key): Returns TRUE if the component is enabled, otherwise FALSE. Use the name of the component as $key.

Advanced Configuration

Components can be configured in application/config/components.php. Every component will be described in one array with three keys:

  • config: This value ist component specific. You can finetune the component here. Please read the chapter Libraries: Master: Components.
  • depends: This array tells the framework on what components this one depends. Depending components will be enabled automatically. Normally you do not have to modify this.
  • after: This array tells the framework after of what enabled components this one should be included. Normally you do not have to modify this.

Loading JavaScript and CSS

Custom Files

The Syntax for linking to a JavaScript file or a stylesheet file is similar to the syntax for loading a view. To add a link to JavaScript-File, you can use the following function: 

$this->load->script('SCRIPTNAME');

To add a link to a stylesheet-file you can use: 

$this->load->style('STYLENAME');
  • The JavaScript files you have to place into the directory application/scripts. The used "SCRIPTNAME" is the name of the file without the extension "js".
  • The stylesheet files you have to place into the directory application/styles. The used "STYLENAME" is the name of the file without the extension "css".

Automatic loaded Files

Two files will be automatic loaded as long by default:

  • application/scripts/global.js
  • application/styles/global.css

You can alter this behaviour by modifying the variable $config['master_global_load'] in the file application/config/master.php:

  • Automatically load global.js: $config['master_global_load'] = "js"
  • Automatically load global.css: $config['master_global_load'] = "css"
  • Automatically load both: $config['master_global_load'] = "both"

Adding static content

In the folder application/views/master/static you will find four files. Here you can add content to include into the master-template statically. All this filenames and the location of this files are configurable:

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 content by code

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

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

$postion can be one of the following values:

To add content at the beginning of <head>:

  • MasterPosition::head_init_beforeComponents_beforeStatic: Before code of components and code of static files.
  • MasterPosition::head_init_beforeComponents_afterStatic]: Before code of components but after code of static files.
  • MasterPosition::head_init_afterComponents_beforeStatic]: After code of components but after code of static files.
  • MasterPosition::head_init_afterComponents_afterStatic]:
  • 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_finish_beforeComponents_beforeStatic]:
  • MasterPosition::body_finish_beforeComponents_afterStatic]:
  • MasterPosition::body_finish_afterComponents_beforeStatic]:
  • MasterPosition::body_finish_afterComponents_afterStatic]:

Or more sophisticated by specifying a key. If somewhere have been added content with the same key, the previous content will be overwritten.

  • $this->master->add_headstart($key,$content)
  • $this->master->add_headend($key,$content)
  • $this->master->add_bodystart($key,$content)
  • $this->master->add_bodyend($key,$content)

Alternatively you can specify one more parameter "overwrite". Setting "overwrite" to FALSE the previous content will not be overwritten, it will be retained and your content will discarded.

  • $this->master->add_headstart($key,$content,FALSE)
  • $this->master->add_headend($key,$content,FALSE)
  • $this->master->add_bodystart($key,$content,FALSE)
  • $this->master->add_bodyend($key,$content,FALSE)

Automatic inclusion of javascript and css

tbd

Configuration

Some basic configurations you can do here 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_static_headstart: Path to the view where static content will be defined for the beginning of <head>.
  • master_static_headend: Path to the view where static content will be defined for the end of <head>.
  • master_static_bodystart: Path to the view where static content will be defined for the beginning of <body>.
  • master_static_bodyend: Path to the view where static content will be defined for the end of <body>.
  • master_components: Here you can configure the master-components. Read further down a detailed description of master components.

And language specific configurations can be done here 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.

Changing configuration by code

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

Enable or disable completely

You can of course disable the templating completely. This is important for 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.

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_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-documnet. In this case you can modify the file application/views/master/main/main.php. Within this template you can access the following additional variables:

  • $master_doctype: Complete <!DOCTYPE>-Tag based on the configuration "master_doctype".
  • $master_charset: Configuration value "master_charset".
  • $master_lang: Configuration value "master_lang".
  • $master_title: Configuration value "master_title".
  • $master_description: Configuration value "master_description".
  • $master_author: Configuration value "master_author".
  • $master_body_controller: The original output of the called controller.
  • $master_head_autoincluded: Content for <head>, defeined by autoincluded javascript and css files.
  • $master_headstart_dynamic: Content for <head>, defined by enabled components and dynamically added content with add_head().
  • $master_headend_dynamic: Content for <head>, defined by enabled components and dynamically added content with add_head().
  • $master_bodystart_dynamic: Content for <body> defined by dynamically added content with add_bodystart().
  • $master_bodyend_dynamic: Content for <body> defined by dynamically added content with add_bodyend().
  • $master_headstart_static: Content for <head>, defined by the static view headstart.php.
  • $master_headend_static: Content for <head>, defined by the static view headend.php.
  • $master_bodystart_static: Content for <body> defined by the static view bodystart.php.
  • $master_bodyend_static: Content for <body> defined by the static view bodyend.php.
  • $master_headstart_components: Content for <head>, defined by enabled components.
  • $master_headend_components: Content for <head>, defined by enabled components.
  • $master_bodystart_components: Content for <body>, defined by enabled components.
  • $master_bodyend_components: Content for <body>, defined by enabled components.
Abgerufen von „https://archive.codecoupler.org/index.php?title=Libraries:_Master&oldid=179“