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>
		<meta charset="[CONFIGURED CHARSET]" />
		<title>[CONFIGURED TITLE]</title>
		<meta name="description" content="[CONFIGURED DESCRIPTION]">
		<meta name="author" content="[CONFIGURED AUTHOR]">
		<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
		<meta name="viewport" content="width=device-width, initial-scale=1.0">
                [STATIC, DYNAMIC AND COMPONENTS CONTENT (head_init)]
                [AUTOMATIC CSS INCLUSION OF VIEW]
                [AUTOMATIC JAVASCRIPT INCLUSION OF CONTROLLER]
                [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>

The master template includes details recommended by the css-frameworks "HTML5 Boilerplate" and "YAML". The following features was adapted from there:

  • The class of the <html> tag contains no-js, lt-ie9, lt-ie8 or lt-ie7 depending on the browser used.
  • Meta tags for "X-UA-Compatible" and "viewport" used, for cross-browser compatibility and normalizing.
  • Including chromeframe if used browser is IE and version is less then 7.

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]-->

Beyond this, the following code will be included at 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

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.

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=148“