InterJinn

Development Framework For PHP

Documentation

Page Patterns

Now that you have at least one template and at least one source file, its time for you to create a pattern. A pattern is a description of what source file is blended with what template, and to where the compiled information should be stored. Other data such as the title of the page and the language are also defined by the pattern. If you are using the database pattern system, then you will populate the page_patterns table of the database. On the other hand if you are using the file based pattern system, then you will add patterns to the file you defined by the project configuration variable:

$GLOBALS['interJinn']['pagePatternSystem']

This should be located in your project configuration file. The format of the data follows:

  • template
  • source
  • target
  • language
  • title
  • extra
  • group
  • comment

You will have many of these declarations to describe your whole Web site. The nice thing is that you can re-use any template or source file and create multiple targets with different styles. This is very useful for things like printer-friendly pages where you want the same content but without the navigation framework. Detailed descriptions of these pattern fields follow.

Field - template

The template field defines the layout of your target. Any common content, headers, or structures should go here. When the target is compiled the defined source content will be compiled into this template to create a target with the common look and feel of the the given template. If the template path begins with // then the template path will be considered relative to the compileTemplatePath that you set in the project configuration. If the path is preceded by / then the template will be retrieved relative to the root of the filesystem. Last, if neither of the former two cases are true then the path will be treated as though it has been prefixed with //. You should make sure that read permission is set for the appropriate owners at this location. The value of this field will also undergo multilingual resolution if multilingual has been set in the project configuration (see the Template Documentation for an explanation).

Example:
'template' => '//mainLayout.template'

The recent addition of the Content Manager Service has added the option to load content via any number of different methods. To specify the exact method you must use the following styles for your path:

Examples:
file:////mainLayout.template
sql:///templates/main.template

There are three parts to the examples and specifically for the first example: the type specifier file, the separator ://, and the path //mainLayout.template. If you do not specify the type portion of the path, then the value configured in the $GLOBALS['interJinn']['contentDefaultType'] property will be used to determine the type. If this property has not been set then file is assumed.

Field - source

All of the unique characteristics of your web site will either come from an embedded module or from the source you set here. This is the content that will make the target interesting. When the target is compiled this source content will be compiled into the defined template to create the target. If the source file path begins with // then the source file path will be considered relative to the compileSourcePath that you set in the project configuration. If the path is preceded by / then the source file will be retrieved relative to the root of the filesystem. Last, if neither of the former two cases are true then the path will be treated as though it has been prefixed with //. You should make sure that read permission is set for the appropriate owners at this location. The value of this field will also undergo multilingual resolution if multilingual has been set in the project configuration (see the Source File Documentation for an explanation).

Example:
'source' => '//documentations/templateJinn.source'

The recent addition of the Content Manager Service has added the option to load content via any number of different methods. To specify the exact method you must use the following styles for your path:

Examples:
file:////mainLayout.template
sql:///templates/main.template

There are three parts to the examples and specifically for the first example: the type specifier file, the separator ://, and the path //mainLayout.template. If you do not specify the type portion of the path, then the value configured in the $GLOBALS['interJinn']['contentDefaultType'] property will be used to determine the type. If this property has not been set then file is assumed.

Field - target

This is the target for the results of mixing the template with the source. If the target path begins with // then the target path will be considered relative to the pageBase that you set in the project configuration. If the path is preceded by / then the target will be created relative to the pageRoot that you set in the project configuration. Last, if neither of the former two cases are true then the path will be treated as though it has been prefixed with //. You should make sure that read and write permissions are set for the appropriate owners at this location.

Example:
'target' => '//documentations/templateJinn.php'

Field - language

If you are working with a unilingual project site and (multilingual is not set or is set to false in your project configuration), then you may ignore this field. On the other hand if you are working with a multilingual site then this determines what language or languages to use for compiling the target. This field may be set to a single language or to multiple languages separated by a comma.

Example:
'language' => 'en'
Example:
'language' => 'en, fr, sp'

