HTMLHeader-Extension

1. Introduction

The HTMLHeader extension is used to copy any HTML elements later into the head of a page, to deliver JavaScript and CSS-objects anywhere within an APF folder and to summarize, minimize, compress and to cache JS- and CSS files. This allows faster loading times of complex JS and CSS constructs. In addition, all JS nodes can be injected to the end of the HTML body which increases the perceived load time of a page.

2. Add head nodes later

In dynamic applications it is often necessary to add data to the page's html head from any point even if it is not actually in the current sphere of influence. For this the HTMLHeader was made. With it, the head area can be added at any point, whether from a template, from a manager or through a document controller. You can add pretty much all sorts of HTML head elements, from the title tag up to include JavaScript and CSS files. If a required tag is missed it is easily possible to add it later.

The JS and CSS files can be defined as static, or delivered as an action or as a package whose URLs are automatically generated.

In the head section of the page the htmlheader:gethead tag must be placed, which uses an output filter to handle the output of post-added information:

APF template
<head> <core:addtaglib class="APF\extensions\htmlheader\pres\taglib\HtmlHeaderGetHeadTag" prefix="htmlheader" name="gethead" /> <htmlheader:gethead /> </head>

If JavaScript files should to be added to the end of the html body, the getbodyjs taglib must be inserted before the closing body tag:

APF template
<body> ... <core:addtaglib class="APF\extensions\htmlheader\pres\taglib\HtmlHeaderGetBodyJsTag" prefix="htmlheader" name="getbodyjs" /> <htmlheader:getbodyjs /> </body>

2.1. In templates

There are some taglibs available to add information in templates. If a scenario is not covered, you can easily write your own taglibs that address the HTMLHeader's API. All taglibs are located in extensions/htmlheader/pres/taglib, starting with the prefix "HtmlHeader" and must be included by using core:addtaglib. Die Taglibs befinden sich alle unter extensions/htmlheader/pres/taglib, besitzen das Prefix "HtmlHeader" und müssen vor der Verwendung mittels core:addtaglib hinzugefügt werden. The use of htmlheader:addcss in a core template would look like this:

APF template
<core:addtaglib class="APF\extensions\htmlheader\pres\taglib\HtmlHeaderAddCssTag" prefix="htmlheader" name="addcss" /> [...]
2.1.1. Title tag

The title of a page can be defined by using the addtitle taglib. If the optional attribute append is set to true, the content of the tag will be added to any existing title, otherwise the existing title will be completely replaced.

APF template
<htmlheader:addtitle append="true"> My cool website title </htmlheader:addtitle>
2.1.2. Static JS & CSS code

Static JS and CSS code (inline, not an external file outsourced) can be added as follows:

APF template
<htmlheader:addjscontent> $('#foo').appendClass('bar'); </htmlheader:addjscontent>
APF template
<htmlheader:addcsscontent> .exampleClass { border: 1px solid red; } </htmlheader:addcsscontent>
2.1.3. Static JS & CSS files

Static JS and CSS files can be added as follows:

APF template
<htmlheader:addstaticjs file="http://maps.google.com/maps/api/js?sensor=false" />
APF template
<htmlheader:addstaticcss file="http://media.adventure-php-framework.org/css/apf.css" />
2.1.4. Dynamic JS & CSS files

It is possible to have the URL of the JS and CSS files automatically generated and to have the files integrated by an FC action, if they are e.g. outside the accessible area.

The two taglibs htmlheader:addcss and htmlheader:addjs are available for this purpose. The functionality is shown only on the addjs taglib because addcss works on the same pattern.

There are the following attributes available:

  • url: Can be used to integrate files from a foreign server.
  • folder: When a file is included by a foreign server, it defines the namespace for the file on the server, with \ as / separation.
  • namespace: The namespace of the file if it is on the same server.
  • filename: The filename without ending.
  • rewriting: Optional. Used if you want to explicitly generate a URL that has rewriting turned on / off. By default the setting of the website is used.
  • fcaction: Optional. If no FC action is used for delivery, set this value to false. (Default: true)

Example: Including a JS file of the current server using an FC action:

APF template
<htmlheader:addjs namespace="APF\sites\example\pres\frontend\static\js" filename="jquery.min" />

Example: Including a external file with deactivated URL rewrite and without FC action to the end of the body:

APF template
<htmlheader:addjs url="http://static/" folder="js\anything" filename="jquery.min" rewriting="false" fcaction="false" appendtobody="true" />
2.1.5. JS & CSS packages

With the JsCssPackager built into the HTML header, many JS or CSS files can be grouped into one file. For the configuration of this scenario please scroll to chapter 3. Define JS & CSS packages. Here the integration of a package within a template is described.

The name attribute corresponds to the package name, which is used as the section name in the configuration. Possible types are js and css.

APF template
<htmlheader:addpackage name="form_clientvalidators_all" type="js" />
APF template
<htmlheader:addpackage name="mystylesheetpackage" type="css"
2.1.6. CSS images (favicons etc.)

To add a favicon use the htmlheader:addcssimage taglib:

APF template
<htmlheader:addcssimage rel="icon" href="favicon.png" type="image/png" />
2.1.7. Control order

The order of the JS and CSS packages can by controled by the optional priority attribute. The higher the value (integer) is the higher the file is included:

APF template
<htmlheader:addpackage name="admin" type="js" appendtobody="true" priority="100" />
If priority is not set 0 (zero) will by used by default.

2.2. In controller and PHP files

The extension consists of many html nodes in the namespace APF\extensions\htmlheader\biz. The desired nodes must be first included by using:

PHP code
use APF\extensions\htmlheader\biz\DynamicJsNode;

The following nodes are available:

  • BaseUrlNode: To define base href=""
  • CanonicalNode: To define link rel="canonical" href=""
  • ConditionalDynamicCssNode
  • ConditionalStaticCssNode
  • CssContentNode
  • CssImageNode
  • CssPackageNode
  • DynamicCssNode
  • DynamicJsNode
  • HttpMetaNode
  • JsContentNode
  • JsPackageNode
  • LanguageMetaNode
  • RefreshNode
  • SimpleMetaNode
  • SimpleTitleNode
  • StaticCssNode
  • StaticJsNode

Next an instance of the HtmlHeaderManager is obtained which will save the nodes:

PHP code
// Get an instance of HtmlHeaderManager: $HHM = $this->getServiceObject('APF\extensions\htmlheader\biz\HtmlHeaderManager');

Now an instance of each desired node can be created and passed to the HtmlHeaderManager:

PHP code
use APF\extensions\htmlheader\biz\RefreshNode; // Add a refresh on index.php?test=abc, with a delay of 5 seconds: $HHM->addNode(new RefreshNode('index.php', 5, array("test" => "abc")));
PHP code
use APF\extensions\htmlheader\biz\SimpleTitleNode; // Add a title $HHM->addNode(new SimpleTitleNode("Example title"));
PHP code
use APF\extensions\htmlheader\biz\DynamicCssNode; //Get instance, configure in constructor and add to HtmlHeaderManager: $CssNode = new DynamicCssNode($url, $namespace, $filename, $rewriting, $fcaction); $HHM->addNode($CssNode);
PHP code
use APF\extensions\htmlheader\biz\SimpleMetaNode; // Add a simple description meta tag $HHM->addNode(new SimpleMetaNode('description', $description));
PHP code
use APF\extensions\htmlheader\biz\HttpMetaNode; // Add a http meta tag definition $HHM->addNode(new HttpMetaNode('content-type', 'text/html; charset=utf-8'));
PHP code
use APF\extensions\htmlheader\biz\JsPackageNode; // Define and add a JsCSSPackager-Package (JavaScript) to HHM $PackageNode = new JsPackageNode($url, $name, $type, $rewriting); $HHM->addPackage($PackageNode);
The order of the nodes can by controled by using the setPriority() mezhod:
PHP code
use APF\extensions\htmlheader\biz\SimpleMetaNode; $node = new SimpleMetaNode('description', $description); $node->setPriority(20); $HHM->addNode($node);
The JavaScript nodes or packages can alo be added at the end of the body. Use therefore the setAppendToBody() method:
PHP code
use APF\extensions\htmlheader\biz\JsPackageNode; $PackageNode = new JsPackageNode($url, $name, $type, $rewriting); $PackageNode->setAppendToBody(true); $HHM->addPackage($PackageNode);