A compilation will occur for each language declared. For this reason if you have more than one language declared you will want to use the language macro in the target path. The language macro is denoted by either [[LANGUAGE]] or if you prefer [[LANG]]. See the description about the extra field for details on how to use a different macro. The current language will be expanded in place of this macro wherever it is found in the target path.

Example:
'target'   => '//documentations/templateJinn.[[LANG]].php'
'language' => 'en, fr, sp'
Targets Created:
/documentations/templateJinn.en.php
/documentations/templateJinn.fr.php
/documentations/templateJinn.sp.php
Another Example:
'target'   => '//[[LANG]]/documentations/templateJinn.php'
'language' => 'en, fr, sp'
Targets Created:
/en/documentations/templateJinn.php
/fr/documentations/templateJinn.php
/sp/documentations/templateJinn.php

The language field also influences how the template and source files are located. When the template is retrieved an attempt to find it in a language named subdirectory of the set path will first be made, if this fails then the template will be retrieved explicitly from the path provided. This same functionality is also true of the source file retrieval.

Another Example:
'template' => '//printerFriendly/mainLayout.template'
'language' => 'en'
Order Of Search:
/printerFriendly/en/mainLayout.template
/printerFriendly/mainLayout.template

This does not mean you must create a template or source file for every language; however, you do have that capability. You will continue to learn more about how this language field influences your system as you read further and learn about the tags that are available to you with the packaged Jinn Compiler.

Field - title

Set this field to the title of the target page. This value will be available via the <jinn:pageTitle/> and <jinn:title/> tags described later. If your project is multilingual then you may set this value to an array of language keys to title values and the appropriate one will be chosen when the target is created.

Example:
'title' => array
(
    'en' => 'The TemplateJinn Manual',
    'fr' => 'Le Manuel De TemplateJinn',
    'sp' => 'El Manual Del TemplateJinn'
)

Field - extra

An arbitrary configuration field in which you can create any data structures or set any data that you want to be available to a custom compiler or to any dynamic modules you create for the target. One very good example for this field is to create a configuration value called validate which can be used by a module or service, that has been included in each page (possibly via a template) to determine if the page needs to validate that the visitor has been authenticated. Then you can easily set which targets require authentication and which do not.

Example:
'extra' => array
(
    'validate' => true
)

Field - group

The group field is an optional and convenient way to group patterns together. This information is available to the compiler and to any dynamic modules. It could easily have just been a part of the extra field but when it was created I had not yet foreseen the need for an extra field.

Example:
'group' => 'admin'

Field - comment

An optional freeform field in which to place any comments describing the pattern. This may or may not be useful to you and the value is ignored.

Example:
'comment' => 'This target includes remote source content.'

Now that you have learned about all of the available pattern fields an example that illustrates it all together would be appropriate. The following example takes advantage of the multilingual system and summarizes many of the examples you have already seen.

Filesystem Based Pattern Example:
array
(
    'template'  => '/admin/layout.template',
    'source'    => '/admin/createUser.source',
    'target'    => '/admin/createUser.[[LANG]].php',
    'language'  => 'en, fr, sp',
    'group'     => 'admin',
    'title'     => array
    (
        'en' => 'Create New User Account',
        'fr' => "Créez Le Nouveau Compte D'Utilisateur",
        'sp' => 'Cree La Nueva Cuenta Del Usuario'
    ),
    'extra'     => array( 'validate' => true ),
    'comment'   => 'The user account creation page.''
)
Database Pattern Example:
INSERT INTO page_patterns
(
    template,
    source,
    target,
    language,
    group_id,
    title,
    extra,
    comment
)
VALUES
(
    '/admin/layout.template',
    '/admin/createUser.source',
    '/admin/createUser.[[LANG]].php',
    'en, fr, sp',
    'admin',
    "'en' => 'Create New User Account',
     'fr' => \"Créez Le Nouveau Compte D'Utilisateur\",
     'sp' => 'Cree La Nueva Cuenta Del Usuario'",
    "'validate' => true",
    'The user account creation page.'
);
Copyright © 2001-2008 Robert Cummings
All Rights Reserved