3. Define JS & CSS packages

To deliver packages they must be configured beforehand. This requires the configuration file config/extensions/htmlheader/biz/{CONTEXT}/{ENVIRONMENT}_JsCssPackager.ini.
For each package a section must be created there, with a freely selectable package name as the section name:

APF configuration
[administration] ClientCacheDays = "7" ; How long should it be cached on client? ServerCacheMinutes = "10080" ; How long should it be cached on server? EnableShrinking = "false" ; Shrink the code in the package? PackageType = "js" ; Possible types: 'js' and 'css' ; The files the package contains. Filename without extension! Files.1.Namespace = "VENDOR\pres\js\jquery" Files.1.Filename = "jquery-3.3.1.min" Files.2.Namespace = "VENDOR\pres\js\popper" Files.2.Filename = "popper.min" Files.3.Namespace = "VENDOR\pres\js\bootstrap" Files.3.Filename = "bootstrap.min"

Each package can be individually configured with caching times as well as shrinking (de)activated. By shrinking unnecessary characters are removed from the files. This usually results in a one-line code that is difficult for people to read but can be interpreted without problems by the browser.

A unique number for every file to include is defined in the subsection Files (multiple numbers are not allowed and can result in undesired effects). Also namespace and file ending are defined.

The same applies to CSS files. Here only the PackageType must be changed to "css".
When server-side caching is enabled, the finished package is once compressed (gzip) and once uncompressed (for non-gzip clients) saved so that it does not need to be regenerated on the next call and can by delivered directly. This is done using the CacheManager of the APF.
Therefore a configuration for the CacheManager is needed. The Packager is using the cache with the name jscsspackager_cache which must be defined in the CacheManager config file. The TextCacheProvider is recommended for this purpose.
Further information can be found in the documentation for the CacheManager: CacheManager.

4. Deliver JS & CSS files/packages

To deliver JS & CSS files by FC action or to deliver equivalent packages a FrontController action must be configured. At config/extensions/htmlheader/{CONTEXT}/{ENVIRONMENT}_actionconfig.ini must be placed the following configuration:

APF configuration
[JsCss] ActionClass = "APF\extensions\htmlheader\biz\actions\JsCssInclusionAction"

Furthermore, JS & CSS files can also be shrinked before delivered to save bandwidth. This can be definied in the configuration file config/extensions/htmlheader/biz/{CONTEXT}/{ENVIRONMENT}_JsCssInclusion.ini:

APF configuration
[General] EnableShrinking = "true"
This setting applies only to files. Packages can be configures individually. See chapter 3. Define JS & CSS packages for more information about this.
To shrink JavaScript files in JS packages the external library JShrink is needed. This is available at https://github.com/tedivm/JShrink. To activate the shrinking import the file Minifier.php e. g. in your bootstrap file to define the class JShrink globally.

5. Looking of Action URLs

For the default APF scheme the URLs for files and packages that are included look like this:

If only the html header nodes are used it is not necessary to know this scheme because the nodes automatically generate the URL. This is only necessary if the URLs have to be inserted manually .

Without URL rewrite:

Code
// single CSS file (themes/default/css/menu.css) /index.php?extensions_htmlheader-action:JsCss=path:themes_default_css|type:css|file:menu // single package (CSS) /index.php?extensions_htmlheader-action:JsCss=package:DefaultTheme.css

With URL rewrite:

Code
// single CSS file (themes/default/css/menu.css) /~/extensions_htmlheader-action/JsCss/path/themes_default_css/type/css/file/menu // single package (CSS) /~/extensions_htmlheader-action/JsCss/package/DefaultTheme.css

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.

In order to provide a state-of-the-art web experience and to continuously improve our services we are using cookies. By using this web page you agree to the use of cookies. For more information, please refer to our Privacy policy.