GeeklogWiki - User contributions [en]

Installing Geeklog:System Requirements

2022-09-27T17:22:56Z

Tom: /* Installation - System Requirements */

== Installation - System Requirements ==

The system requirements for installing Geeklog v2.2.2 (the last time the requirements changed) and later are as follows:

# Web server - one of the following
## Apache Web Server
## Microsoft IIS (Internet Information Server)
# PHP v5.6.4 or higher (including PHP v8.1) with the following extensions
## mbstring Extension
## bzip2 Extension
## mysql or mysqli Extension (To enable MySQL support)
## pgsql Extension (To enable Postgresql support)
## OpenSSL Extension (To enable the Geeklog OAuth Login process)
## JSON Extension (For Filemanager and Database tools)
## fileinfo (To enable thumbnail creation of images in articles) (for IIS only as fileinfo is integrated into Apache)
## cURL (Not required but recommended for the reCaptcha plugin)
# Database server - one of the following
## MySQL 4.1.3 or higher (MySQL 5 recommended)
## Postgresql 9.1.7 or later
# The ability to create a new database or to have access to an existing one

Main Page

2022-09-27T17:22:16Z

Tom: /* Geeklog Documentation */

[[Image:Logo.gif]]

== Geeklog Documentation ==

This is the main entry for Documentation for the [https://www.geeklog.net/ Geeklog] Content Management System (CMS). The current version is v2.2.2. For more information about this version please read [https://www.geeklog.net/article.php/geeklog-v2-2-2 this announcement article].

If you are upgrading from Geeklog v2.1.3 or older please make sure your 3rd party Geeklog plugins are updated to the latest version and support at least Geeklog v2.2.0. Plugins are now required to use the function COM_createHTMLDocument. This replaces the depreciated functions COM_siteHeader and COM_siteFooter. If you are unsure if a plugin supports Geeklog v2.2.0 then either disable it before you upgrade Geeklog, or uninstall it.

Also, there have been some changes with blocks and topics between Geeklog 2.0.0 and 1.8.2sr1 so not all plugins may work with 2.1.0 or higher unless they have been updated. If you are upgrading your site that is 2.0.0 or older make sure all the plugins you use are compatible with Geeklog 2.1.0 or higher.

This documentation is a result of community action. Everyone is invited to [http://wiki.geeklog.net/wiki/index.php?title=Special:Userlogin sign up] and participate. If you see an omission you can fill it in. If you see a mistake, correct it. If you see where things could be better organized, change it. If you have a note about a particular configuration, add it. In other words: We need your help to make it better!

* [[Geeklog Documentation]]:
*# [[Introduction]]
*# [[Installation]]
*# [[Administration]]
*# [[Users Documentation|User's Documentation]]
*# [[Programmers/Developers Documentation]]
* Quick Links:
*# [[Complete Table of Contents]]
*# [[Special:AllPages|List of all Articles]]
*# [[Getting Started]] with Geeklog Development
*# [[Google Summer of Code]]

Caching Template Library

2022-01-13T15:22:47Z

Tom: /* PHP Code in a Template Files */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :h Call strip_tags on the variable before output. (as of Geeklog v2.2.1)
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments. If you want these comments to appear in the cache and the HTML source of the page you can in the Geeklog Configuration enable "Template Comments in Output". See example 3 to see how to use a comment.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
In this example, we set the array myVar and then print it out using a while loop:
<pre>
{!!set myVar array('a', 'b') !!}
{!!set myCount 0 !!}

{!!while !empty(array_slice({myVar}, {myCount}, 1)) !!}
{!!set myVar1 array_slice({myVar}, {myCount}, 1)[0] !!}
myVar: {myVar1}<br>
{!inc myCount}
{!endwhile!}
</pre>
The output then looks like this:
<pre>
myVar: a
myVar: b
</pre>

==== Example 5 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. Remember you need to be very careful when using PHP and selecting variable names for variables you create in your code. Make sure they are unique as variables can unintentionally be overwritten if they are for example global in scope and/or are local in scope but are being used in the Geeklog function already that will be evaluating your PHP code.

To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Installing Geeklog:System Requirements

2020-04-19T21:50:36Z

Tom: /* Installation - System Requirements */

== Installation - System Requirements ==

The system requirements for installing Geeklog v2.2.1 (the last time the requirements changed) and later are as follows:

# Web server - one of the following
## Apache Web Server
## Microsoft IIS (Internet Information Server)
# PHP v5.6.4 or higher (including PHP v7) with the following extensions
## mbstring Extension
## bzip2 Extension
## mysql or mysqli Extension (To enable MySQL support)
## pgsql Extension (To enable Postgresql support)
## OpenSSL Extension (To enable the Geeklog OAuth Login process)
## JSON Extension (For Filemanager and Database tools)
## fileinfo (To enable thumbnail creation of images in articles) (for IIS only as fileinfo is integrated into Apache)
## cURL (Not required but recommended for the reCaptcha plugin)
# Database server - one of the following
## MySQL 4.1.3 or higher (MySQL 5 recommended)
## Postgresql 9.1.7 or later
# The ability to create a new database or to have access to an existing one

Installing Geeklog:System Requirements

2020-04-19T21:50:25Z

Tom: /* Installation - System Requirements */

== Installation - System Requirements ==

The system requirements for installing Geeklog v2.2.1 (the last time the requirements changed) and later are as follows:

# Web server - one of the following
## Apache Web Server
## Microsoft IIS (Internet Information Server)
# PHP v5.6.4 or higher (including PHP 7) with the following extensions
## mbstring Extension
## bzip2 Extension
## mysql or mysqli Extension (To enable MySQL support)
## pgsql Extension (To enable Postgresql support)
## OpenSSL Extension (To enable the Geeklog OAuth Login process)
## JSON Extension (For Filemanager and Database tools)
## fileinfo (To enable thumbnail creation of images in articles) (for IIS only as fileinfo is integrated into Apache)
## cURL (Not required but recommended for the reCaptcha plugin)
# Database server - one of the following
## MySQL 4.1.3 or higher (MySQL 5 recommended)
## Postgresql 9.1.7 or later
# The ability to create a new database or to have access to an existing one

Main Page

2020-04-19T21:49:18Z

Tom: /* Geeklog Documentation */

[[Image:Logo.gif]]

== Geeklog Documentation ==

This is the main entry for Documentation for the [https://www.geeklog.net/ Geeklog] Content Management System (CMS). The current version is v2.2.1sr1. For more information about this version please read [https://www.geeklog.net/article.php/geeklog-v2-2-1sr1 this announcement article].

If you are upgrading from Geeklog v2.1.3 or older please make sure your 3rd party Geeklog plugins are updated to the latest version and support at least Geeklog v2.2.0. Plugins are now required to use the function COM_createHTMLDocument. This replaces the depreciated functions COM_siteHeader and COM_siteFooter. If you are unsure if a plugin supports Geeklog v2.2.0 then either disable it before you upgrade Geeklog, or uninstall it.

Also, there have been some changes with blocks and topics between Geeklog 2.0.0 and 1.8.2sr1 so not all plugins may work with 2.1.0 or higher unless they have been updated. If you are upgrading your site that is 2.0.0 or older make sure all the plugins you use are compatible with Geeklog 2.1.0 or higher.

This documentation is a result of community action. Everyone is invited to [http://wiki.geeklog.net/wiki/index.php?title=Special:Userlogin sign up] and participate. If you see an omission you can fill it in. If you see a mistake, correct it. If you see where things could be better organized, change it. If you have a note about a particular configuration, add it. In other words: We need your help to make it better!

* [[Geeklog Documentation]]:
*# [[Introduction]]
*# [[Installation]]
*# [[Administration]]
*# [[Users Documentation|User's Documentation]]
*# [[Programmers/Developers Documentation]]
* Quick Links:
*# [[Complete Table of Contents]]
*# [[Special:AllPages|List of all Articles]]
*# [[Getting Started]] with Geeklog Development
*# [[Google Summer of Code]]

Geeklog Release Procedures

2020-04-16T15:07:36Z

Tom: /* Geeklog Sites */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history, install.html, changes.html, themevars.html files in docs (both English and Japanese) with the latest info about the version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository. Note: no old compressed install packages will note be rolled into the new package.
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
*** '''IMPORTANT:''' Make sure to tag the release after you have committed the change-files file into the repository as we want these changes included as part of the version
* Visit Geeklog.net
** Add the new release to the Downloads plugin
** In Downloads plugin, move any releases not current to Geeklog->Old Versions (like previous version of Geeklog or older betas and RCs). Need to clear cache after so block updates.
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net as users cannot change themes.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* The demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2020-04-16T13:31:44Z

Tom: /* The Tarball */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history, install.html, changes.html, themevars.html files in docs (both English and Japanese) with the latest info about the version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository. Note: no old compressed install packages will note be rolled into the new package.
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
*** '''IMPORTANT:''' Make sure to tag the release after you have committed the change-files file into the repository as we want these changes included as part of the version
* Visit Geeklog.net
** Add the new release to the Downloads plugin
** In Downloads plugin, move any releases not current to Geeklog->Old Versions (like previous version of Geeklog or older betas and RCs). Need to clear cache after so block updates.
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net as users cannot change themes.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2020-02-27T12:00:29Z

Tom: /* Updating geeklog.net */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository. Note: no old compressed install packages will note be rolled into the new package.
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
*** '''IMPORTANT:''' Make sure to tag the release after you have committed the change-files file into the repository as we want these changes included as part of the version
* Visit Geeklog.net
** Add the new release to the Downloads plugin
** In Downloads plugin, move any releases not current to Geeklog->Old Versions (like previous version of Geeklog or older betas and RCs). Need to clear cache after so block updates.
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net as users cannot change themes.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Installing Geeklog:System Requirements

2020-02-27T11:59:13Z

Tom: /* Installation - System Requirements */

== Installation - System Requirements ==

The system requirements for installing Geeklog v2.2.1 (the last time the requirements changed) and later are as follows:

# Web server - one of the following
## Apache Web Server
## Microsoft IIS (Internet Information Server)
# PHP 5.6.4 or higher with the following extensions
## mbstring Extension
## bzip2 Extension
## mysql or mysqli Extension (To enable MySQL support)
## pgsql Extension (To enable Postgresql support)
## OpenSSL Extension (To enable the Geeklog OAuth Login process)
## JSON Extension (For Filemanager and Database tools)
## fileinfo (To enable thumbnail creation of images in articles) (for IIS only as fileinfo is integrated into Apache)
## cURL (Not required but recommended for the reCaptcha plugin)
# Database server - one of the following
## MySQL 4.1.3 or higher (MySQL 5 recommended)
## Postgresql 9.1.7 or later
# The ability to create a new database or to have access to an existing one

Installing Geeklog:System Requirements

2020-02-27T11:57:37Z

Tom: /* Installation - System Requirements */

== Installation - System Requirements ==

The system requirements for installing Geeklog 2.2.1 and later are as follows:

# Web server - one of the following
## Apache Web Server
## Microsoft IIS (Internet Information Server)
# PHP 5.6.4 or higher with the following extensions
## mbstring Extension
## bzip2 Extension
## mysql or mysqli Extension (To enable MySQL support)
## pgsql Extension (To enable Postgresql support)
## OpenSSL Extension (To enable the Geeklog OAuth Login process)
## JSON Extension (For Filemanager and Database tools)
## fileinfo (To enable thumbnail creation of images in articles) (for IIS only as fileinfo is integrated into Apache)
## cURL (Not required but recommended for the reCaptcha plugin)
# Database server - one of the following
## MySQL 4.1.3 or higher (MySQL 5 recommended)
## Postgresql 9.1.7 or later
# The ability to create a new database or to have access to an existing one

Main Page

2020-02-27T11:56:05Z

Tom: /* Geeklog Documentation */

[[Image:Logo.gif]]

== Geeklog Documentation ==

This is the main entry for Documentation for the [https://www.geeklog.net/ Geeklog] Content Management System (CMS). The current version is v2.2.1. For more information about this version please read [https://www.geeklog.net/article.php/geeklog-v2-2-1 this announcement article].

If you are upgrading from Geeklog v2.1.3 or older please make sure your 3rd party Geeklog plugins are updated to the latest version and support at least Geeklog v2.2.0. Plugins are now required to use the function COM_createHTMLDocument. This replaces the depreciated functions COM_siteHeader and COM_siteFooter. If you are unsure if a plugin supports Geeklog v2.2.0 then either disable it before you upgrade Geeklog, or uninstall it.

Also, there have been some changes with blocks and topics between Geeklog 2.0.0 and 1.8.2sr1 so not all plugins may work with 2.1.0 or higher unless they have been updated. If you are upgrading your site that is 2.0.0 or older make sure all the plugins you use are compatible with Geeklog 2.1.0 or higher.

This documentation is a result of community action. Everyone is invited to [http://wiki.geeklog.net/wiki/index.php?title=Special:Userlogin sign up] and participate. If you see an omission you can fill it in. If you see a mistake, correct it. If you see where things could be better organized, change it. If you have a note about a particular configuration, add it. In other words: We need your help to make it better!

* [[Geeklog Documentation]]:
*# [[Introduction]]
*# [[Installation]]
*# [[Administration]]
*# [[Users Documentation|User's Documentation]]
*# [[Programmers/Developers Documentation]]
* Quick Links:
*# [[Complete Table of Contents]]
*# [[Special:AllPages|List of all Articles]]
*# [[Getting Started]] with Geeklog Development
*# [[Google Summer of Code]]

Geeklog Release Procedures

2019-12-18T15:23:50Z

Tom: /* The Tarball */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository. Note: no old compressed install packages will note be rolled into the new package.
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
*** '''IMPORTANT:''' Make sure to tag the release after you have committed the change-files file into the repository as we want these changes included as part of the version
* Visit Geeklog.net
** Add the new release to the Downloads plugin
** In Downloads plugin, move any releases not current to Geeklog->Old Versions (like previous version of Geeklog or older betas and RCs). Need to clear cache after so block updates.
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2019-11-15T17:33:17Z

Tom: /* The Tarball */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
*** '''IMPORTANT:''' Make sure to tag the release after you have committed the change-files file into the repository as we want these changes included as part of the version
* Visit Geeklog.net
** Add the new release to the Downloads plugin
** In Downloads plugin, move any releases not current to Geeklog->Old Versions (like previous version of Geeklog or older betas and RCs). Need to clear cache after so block updates.
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2019-11-15T16:47:29Z

Tom: /* The Tarball */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
*** '''IMPORTANT:''' Make sure to tag the release after you have committed the change-files file into the repository as we want these changes included as part of the version
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2019-11-15T16:47:14Z

Tom: /* Updating geeklog.net */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
*** Make sure to tag the release after you have committed the change-files file into the repository as we want these changes included as part of the version
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2019-11-15T16:44:14Z

Tom: /* The Tarball */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
*** Make sure to tag the release after you have committed the change-files file into the repository as we want these changes included as part of the version
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2019-11-15T16:43:35Z

Tom: /* The Tarball */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
*** Make sure to tag the release after you have committed the change-files file into the repository as we want these changes included as part of the version (for actual releases not betas)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

New Installation

2019-11-12T11:55:40Z

Tom: /* Folder/File Setup */

== Folder/File Setup ==
* First [https://www.geeklog.net/downloads/index.php?cid=8 download] the latest Geeklog version
* Download the tarball into any directory.
* move the file to your webroot
<pre>tar -zxvf geeklog*.tar.gz</pre>
* Change into the Geeklog directory
<pre>cd geeklog-1.*</pre>
* Copy all files to your primary directory with
<pre>cp -Rf * /home/username/public_html</pre>
* Change the access rights in the directories:
<pre>
chown -R webuser:webuser *
chmod -R 755 logs
chmod -R 755 backups
chmod -R 755 data
chmod -R 755 public_html/backend
chmod -R 755 public_html/images/articles
chmod -R 755 pulic_html/images/topics
chmod -R 755 public_html/images/userphotos/</pre>

== Database ==

* Create your MySQL database, MySQL account, grant privileges to MySQL account.
* As root create the MySQL database and access rights:
<pre>$ mysql -u root
mysql> create database geeklog_db;
mysql>grant all on geeklog.* to geeklog@localhost identified by 'yourgeeklogpassword';
mysql>quit</pre>

== Install ==

* run www.yourdomain.foo/admin/install/index.php
* follow the instructions
* login to your page using default Admin/password
* change password
* remove directory public_html/admin/install

New Installation

2019-11-12T11:55:27Z

Tom:

== Folder/File Setup ==
* First [https://www.geeklog.net/downloads/index.php?cid=88 download] the latest Geeklog version
* Download the tarball into any directory.
* move the file to your webroot
<pre>tar -zxvf geeklog*.tar.gz</pre>
* Change into the Geeklog directory
<pre>cd geeklog-1.*</pre>
* Copy all files to your primary directory with
<pre>cp -Rf * /home/username/public_html</pre>
* Change the access rights in the directories:
<pre>
chown -R webuser:webuser *
chmod -R 755 logs
chmod -R 755 backups
chmod -R 755 data
chmod -R 755 public_html/backend
chmod -R 755 public_html/images/articles
chmod -R 755 pulic_html/images/topics
chmod -R 755 public_html/images/userphotos/</pre>

== Database ==

* Create your MySQL database, MySQL account, grant privileges to MySQL account.
* As root create the MySQL database and access rights:
<pre>$ mysql -u root
mysql> create database geeklog_db;
mysql>grant all on geeklog.* to geeklog@localhost identified by 'yourgeeklogpassword';
mysql>quit</pre>

== Install ==

* run www.yourdomain.foo/admin/install/index.php
* follow the instructions
* login to your page using default Admin/password
* change password
* remove directory public_html/admin/install

Geeklog Release Procedures

2019-11-08T17:44:13Z

Tom: /* The Tarball */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.''' Best way to do this is delete the .gitignore file and then check for any new files.
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2019-11-08T17:38:03Z

Tom: /* The Tarball */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Confirm git is installed on server that install package is being built on so the "changed-files" file gets updated properly
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** '''Make sure no extra files exist as they will get included in the package. This includes db-config.php, siteconfig.php and any images and cached files.'''
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2019-10-25T00:49:45Z

Tom: /* The Tarball */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.properties
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” and “build.properties” in the top directory).
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Installing Geeklog:System Requirements

2019-05-28T13:24:18Z

Tom: /* Installation - System Requirements */

== Installation - System Requirements ==

The system requirements for installing Geeklog 2.1.2 and later are as follows:

# Web server - one of the following
## Apache Web Server
## Microsoft IIS (Internet Information Server)
# PHP 5.3.3 or higher with the following extensions
## mbstring Extension
## bzip2 Extension
## mysql or mysqli Extension (To enable MySQL support)
## pgsql Extension (To enable Postgresql support)
## OpenSSL Extension (To enable the Geeklog OAuth Login process)
## JSON Extension (For Filemanager and Database tools)
## fileinfo (To enable thumbnail creation of images in articles) (for IIS only as fileinfo is integrated into Apache)
## cURL (Not required but recommended for the reCaptcha plugin)
# Database server - one of the following
## MySQL 4.1.3 or higher (MySQL 5 recommended)
## Postgresql 9.1.7 or later
# The ability to create a new database or to have access to an existing one

OAuth

2019-04-07T15:59:08Z

Tom: /* Google */

== What is OAuth? ==

The idea behind OAuth is to get rid of the need to register separately with all the websites out there that require registration before you can use them. Instead of having to keep track of all the different accounts, you can use one login on every website that supports OAuth.

To quote the [http://OAuth.net/ OAuth homepage]:

:"An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications."

OAuth is a free and open protocol. It is not owned by any corporation.

== OAuth in Geeklog ==

OAuth support in Geeklog differs slightly from the [[Remote Authentication]] support, but only in that it requires a separate login prompt.

To activate OAuth support there are several steps.

First you must go to the Configuration Admin panel:

: Configuration > Geeklog > Users and Submissions > Users > User Login Method[OAuth]

Set this option to "true". Just below this configuration option you will find the other OAuth settings. Currently Geeklog supports logging in via Facebook, LinkedIn, Twitter, Yahoo, and Google via OAuth. For each of these login methods you will find an option to enable it and two text boxes for you to enter an Application Id and Application Secret Key (see below to find out how to get an Id and Secret Key). Each of these items needs to be filled out before the login button for it will be enabled. Once you have filled out the required information remember to then save the configuration changes.

Other requirements needed to enable Geeklogs OAuth Login process is you must have the PHP extension OpenSSL loaded on your web server.

The Geeklog User Submission Queue must also be set to false in the Geeklog Configuration. Currently a new remote user cannot be added to the submission queue for approval later on.

When you log out, you will see one or more new login buttons in your site's User Functions block, below the normal login options:

[[Image:OAuth-login.png|border]]

The first time any user clicks on one of the OAuth login buttons they will be redirected to the website offering the OAuth login (Facebook, LinkedIn or Twitter). Here (if they are not currently logged into the website) they will be asked to login. Once logined they will then be asked if they wish to give permission to your Geeklog website to access some of your personal information. If the user approves the request they will then be redirected back to the Geeklog website which will then use the information to create a Geeklog user account and log them into the Geeklog website. If the user does not approve the request for information they will still be redirected back to the website but no Geeklog user account will be created.

The next time the user logs into your Geeklog website using the same OAuth login method Geeklog will check with the website providing the OAuth login to see if you are logged in the site. If not the user will be redirected to the site to login. Once they have the site will the redirect back to your Geeklog website.

When Geeklog uses OAuth to login it's users, it will never see your OAuth password - it will only get an "okay" back from the OAuth provider if you authenticated successfully.

Once a user has logged in via OAuth, they are just like any other Geeklog user. They can be added to groups, change their profile, do whatever else you allow your users to do on your site. And yes, OAuth users can also be banned.

Users that log in through OAuth are automatically added to the "Remote Users" group.

=== Limitations ===

* Currently, OAuth 1.0, 1.0a and 2.0 is supported (depends on what the OAuth provider supports).

== OAuth Login Methods ==

General review...

=== Facebook ===

Please note:
* To use Facebook Login your website must use SSL.
* Use Strict Mode for Redirect URIs on the Facebook Web App defaults to Strict and cannot be changed for new login apps created in the Facebook developer portal. This means you must specify the exact Valid OAuth Redirect URIs used by Geeklog. For example: https://www.yoursitehere.com/users.php?oauth_login=facebook
* You may need to also submit the Login for Facebook review before location / user photo can be retrieved. You have to include a screencast showing how you login and use the Facebook data.

Access Facebook 'Create an Application' page, and input form.

Please go to Facebook Apps page https://developers.facebook.com/apps

=== LinkedIn ===

Access LinkedIn 'List of Applications' page, and click 'Add New Application'.<br>
https://www.linkedin.com/secure/developer

=== Twitter ===

Access 'Applications Using Twitter' page and click 'Register a new application'.<br>
https://dev.twitter.com/apps/new<br><br>
Application Type: Select 'Browser'<br>
Callback URL: Input URL same as Website<br>
Default Access type: Select 'Read & Write'<br>
Use Twitter for login: Check<br>
Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=twitter

=== Microsoft Live ===

Allows users to login with their Hotmail, Live or Outlook email accounts
Please go to Microsoft Live Connect Developer Center page https://manage.dev.live.com/AddApplication.aspx

=== Google ===

Note: Google will shutdown Google+ on April 2, 2019. As of Geeklog v2.2.1 we will move from the Google+ OAuth scope to the Google OAuth scope. Because of this change you may need to update your Google API key

Google APIs console page http://code.google.com/apis/console in the API access tab

Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=google

=== Yahoo ===

Yahoo Apps page https://developer.apps.yahoo.com/wsregapp/

=== GitHub ===

GitHub Developer page https://developer.github.com/v3/oauth/

Create a new GitHub Application: https://github.com/settings/applications/new

Redirection URL (Authorization callback URL): http://www.yoursitehere.com/users.php?oauth_login=github

== Further reading ==

* [http://OAuth.net/ OAuth homepage]

OAuth

2019-04-07T15:45:51Z

Tom: /* Facebook */

== What is OAuth? ==

The idea behind OAuth is to get rid of the need to register separately with all the websites out there that require registration before you can use them. Instead of having to keep track of all the different accounts, you can use one login on every website that supports OAuth.

To quote the [http://OAuth.net/ OAuth homepage]:

:"An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications."

OAuth is a free and open protocol. It is not owned by any corporation.

== OAuth in Geeklog ==

OAuth support in Geeklog differs slightly from the [[Remote Authentication]] support, but only in that it requires a separate login prompt.

To activate OAuth support there are several steps.

First you must go to the Configuration Admin panel:

: Configuration > Geeklog > Users and Submissions > Users > User Login Method[OAuth]

Set this option to "true". Just below this configuration option you will find the other OAuth settings. Currently Geeklog supports logging in via Facebook, LinkedIn, Twitter, Yahoo, and Google via OAuth. For each of these login methods you will find an option to enable it and two text boxes for you to enter an Application Id and Application Secret Key (see below to find out how to get an Id and Secret Key). Each of these items needs to be filled out before the login button for it will be enabled. Once you have filled out the required information remember to then save the configuration changes.

Other requirements needed to enable Geeklogs OAuth Login process is you must have the PHP extension OpenSSL loaded on your web server.

The Geeklog User Submission Queue must also be set to false in the Geeklog Configuration. Currently a new remote user cannot be added to the submission queue for approval later on.

When you log out, you will see one or more new login buttons in your site's User Functions block, below the normal login options:

[[Image:OAuth-login.png|border]]

The first time any user clicks on one of the OAuth login buttons they will be redirected to the website offering the OAuth login (Facebook, LinkedIn or Twitter). Here (if they are not currently logged into the website) they will be asked to login. Once logined they will then be asked if they wish to give permission to your Geeklog website to access some of your personal information. If the user approves the request they will then be redirected back to the Geeklog website which will then use the information to create a Geeklog user account and log them into the Geeklog website. If the user does not approve the request for information they will still be redirected back to the website but no Geeklog user account will be created.

The next time the user logs into your Geeklog website using the same OAuth login method Geeklog will check with the website providing the OAuth login to see if you are logged in the site. If not the user will be redirected to the site to login. Once they have the site will the redirect back to your Geeklog website.

When Geeklog uses OAuth to login it's users, it will never see your OAuth password - it will only get an "okay" back from the OAuth provider if you authenticated successfully.

Once a user has logged in via OAuth, they are just like any other Geeklog user. They can be added to groups, change their profile, do whatever else you allow your users to do on your site. And yes, OAuth users can also be banned.

Users that log in through OAuth are automatically added to the "Remote Users" group.

=== Limitations ===

* Currently, OAuth 1.0, 1.0a and 2.0 is supported (depends on what the OAuth provider supports).

== OAuth Login Methods ==

General review...

=== Facebook ===

Please note:
* To use Facebook Login your website must use SSL.
* Use Strict Mode for Redirect URIs on the Facebook Web App defaults to Strict and cannot be changed for new login apps created in the Facebook developer portal. This means you must specify the exact Valid OAuth Redirect URIs used by Geeklog. For example: https://www.yoursitehere.com/users.php?oauth_login=facebook
* You may need to also submit the Login for Facebook review before location / user photo can be retrieved. You have to include a screencast showing how you login and use the Facebook data.

Access Facebook 'Create an Application' page, and input form.

Please go to Facebook Apps page https://developers.facebook.com/apps

=== LinkedIn ===

Access LinkedIn 'List of Applications' page, and click 'Add New Application'.<br>
https://www.linkedin.com/secure/developer

=== Twitter ===

Access 'Applications Using Twitter' page and click 'Register a new application'.<br>
https://dev.twitter.com/apps/new<br><br>
Application Type: Select 'Browser'<br>
Callback URL: Input URL same as Website<br>
Default Access type: Select 'Read & Write'<br>
Use Twitter for login: Check<br>
Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=twitter

=== Microsoft Live ===

Allows users to login with their Hotmail, Live or Outlook email accounts
Please go to Microsoft Live Connect Developer Center page https://manage.dev.live.com/AddApplication.aspx

=== Google ===

Note: Google will shutdown Google+ on April 2, 2019. As of Geeklog v2.2.1 this OAuth login method will be removed on upgrade and all current user accounts that are setup to use Google+ will be converted to a regular Geeklog user account.

Google APIs console page http://code.google.com/apis/console in the API access tab

Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=google

=== Yahoo ===

Yahoo Apps page https://developer.apps.yahoo.com/wsregapp/

=== GitHub ===

GitHub Developer page https://developer.github.com/v3/oauth/

Create a new GitHub Application: https://github.com/settings/applications/new

Redirection URL (Authorization callback URL): http://www.yoursitehere.com/users.php?oauth_login=github

== Further reading ==

* [http://OAuth.net/ OAuth homepage]

OAuth

2019-04-07T15:44:57Z

Tom: /* Facebook */

== What is OAuth? ==

The idea behind OAuth is to get rid of the need to register separately with all the websites out there that require registration before you can use them. Instead of having to keep track of all the different accounts, you can use one login on every website that supports OAuth.

To quote the [http://OAuth.net/ OAuth homepage]:

:"An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications."

OAuth is a free and open protocol. It is not owned by any corporation.

== OAuth in Geeklog ==

OAuth support in Geeklog differs slightly from the [[Remote Authentication]] support, but only in that it requires a separate login prompt.

To activate OAuth support there are several steps.

First you must go to the Configuration Admin panel:

: Configuration > Geeklog > Users and Submissions > Users > User Login Method[OAuth]

Set this option to "true". Just below this configuration option you will find the other OAuth settings. Currently Geeklog supports logging in via Facebook, LinkedIn, Twitter, Yahoo, and Google via OAuth. For each of these login methods you will find an option to enable it and two text boxes for you to enter an Application Id and Application Secret Key (see below to find out how to get an Id and Secret Key). Each of these items needs to be filled out before the login button for it will be enabled. Once you have filled out the required information remember to then save the configuration changes.

Other requirements needed to enable Geeklogs OAuth Login process is you must have the PHP extension OpenSSL loaded on your web server.

The Geeklog User Submission Queue must also be set to false in the Geeklog Configuration. Currently a new remote user cannot be added to the submission queue for approval later on.

When you log out, you will see one or more new login buttons in your site's User Functions block, below the normal login options:

[[Image:OAuth-login.png|border]]

The first time any user clicks on one of the OAuth login buttons they will be redirected to the website offering the OAuth login (Facebook, LinkedIn or Twitter). Here (if they are not currently logged into the website) they will be asked to login. Once logined they will then be asked if they wish to give permission to your Geeklog website to access some of your personal information. If the user approves the request they will then be redirected back to the Geeklog website which will then use the information to create a Geeklog user account and log them into the Geeklog website. If the user does not approve the request for information they will still be redirected back to the website but no Geeklog user account will be created.

The next time the user logs into your Geeklog website using the same OAuth login method Geeklog will check with the website providing the OAuth login to see if you are logged in the site. If not the user will be redirected to the site to login. Once they have the site will the redirect back to your Geeklog website.

When Geeklog uses OAuth to login it's users, it will never see your OAuth password - it will only get an "okay" back from the OAuth provider if you authenticated successfully.

Once a user has logged in via OAuth, they are just like any other Geeklog user. They can be added to groups, change their profile, do whatever else you allow your users to do on your site. And yes, OAuth users can also be banned.

Users that log in through OAuth are automatically added to the "Remote Users" group.

=== Limitations ===

* Currently, OAuth 1.0, 1.0a and 2.0 is supported (depends on what the OAuth provider supports).

== OAuth Login Methods ==

General review...

=== Facebook ===

Please note:
- To use Facebook Login your website must use SSL.
- Use Strict Mode for Redirect URIs on the Facebook Web App defaults to Strict and cannot be changed for new login apps created in the Facebook developer portal. This means you must specify the exact Valid OAuth Redirect URIs used by Geeklog. For example: https://www.yoursitehere.com/users.php?oauth_login=facebook
- You may need to also submit the Login for Facebook review before location / user photo can be retrieved. You have to include a screencast showing how you login and use the Facebook data.

Access Facebook 'Create an Application' page, and input form.

Please go to Facebook Apps page https://developers.facebook.com/apps

=== LinkedIn ===

Access LinkedIn 'List of Applications' page, and click 'Add New Application'.<br>
https://www.linkedin.com/secure/developer

=== Twitter ===

Access 'Applications Using Twitter' page and click 'Register a new application'.<br>
https://dev.twitter.com/apps/new<br><br>
Application Type: Select 'Browser'<br>
Callback URL: Input URL same as Website<br>
Default Access type: Select 'Read & Write'<br>
Use Twitter for login: Check<br>
Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=twitter

=== Microsoft Live ===

Allows users to login with their Hotmail, Live or Outlook email accounts
Please go to Microsoft Live Connect Developer Center page https://manage.dev.live.com/AddApplication.aspx

=== Google ===

Note: Google will shutdown Google+ on April 2, 2019. As of Geeklog v2.2.1 this OAuth login method will be removed on upgrade and all current user accounts that are setup to use Google+ will be converted to a regular Geeklog user account.

Google APIs console page http://code.google.com/apis/console in the API access tab

Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=google

=== Yahoo ===

Yahoo Apps page https://developer.apps.yahoo.com/wsregapp/

=== GitHub ===

GitHub Developer page https://developer.github.com/v3/oauth/

Create a new GitHub Application: https://github.com/settings/applications/new

Redirection URL (Authorization callback URL): http://www.yoursitehere.com/users.php?oauth_login=github

== Further reading ==

* [http://OAuth.net/ OAuth homepage]

OAuth

2019-04-06T16:58:26Z

Tom: /* Facebook */

== What is OAuth? ==

The idea behind OAuth is to get rid of the need to register separately with all the websites out there that require registration before you can use them. Instead of having to keep track of all the different accounts, you can use one login on every website that supports OAuth.

To quote the [http://OAuth.net/ OAuth homepage]:

:"An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications."

OAuth is a free and open protocol. It is not owned by any corporation.

== OAuth in Geeklog ==

OAuth support in Geeklog differs slightly from the [[Remote Authentication]] support, but only in that it requires a separate login prompt.

To activate OAuth support there are several steps.

First you must go to the Configuration Admin panel:

: Configuration > Geeklog > Users and Submissions > Users > User Login Method[OAuth]

Set this option to "true". Just below this configuration option you will find the other OAuth settings. Currently Geeklog supports logging in via Facebook, LinkedIn, Twitter, Yahoo, and Google via OAuth. For each of these login methods you will find an option to enable it and two text boxes for you to enter an Application Id and Application Secret Key (see below to find out how to get an Id and Secret Key). Each of these items needs to be filled out before the login button for it will be enabled. Once you have filled out the required information remember to then save the configuration changes.

Other requirements needed to enable Geeklogs OAuth Login process is you must have the PHP extension OpenSSL loaded on your web server.

The Geeklog User Submission Queue must also be set to false in the Geeklog Configuration. Currently a new remote user cannot be added to the submission queue for approval later on.

When you log out, you will see one or more new login buttons in your site's User Functions block, below the normal login options:

[[Image:OAuth-login.png|border]]

The first time any user clicks on one of the OAuth login buttons they will be redirected to the website offering the OAuth login (Facebook, LinkedIn or Twitter). Here (if they are not currently logged into the website) they will be asked to login. Once logined they will then be asked if they wish to give permission to your Geeklog website to access some of your personal information. If the user approves the request they will then be redirected back to the Geeklog website which will then use the information to create a Geeklog user account and log them into the Geeklog website. If the user does not approve the request for information they will still be redirected back to the website but no Geeklog user account will be created.

The next time the user logs into your Geeklog website using the same OAuth login method Geeklog will check with the website providing the OAuth login to see if you are logged in the site. If not the user will be redirected to the site to login. Once they have the site will the redirect back to your Geeklog website.

When Geeklog uses OAuth to login it's users, it will never see your OAuth password - it will only get an "okay" back from the OAuth provider if you authenticated successfully.

Once a user has logged in via OAuth, they are just like any other Geeklog user. They can be added to groups, change their profile, do whatever else you allow your users to do on your site. And yes, OAuth users can also be banned.

Users that log in through OAuth are automatically added to the "Remote Users" group.

=== Limitations ===

* Currently, OAuth 1.0, 1.0a and 2.0 is supported (depends on what the OAuth provider supports).

== OAuth Login Methods ==

General review...

=== Facebook ===

1. To use Facebook Login your website must use SSL.

2. Use Strict Mode for Redirect URIs on the Facebook Web App defaults to Strict and cannot be changed for new login apps created in the Facebook developer portal. This means you must specify the exact Valid OAuth Redirect URIs used by Geeklog. For example: https://www.yoursitehere.com/users.php?oauth_login=facebook

3. You will need to submit the Login for Facebook review before location / user photo can be retrieved. You have to include a screencast showing how you login and use the Facebook data.

Access Facebook 'Create an Application' page, and input form.

Please go to Facebook Apps page https://developers.facebook.com/apps

=== LinkedIn ===

Access LinkedIn 'List of Applications' page, and click 'Add New Application'.<br>
https://www.linkedin.com/secure/developer

=== Twitter ===

Access 'Applications Using Twitter' page and click 'Register a new application'.<br>
https://dev.twitter.com/apps/new<br><br>
Application Type: Select 'Browser'<br>
Callback URL: Input URL same as Website<br>
Default Access type: Select 'Read & Write'<br>
Use Twitter for login: Check<br>
Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=twitter

=== Microsoft Live ===

Allows users to login with their Hotmail, Live or Outlook email accounts
Please go to Microsoft Live Connect Developer Center page https://manage.dev.live.com/AddApplication.aspx

=== Google ===

Note: Google will shutdown Google+ on April 2, 2019. As of Geeklog v2.2.1 this OAuth login method will be removed on upgrade and all current user accounts that are setup to use Google+ will be converted to a regular Geeklog user account.

Google APIs console page http://code.google.com/apis/console in the API access tab

Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=google

=== Yahoo ===

Yahoo Apps page https://developer.apps.yahoo.com/wsregapp/

=== GitHub ===

GitHub Developer page https://developer.github.com/v3/oauth/

Create a new GitHub Application: https://github.com/settings/applications/new

Redirection URL (Authorization callback URL): http://www.yoursitehere.com/users.php?oauth_login=github

== Further reading ==

* [http://OAuth.net/ OAuth homepage]

OAuth

2019-03-11T19:15:37Z

Tom: /* Google */

== What is OAuth? ==

The idea behind OAuth is to get rid of the need to register separately with all the websites out there that require registration before you can use them. Instead of having to keep track of all the different accounts, you can use one login on every website that supports OAuth.

To quote the [http://OAuth.net/ OAuth homepage]:

:"An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications."

OAuth is a free and open protocol. It is not owned by any corporation.

== OAuth in Geeklog ==

OAuth support in Geeklog differs slightly from the [[Remote Authentication]] support, but only in that it requires a separate login prompt.

To activate OAuth support there are several steps.

First you must go to the Configuration Admin panel:

: Configuration > Geeklog > Users and Submissions > Users > User Login Method[OAuth]

Set this option to "true". Just below this configuration option you will find the other OAuth settings. Currently Geeklog supports logging in via Facebook, LinkedIn, Twitter, Yahoo, and Google via OAuth. For each of these login methods you will find an option to enable it and two text boxes for you to enter an Application Id and Application Secret Key (see below to find out how to get an Id and Secret Key). Each of these items needs to be filled out before the login button for it will be enabled. Once you have filled out the required information remember to then save the configuration changes.

Other requirements needed to enable Geeklogs OAuth Login process is you must have the PHP extension OpenSSL loaded on your web server.

The Geeklog User Submission Queue must also be set to false in the Geeklog Configuration. Currently a new remote user cannot be added to the submission queue for approval later on.

When you log out, you will see one or more new login buttons in your site's User Functions block, below the normal login options:

[[Image:OAuth-login.png|border]]

The first time any user clicks on one of the OAuth login buttons they will be redirected to the website offering the OAuth login (Facebook, LinkedIn or Twitter). Here (if they are not currently logged into the website) they will be asked to login. Once logined they will then be asked if they wish to give permission to your Geeklog website to access some of your personal information. If the user approves the request they will then be redirected back to the Geeklog website which will then use the information to create a Geeklog user account and log them into the Geeklog website. If the user does not approve the request for information they will still be redirected back to the website but no Geeklog user account will be created.

The next time the user logs into your Geeklog website using the same OAuth login method Geeklog will check with the website providing the OAuth login to see if you are logged in the site. If not the user will be redirected to the site to login. Once they have the site will the redirect back to your Geeklog website.

When Geeklog uses OAuth to login it's users, it will never see your OAuth password - it will only get an "okay" back from the OAuth provider if you authenticated successfully.

Once a user has logged in via OAuth, they are just like any other Geeklog user. They can be added to groups, change their profile, do whatever else you allow your users to do on your site. And yes, OAuth users can also be banned.

Users that log in through OAuth are automatically added to the "Remote Users" group.

=== Limitations ===

* Currently, OAuth 1.0, 1.0a and 2.0 is supported (depends on what the OAuth provider supports).

== OAuth Login Methods ==

General review...

=== Facebook ===

Access Facebook 'Create an Application' page, and input form.<br>
Please go to Facebook Apps page https://developers.facebook.com/apps

=== LinkedIn ===

Access LinkedIn 'List of Applications' page, and click 'Add New Application'.<br>
https://www.linkedin.com/secure/developer

=== Twitter ===

Access 'Applications Using Twitter' page and click 'Register a new application'.<br>
https://dev.twitter.com/apps/new<br><br>
Application Type: Select 'Browser'<br>
Callback URL: Input URL same as Website<br>
Default Access type: Select 'Read & Write'<br>
Use Twitter for login: Check<br>
Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=twitter

=== Microsoft Live ===

Allows users to login with their Hotmail, Live or Outlook email accounts
Please go to Microsoft Live Connect Developer Center page https://manage.dev.live.com/AddApplication.aspx

=== Google ===

Note: Google will shutdown Google+ on April 2, 2019. As of Geeklog v2.2.1 this OAuth login method will be removed on upgrade and all current user accounts that are setup to use Google+ will be converted to a regular Geeklog user account.

Google APIs console page http://code.google.com/apis/console in the API access tab

Redirection URL: http://www.yoursitehere.com/users.php?oauth_login=google

=== Yahoo ===

Yahoo Apps page https://developer.apps.yahoo.com/wsregapp/

=== GitHub ===

GitHub Developer page https://developer.github.com/v3/oauth/

Create a new GitHub Application: https://github.com/settings/applications/new

Redirection URL (Authorization callback URL): http://www.yoursitehere.com/users.php?oauth_login=github

== Further reading ==

* [http://OAuth.net/ OAuth homepage]

Caching Template Library

2018-11-30T14:07:21Z

Tom: /* Example 4 */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :h Call strip_tags on the variable before output. (as of Geeklog v2.2.1)
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments. If you want these comments to appear in the cache and the HTML source of the page you can in the Geeklog Configuration enable "Template Comments in Output". See example 3 to see how to use a comment.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
In this example, we set the array myVar and then print it out using a while loop:
<pre>
{!!set myVar array('a', 'b') !!}
{!!set myCount 0 !!}

{!!while !empty(array_slice({myVar}, {myCount}, 1)) !!}
{!!set myVar1 array_slice({myVar}, {myCount}, 1)[0] !!}
myVar: {myVar1}<br>
{!inc myCount}
{!endwhile!}
</pre>
The output then looks like this:
<pre>
myVar: a
myVar: b
</pre>

==== Example 5 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Caching Template Library

2018-11-30T14:06:52Z

Tom: /* Example 4 */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :h Call strip_tags on the variable before output. (as of Geeklog v2.2.1)
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments. If you want these comments to appear in the cache and the HTML source of the page you can in the Geeklog Configuration enable "Template Comments in Output". See example 3 to see how to use a comment.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
In this example, we set the array myVar and then print it out using a while loop:
<pre>
{!!set myVar array('a', 'b') !!}
{!!set myCount 0 !!}

{!!while !empty(array_slice({myVar}, {myCount}, 1)) !!}
{!!set myVar1 array_slice({myVar}, {myCount}, 1)[0] !!}
myVar: {myVar1}<br>

{!inc myCount}
{!endwhile!}
The output then looks like this:
<pre>
myVar: a
myVar: b
</pre>

==== Example 5 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Caching Template Library

2018-11-30T14:06:30Z

Tom: /* Comments */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :h Call strip_tags on the variable before output. (as of Geeklog v2.2.1)
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments. If you want these comments to appear in the cache and the HTML source of the page you can in the Geeklog Configuration enable "Template Comments in Output". See example 3 to see how to use a comment.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
In this example, we set the array myVar and then print it out using a while loop:
<pre>
{!!set myVar array('a', 'b') !!}
{!!set myCount 0 !!}
{!!while !empty(array_slice({myVar}, {myCount}, 1)) !!}
{!!set myVar1 array_slice({myVar}, {myCount}, 1)[0] !!}
myVar: {myVar1}<br>
{!inc myCount}
{!endwhile!}
The output then looks like this:
<pre>
myVar: a
myVar: b
</pre>

==== Example 5 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Caching Template Library

2018-11-30T14:03:17Z

Tom: /* Example 4 */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :h Call strip_tags on the variable before output. (as of Geeklog v2.2.1)
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
In this example, we set the array myVar and then print it out using a while loop:
<pre>
{!!set myVar array('a', 'b') !!}
{!!set myCount 0 !!}
{!!while !empty(array_slice({myVar}, {myCount}, 1)) !!}
{!!set myVar1 array_slice({myVar}, {myCount}, 1)[0] !!}
myVar: {myVar1}<br>
{!inc myCount}
{!endwhile!}
The output then looks like this:
<pre>
myVar: a
myVar: b
</pre>

==== Example 5 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Caching Template Library

2018-11-30T14:02:23Z

Tom: /* Example 4 */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :h Call strip_tags on the variable before output. (as of Geeklog v2.2.1)
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
In this example, we set the array myVar and then print it out using a while loop:
<pre>
{!!set myVar array('a', 'b') !!}
{!!set myCount 0 !!}
{!!while !empty(array_slice({myVar}, {myCount}, 1)) !!}
{!!set myVar1 array_slice({myVar}, {myCount}, 1)[0] !!}
myVar: {myVar1}<br>
{!inc myCount}
{!endwhile!}
The output then looks like this:
<pre>
myVar: a
myVar: b
</pre>

==== Example 5 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Caching Template Library

2018-11-30T14:02:11Z

Tom: /* Example 3 */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :h Call strip_tags on the variable before output. (as of Geeklog v2.2.1)
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
In this example, we set the array myVar and then print it out using a while loop:
<pre>
{!!set myVar array('a', 'b') !!}
{!!set myCount 0 !!}
{!!while !empty(array_slice({myVar}, {myCount}, 1)) !!}
{!!set myVar1 array_slice({myVar}, {myCount}, 1)[0] !!}
myVar: {myVar1}<br>
{!inc myCount}
{!endwhile!}
The output then looks like this:
<pre>
myVar: a
myVar: b
</pre>

==== Example 4 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Static Pages Plugin

2018-11-26T21:51:16Z

Tom: /* Accessing Geeklog Variables and Logic Processing */

== What is it? ==

The Static Pages plugin was originally aimed at creating pages with static content (as opposed to the dynamic pages created by Geeklog) - hence the name. Pages like an "about us" page, a mission statement, etc. would come to mind.

Since then, people have used the static pages for all kinds of things and with the inclusion of PHP into static pages, even the original name isn't quite right any more ...
History

The plugin was originally written by Tony Bibbs and is included with Geeklog as a pre-installed plugin since Geeklog 1.3.5. An extended version of the plugin was started by Phill Gillespie and later supported by Tom Willet. The extended version was the first to allow the use of PHP in static pages and also supported proper Geeklog permissions.

With Geeklog 1.3.8 and Static Pages 1.3, these two versions were merged again. Static Pages 1.3 also introduced some new features that were not included in either of its predecessors.
Features

* supports use of PHP
* editable page ID to make more readable URLs
* Static pages can be displayed on Geeklog's index and topic pages and can even replace it entirely ("splash screen")
* "cloning" of existing pages
* Makes use of Geeklog's URL rewrite feature
* Supports autolinks and provides a [staticpage:] autotag
* proper support for Geeklog permissions

== Use of PHP ==

=== Activating PHP ===

'''Important:''' For security reasons, the use of PHP in static pages is disabled by default.

To enable it, you will have to grant the 'staticpages.PHP' permission to the "Static Page Admin" group. To do this, log in as the Admin and from the Admin's Only block, select "Groups". Find the "Static Page Admin" group and edit it by clicking on the name of the group. At the bottom of the page, you will find a list of "Rights" (permissions) that can be granted to all members of this group. Note that 'staticpages.delete' and 'staticpages.edit' are checked, while 'staticpages.PHP' is not checked. To allow members of the Static Page Admin group to use PHP in static pages, you will have to check the 'staticpages.PHP' checkbox and save your changes.

In addition to the 'staticpages.PHP' permission discussed above, there is also a global flag, $_SP_CONF['allow_php'], that can be used to disable the use of PHP in static pages entirely. When set to 0, it will override the 'staticpages.PHP' permission and disable all use of PHP in static pages. The flag is located in the static pages' config.php file in the plugins/staticpages directory.
Usage

''The use of PHP in static pages may result in security issues if not used properly. Use this feature with care!''

The use of PHP has to be enabled for each individual static page. Below the content edit field, you will find a drop-down menu with the following options:

* do not execute PHP
Obivously, when you select this option, any PHP code in the static page will not be executed but will instead be printed out as-is.
* execute PHP (return)
If you select this option, PHP code in static pages will be executed. The 'return' indicates that the code should return any output it generates, using a PHP return statement, instead of printing it out directly. This is the PHP option as introduced with the Static Pages plugin 1.3.
* execute PHP
Again, this option will enable execution of PHP. Only this time, the PHP code can actually use echo and print statements without having the output interfere with the page layout.

Please note that when embedding PHP code in a static page, your code should not be enclosed in the PHP <?php and ?> tags. Instead, it is assumed that the static page contains the PHP code that would normally go between those two tags.

When selecting the second of the above PHP execution options ("execute PHP") you can, however, switch back and forth between PHP and plain HTML like this:

<pre>echo "Hello"; ?>, <b>world</b>, <?php echo "how are you?";</pre>

The above example would print out "Hello, world, how are you?".

== Page ID ==

When creating a new static page, it will be assigned a page ID automatically. This ID consists of the date and time and up to three random digits. When you anticipate that the URL of this page may be used a lot, e.g. quoted in emails, it may make sense to use a more readable ID for the page.

The static pages editor will let you change the page ID. For example, you may want to rename the ID for your "about" page from "20030313100131123" to "about", thus creating a URL like

http://www.example.com/staticpages/index.php?page=about

which looks much nicer when quoted (and is easier to remember). You could further improve this by making use of Geeklog's URL rewrite feature.

Please note that you should only use letters and digits for the page ID. Avoid national special characters, most punctuation characters ('-' and '.' should be okay, though) and spaces. The static page editor will catch some illegal characters but not all of them ...

== Using Static Pages on the index page ==

Geeklog 1.3.8 introduced a new concept for use by plugins, called Center Blocks. Basically, this means that any plugin can place blocks in the center area of a Geeklog site, i.e. among the stories.

When you check the "Centerblock" option for a static page, you can use the "Position" and "Topic" drop-downs to chose where this static page will be displayed. For "Position", the options are "Top Of Page", "After Featured Story", "Bottom Of Page" (which should be self-explanatory) and "Entire Page". That last option, "Entire Page", will tell Geeklog that this static page will replace the entire index page - it will not display any stories, but only the contents of this static page. This is useful e.g. for "splash" screens or Welcome pages.

'''Tip:''' When using a static page as a "splash" screen, you may need a link that takes your visitors to the normal index page, i.e. the list of current stories. To do this, create a link to index.php?display=all

The second drop-down, "Topic", lets you restrict the display of a static page to only a certain topic, the homepage only, or all pages (i.e. all topic pages and the homepage). This is the same as the options you have for blocks.

'''Tip:''' You can combine these options with the permission settings. This will let you, for example, create a "welcome" page that is only displayed to anonymous users.

== Sorting ==

'''Centerblocks:''' When you have more than one static page that would appear in the same section of the center area (e.g. two static pages that would be displayed at the top of the index page), you can chose the order in which they appear by setting the $_SP_CONF['sort_by'] variable in the plugin's config.php file to one of id (sort by page id), date (sort by last changed date), or title (sort by page title). The default is to sort by page id.

'''Menu entries:''' It's also possible to sort the static pages that are displayed in the site's menu (if you're using a theme that uses the {plg_menu_elements} variables in its header.thtml). Set the $_SP_CONF['sort_menu_by'] variable (again, in the plugin's config.php file) to one of id (sort by page id), date (sort by last changed date), label (sort by the menu label), or title (sort by page title).

== Wrapping Static Pages in a block ==

You can chose to have a static page wrapped in a Geeklog block by checking the "wrap static page in a block" option in the static pages editor. If selected, the page's title will be used as the block title.

The plugin's config.php file also has a flag, $_SP_CONF['in_block'], which is used as the default for this option.

== Cloning Static Pages ==

When you have a lot of similar static pages you may want to make a copy of an existing page and then edit that copy. This can easily be done by clicking on the [C] from the list of static pages. Doing so will create a copy of that page with a new page ID.

== URL rewriting ==

Please note that this feature is considered experimental and is known not to work with IIS.

Geeklog supports a form of URL rewriting, i.e. change the look of URLs such that they are more search engine friendly. For example, instead of

http://www.example.com/staticpages/index.php?page=20030313100131123

the URL could look like this

http://www.example.com/staticpages/index.php/20030313100131123

Some search engines are known not to index pages when the URL includes characters like '?' and '='. You could further improve the chances of this page being indexed by replacing the numeric page ID with a word or expression (preferrably something that corresponds to the page's content), e.g.

http://www.example.com/staticpages/index.php/about

To make use of URL rewriting, you will need to enable it in Geeklog's config.php file by setting

$_CONF['url_rewrite'] = true;

== Template Static Pages ==

As of Geeklog 1.7.1, you now have the ability for a Static Page to use another Static Page as a template. What this allows you to do is create one template page and then have it be used by one or more other Static Pages as a base. This feature is ideal for people who have a number of similar formatted Static Pages. For example if you have a bunch of product pages that need to look the same but they have different titles, product image, and product description. A Static Page Template would be ideal here. You can just supply the text in one page and have it use the other for the formatting. If you ever need to change the formatting of these pages at a later date all you need to do is just update the template Static Page. To set this functionality up, you need to do a couple of things.

The first thing you must do is create a template Static Page. To do this you first need to create a Static Page. Once in the editor you need to give the page a Title and an ID. You then need to check the "Template" check box option. Once this is done, you can enter your HTML code in the content section. Where ever you have a spot where you want data from another Static Page to go, you can put a template variable there. This template variable can be any unique text you want. An example of this would be something like:

<pre><p>Hello World!</p> <p>{tpl_var1}</p> <p>Bye World!</p> <p>{tpl_var2}</p></pre>

Once you have assigned a static page as a template, most features in the editor are not available to you to use. This includes the Menu options, Page Format, Comments, Meta Information, Centerblock and the PHP option. Also by themselves template Static Pages will not appear in search results, Site Statistics or in the What's New Block.

The second thing you need to do now is, create a page that will use your new template Static Page. To do this, create a new Static Page. Once you are in the Static Page editor you then need to select your new template from the "Use Template" option. Once selected, you can then enter your template variable information into the content section of the editor. This information is XML and needs to be formatted properly and include the correct attributes and tags like the sample below:

NOTE: These examples have been updated for use with Geeklog 2.1.3. As of Geeklog 2.1.3 curly brackets are automatically used to surround variable names in the templates. With Geeklog 2.1.2 and lower the variable name required the use of {curly brackets}. So Geeklog v2.1.2 and lower the staticpage which uses a template must have variable names like (with {curley_brackets}):

<pre>
<page>
<variable name="{tpl_var1}">
<data>Test Variable Data 1</data>
</variable>
<variable name="{tpl_var2}">
<data>Test Variable Data 2</data>
</variable>
<variable name="{tpl_var3}">
<data>True</data>
</variable>
</page>
</pre>

Geeklog v2.1.3 and later the curly brackets are not needed around the variable names. For example:

<pre>
<page>
<variable name="tpl_var1">
<data>Test Variable Data 1</data>
</variable>
<variable name="tpl_var2">
<data>Test Variable Data 2</data>
</variable>
<variable name="tpl_var3">
<data>True</data>
</variable>
</page>
</pre>

You should have the same number of variables here, as in your template Static Page. Each of the name attributes of the variable tag should be one of the template variables from the template Static Page. Any information you want to appear would go between the data tags. If this information contains other tags (like HTML) then you need to wrap it in CDATA so it will not be parsed. Here is an example of how to use CDATA:

<pre>
<variable name="tpl_var1">
<data><![CDATA[
<p>Test Variable Data 1</p>
]]></data>
</variable>
</pre>

Most functions of the Static Page editor are available to this page with the exception of allowing PHP to be used and Post Mode. Your "Post Mode" option should be set as "HTML Formatted". If there is an error in your XML this could throw a PHP error when you attempt to view the page. You also need to make sure that this page and the template Static Page have the same permissions. If the user can view this page and not the template Static Page assigned to it then the page will not display properly.

=== Accessing Geeklog Variables and Logic Processing ===

As of Geeklog v2.1.3 and Static Page Plugin v1.6.9 the staticpage template feature has improved. Instead of the Staticpage plugin itself replacing template variables and autotags it has now handed over this funcitionaly for the most part to the [[Caching_Template_Library |Geeklog Caching Template Class]]. This means that template Static page can now use many features of the template class including access to [[Caching_Template_Library#TEMPLATE_OPTIONS |default variables]] like {anonymous_user} and {device_mobile}. Plus [[Caching_Template_Library#Automatic_Language_File_Variables |Lanaguage File Variables]]. It also means that [[Caching_Template_Library#Logic_Processing_2 |Logic Processing]] can now be used! This means you can include If and Else statements, Loops, and also include PHP code in Staticpage Template Pages. So for example in a template Staticpage you can now display content depending on a variable like {device_mobile) or another variable that has been defined in your Staticpage (like {tpl_var3} from the sample above).

As of Geeklog 2.2.1 the Static Pages plugin also adds its own addition default template variables. There are 3: the static page title (sp_title}, created date (sp_created), and last modified date {sp_modified}. All dates returned by these template variables are ISO 8601 dates.

<pre>
<p>Hello World!</p> <p>{tpl_var1}</p> <p>Bye World!</p> <p>{tpl_var2}</p>

{!if device_mobile}
<p>The paragraph will only display on mobile devices.</p>
{!else}
<p>The paragraph will only display on desktop and laptops.</p>
{!endif}

{!if tpl_var3}
<p>test_variable contains a string.</p>
{!else}
<p>test_variable contains a 0, is empty, or does not exist.</p>
{!endif}

<p>This is a test to access a language variable: {$LANG_DB_BACKUP[database_admin]}</p>

<p>This is a test to access the Staticpage title: {sp_title}</p>
</pre>

== Deleting pages with their owner ==

As all objects in Geeklog, static pages have an owner (the user that created the static page). When that user's account is deleted for some reason, any static pages owned by that user can either be deleted as well or they can be assigned to another user in Geeklog's Root group. The config.php file for the Static Pages plugin has the following option:

$_SP_CONF['delete_pages'] = 0;

If set to 0 (which is the default), static pages will not be deleted with their owner, but assigned to a member of the Root group instead (the user with the lowest user ID, most likely the Admin). If you change this to 1, static pages will be deleted when their owner's account is deleted.

[[category:Plugins]]

Static Pages Plugin

2018-11-26T21:49:57Z

Tom: /* Accessing Geeklog Variables and Logic Processing */

== What is it? ==

The Static Pages plugin was originally aimed at creating pages with static content (as opposed to the dynamic pages created by Geeklog) - hence the name. Pages like an "about us" page, a mission statement, etc. would come to mind.

Since then, people have used the static pages for all kinds of things and with the inclusion of PHP into static pages, even the original name isn't quite right any more ...
History

The plugin was originally written by Tony Bibbs and is included with Geeklog as a pre-installed plugin since Geeklog 1.3.5. An extended version of the plugin was started by Phill Gillespie and later supported by Tom Willet. The extended version was the first to allow the use of PHP in static pages and also supported proper Geeklog permissions.

With Geeklog 1.3.8 and Static Pages 1.3, these two versions were merged again. Static Pages 1.3 also introduced some new features that were not included in either of its predecessors.
Features

* supports use of PHP
* editable page ID to make more readable URLs
* Static pages can be displayed on Geeklog's index and topic pages and can even replace it entirely ("splash screen")
* "cloning" of existing pages
* Makes use of Geeklog's URL rewrite feature
* Supports autolinks and provides a [staticpage:] autotag
* proper support for Geeklog permissions

== Use of PHP ==

=== Activating PHP ===

'''Important:''' For security reasons, the use of PHP in static pages is disabled by default.

To enable it, you will have to grant the 'staticpages.PHP' permission to the "Static Page Admin" group. To do this, log in as the Admin and from the Admin's Only block, select "Groups". Find the "Static Page Admin" group and edit it by clicking on the name of the group. At the bottom of the page, you will find a list of "Rights" (permissions) that can be granted to all members of this group. Note that 'staticpages.delete' and 'staticpages.edit' are checked, while 'staticpages.PHP' is not checked. To allow members of the Static Page Admin group to use PHP in static pages, you will have to check the 'staticpages.PHP' checkbox and save your changes.

In addition to the 'staticpages.PHP' permission discussed above, there is also a global flag, $_SP_CONF['allow_php'], that can be used to disable the use of PHP in static pages entirely. When set to 0, it will override the 'staticpages.PHP' permission and disable all use of PHP in static pages. The flag is located in the static pages' config.php file in the plugins/staticpages directory.
Usage

''The use of PHP in static pages may result in security issues if not used properly. Use this feature with care!''

The use of PHP has to be enabled for each individual static page. Below the content edit field, you will find a drop-down menu with the following options:

* do not execute PHP
Obivously, when you select this option, any PHP code in the static page will not be executed but will instead be printed out as-is.
* execute PHP (return)
If you select this option, PHP code in static pages will be executed. The 'return' indicates that the code should return any output it generates, using a PHP return statement, instead of printing it out directly. This is the PHP option as introduced with the Static Pages plugin 1.3.
* execute PHP
Again, this option will enable execution of PHP. Only this time, the PHP code can actually use echo and print statements without having the output interfere with the page layout.

Please note that when embedding PHP code in a static page, your code should not be enclosed in the PHP <?php and ?> tags. Instead, it is assumed that the static page contains the PHP code that would normally go between those two tags.

When selecting the second of the above PHP execution options ("execute PHP") you can, however, switch back and forth between PHP and plain HTML like this:

<pre>echo "Hello"; ?>, <b>world</b>, <?php echo "how are you?";</pre>

The above example would print out "Hello, world, how are you?".

== Page ID ==

When creating a new static page, it will be assigned a page ID automatically. This ID consists of the date and time and up to three random digits. When you anticipate that the URL of this page may be used a lot, e.g. quoted in emails, it may make sense to use a more readable ID for the page.

The static pages editor will let you change the page ID. For example, you may want to rename the ID for your "about" page from "20030313100131123" to "about", thus creating a URL like

http://www.example.com/staticpages/index.php?page=about

which looks much nicer when quoted (and is easier to remember). You could further improve this by making use of Geeklog's URL rewrite feature.

Please note that you should only use letters and digits for the page ID. Avoid national special characters, most punctuation characters ('-' and '.' should be okay, though) and spaces. The static page editor will catch some illegal characters but not all of them ...

== Using Static Pages on the index page ==

Geeklog 1.3.8 introduced a new concept for use by plugins, called Center Blocks. Basically, this means that any plugin can place blocks in the center area of a Geeklog site, i.e. among the stories.

When you check the "Centerblock" option for a static page, you can use the "Position" and "Topic" drop-downs to chose where this static page will be displayed. For "Position", the options are "Top Of Page", "After Featured Story", "Bottom Of Page" (which should be self-explanatory) and "Entire Page". That last option, "Entire Page", will tell Geeklog that this static page will replace the entire index page - it will not display any stories, but only the contents of this static page. This is useful e.g. for "splash" screens or Welcome pages.

'''Tip:''' When using a static page as a "splash" screen, you may need a link that takes your visitors to the normal index page, i.e. the list of current stories. To do this, create a link to index.php?display=all

The second drop-down, "Topic", lets you restrict the display of a static page to only a certain topic, the homepage only, or all pages (i.e. all topic pages and the homepage). This is the same as the options you have for blocks.

'''Tip:''' You can combine these options with the permission settings. This will let you, for example, create a "welcome" page that is only displayed to anonymous users.

== Sorting ==

'''Centerblocks:''' When you have more than one static page that would appear in the same section of the center area (e.g. two static pages that would be displayed at the top of the index page), you can chose the order in which they appear by setting the $_SP_CONF['sort_by'] variable in the plugin's config.php file to one of id (sort by page id), date (sort by last changed date), or title (sort by page title). The default is to sort by page id.

'''Menu entries:''' It's also possible to sort the static pages that are displayed in the site's menu (if you're using a theme that uses the {plg_menu_elements} variables in its header.thtml). Set the $_SP_CONF['sort_menu_by'] variable (again, in the plugin's config.php file) to one of id (sort by page id), date (sort by last changed date), label (sort by the menu label), or title (sort by page title).

== Wrapping Static Pages in a block ==

You can chose to have a static page wrapped in a Geeklog block by checking the "wrap static page in a block" option in the static pages editor. If selected, the page's title will be used as the block title.

The plugin's config.php file also has a flag, $_SP_CONF['in_block'], which is used as the default for this option.

== Cloning Static Pages ==

When you have a lot of similar static pages you may want to make a copy of an existing page and then edit that copy. This can easily be done by clicking on the [C] from the list of static pages. Doing so will create a copy of that page with a new page ID.

== URL rewriting ==

Please note that this feature is considered experimental and is known not to work with IIS.

Geeklog supports a form of URL rewriting, i.e. change the look of URLs such that they are more search engine friendly. For example, instead of

http://www.example.com/staticpages/index.php?page=20030313100131123

the URL could look like this

http://www.example.com/staticpages/index.php/20030313100131123

Some search engines are known not to index pages when the URL includes characters like '?' and '='. You could further improve the chances of this page being indexed by replacing the numeric page ID with a word or expression (preferrably something that corresponds to the page's content), e.g.

http://www.example.com/staticpages/index.php/about

To make use of URL rewriting, you will need to enable it in Geeklog's config.php file by setting

$_CONF['url_rewrite'] = true;

== Template Static Pages ==

As of Geeklog 1.7.1, you now have the ability for a Static Page to use another Static Page as a template. What this allows you to do is create one template page and then have it be used by one or more other Static Pages as a base. This feature is ideal for people who have a number of similar formatted Static Pages. For example if you have a bunch of product pages that need to look the same but they have different titles, product image, and product description. A Static Page Template would be ideal here. You can just supply the text in one page and have it use the other for the formatting. If you ever need to change the formatting of these pages at a later date all you need to do is just update the template Static Page. To set this functionality up, you need to do a couple of things.

The first thing you must do is create a template Static Page. To do this you first need to create a Static Page. Once in the editor you need to give the page a Title and an ID. You then need to check the "Template" check box option. Once this is done, you can enter your HTML code in the content section. Where ever you have a spot where you want data from another Static Page to go, you can put a template variable there. This template variable can be any unique text you want. An example of this would be something like:

<pre><p>Hello World!</p> <p>{tpl_var1}</p> <p>Bye World!</p> <p>{tpl_var2}</p></pre>

Once you have assigned a static page as a template, most features in the editor are not available to you to use. This includes the Menu options, Page Format, Comments, Meta Information, Centerblock and the PHP option. Also by themselves template Static Pages will not appear in search results, Site Statistics or in the What's New Block.

The second thing you need to do now is, create a page that will use your new template Static Page. To do this, create a new Static Page. Once you are in the Static Page editor you then need to select your new template from the "Use Template" option. Once selected, you can then enter your template variable information into the content section of the editor. This information is XML and needs to be formatted properly and include the correct attributes and tags like the sample below:

NOTE: These examples have been updated for use with Geeklog 2.1.3. As of Geeklog 2.1.3 curly brackets are automatically used to surround variable names in the templates. With Geeklog 2.1.2 and lower the variable name required the use of {curly brackets}. So Geeklog v2.1.2 and lower the staticpage which uses a template must have variable names like (with {curley_brackets}):

<pre>
<page>
<variable name="{tpl_var1}">
<data>Test Variable Data 1</data>
</variable>
<variable name="{tpl_var2}">
<data>Test Variable Data 2</data>
</variable>
<variable name="{tpl_var3}">
<data>True</data>
</variable>
</page>
</pre>

Geeklog v2.1.3 and later the curly brackets are not needed around the variable names. For example:

<pre>
<page>
<variable name="tpl_var1">
<data>Test Variable Data 1</data>
</variable>
<variable name="tpl_var2">
<data>Test Variable Data 2</data>
</variable>
<variable name="tpl_var3">
<data>True</data>
</variable>
</page>
</pre>

You should have the same number of variables here, as in your template Static Page. Each of the name attributes of the variable tag should be one of the template variables from the template Static Page. Any information you want to appear would go between the data tags. If this information contains other tags (like HTML) then you need to wrap it in CDATA so it will not be parsed. Here is an example of how to use CDATA:

<pre>
<variable name="tpl_var1">
<data><![CDATA[
<p>Test Variable Data 1</p>
]]></data>
</variable>
</pre>

Most functions of the Static Page editor are available to this page with the exception of allowing PHP to be used and Post Mode. Your "Post Mode" option should be set as "HTML Formatted". If there is an error in your XML this could throw a PHP error when you attempt to view the page. You also need to make sure that this page and the template Static Page have the same permissions. If the user can view this page and not the template Static Page assigned to it then the page will not display properly.

=== Accessing Geeklog Variables and Logic Processing ===

As of Geeklog v2.1.3 and Static Page Plugin v1.6.9 the staticpage template feature has improved. Instead of the Staticpage plugin itself replacing template variables and autotags it has now handed over this funcitionaly for the most part to the [[Caching_Template_Library |Geeklog Caching Template Class]]. This means that template Static page can now use many features of the template class including access to [[Caching_Template_Library#TEMPLATE_OPTIONS |default variables]] like {anonymous_user} and {device_mobile}. Plus [[Caching_Template_Library#Automatic_Language_File_Variables |Lanaguage File Variables]]. It also means that [[Caching_Template_Library#Logic_Processing_2 |Logic Processing]] can now be used! This means you can include If and Else statements, Loops, and also include PHP code in Staticpage Template Pages. So for example in a template Staticpage you can now display content depending on a variable like {device_mobile) or another variable that has been defined in your Staticpage (like {tpl_var3} from the sample above). As of Geeklog 2.2.1 the Static Pages plugin also adds its own addition template variables for the static page title (sp_title}, created date (sp_created), and last modified date {sp_modified}. All dates returned by these template variables are ISO 8601 dates.

<pre>
<p>Hello World!</p> <p>{tpl_var1}</p> <p>Bye World!</p> <p>{tpl_var2}</p>

{!if device_mobile}
<p>The paragraph will only display on mobile devices.</p>
{!else}
<p>The paragraph will only display on desktop and laptops.</p>
{!endif}

{!if tpl_var3}
<p>test_variable contains a string.</p>
{!else}
<p>test_variable contains a 0, is empty, or does not exist.</p>
{!endif}

<p>This is a test to access a language variable: {$LANG_DB_BACKUP[database_admin]}</p>

<p>This is a test to access the Staticpage title: {sp_title}</p>
</pre>

== Deleting pages with their owner ==

As all objects in Geeklog, static pages have an owner (the user that created the static page). When that user's account is deleted for some reason, any static pages owned by that user can either be deleted as well or they can be assigned to another user in Geeklog's Root group. The config.php file for the Static Pages plugin has the following option:

$_SP_CONF['delete_pages'] = 0;

If set to 0 (which is the default), static pages will not be deleted with their owner, but assigned to a member of the Root group instead (the user with the lowest user ID, most likely the Admin). If you change this to 1, static pages will be deleted when their owner's account is deleted.

[[category:Plugins]]

Caching Template Library

2018-11-26T21:46:09Z

Tom: /* Replacement Variable Manipulation Modifiers */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :h Call strip_tags on the variable before output. (as of Geeklog v2.2.1)
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Caching Template Library

2018-11-26T21:13:21Z

Tom: /* Replacement Variable Manipulation Modifiers */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :h Call strip_tags on the variable before output.
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Caching Template Library

2018-08-15T17:16:46Z

Tom: /* TEMPLATE_OPTIONS */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL() (Note: This returns the current URL as PHP sees it on the server. If the server is setup to rewrite the URL then it may be different from the actual URL)

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Caching Template Library

2018-08-15T17:15:10Z

Tom: /* TEMPLATE_OPTIONS */

== Introduction ==

The Caching Template Library (CTL) is the template engine in Geeklog. A template engine facilitates a manageable way to separate application logic and content from its presentation. This allows the programmer to focus specifically on the application and the template designer to focus on the presentation. It also allows site administrators to easily manipulate the look and feel of their site without having to know the application or become a programmer.

The benefits of the Caching Template Library are that it adds the following features to Geeklog. These features benefit both the site administrator and the plugin developer.

* Compiles templates to PHP code for enhanced page load speeds.
* Adds logic processing to the templates.
* Ability to specify multiple locations to search for templates.

== Compiles Templates to PHP code ==

One of the unique aspects about the Caching Template Library is template compiling. This means the Caching Template Library reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is no costly template file parsing for each request. Each template can take full advantage of the PHP compiler and cache solutions such as eAccelerator, ionCube mmCache or Zend Accelerator to name a few. Some anecdotal experience with performance testing can be found in the forum.

== Logic Processing ==

One design goal of the Caching Template Library is the separation of application logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as checking if a specific variable is set and adjusting the display appropriately is a good example of presentation logic. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only.

== Not just for Templates ==

As of Geeklog v2.1.3 you can set a View instead of a template file when using the Caching Template Library. A View is basically a large string of text that can be compiled by the Caching Template Library. The text string can there for contain the same type of logic processing, template variables and autotags as a normal template file. With the view, developers can even assign their own template variables or access the default ones automatically like site_url, anonymous_user, and device_mobile. The first plugin to support this is the Static Pages Plugin v1.6.9. For more information on how this works see [[Static_Pages_Plugin#Accessing_Geeklog_Variables_and_Logic_Processing |Static Pages plugin wiki page]].

Template Blocks are supported via a View as well. The only thing that is not supported for Views is the ability to have a Template Block within another Template Block.

== Multiple Template Source Paths ==

There are many templates files within the Geeklog system, plus all the template files that plugins use as well. If you want to change the look and feel of a site, generally only a small number of template files are actually modified. Having the ability to specify multiple templates paths allows you to have a base location for templates, and then simply copy the ones you wish to modify to an alternative location (usually the /custom folder in the same directory.) This reduces the overall disk storage needed on the server, and also provides a method to quickly see which templates have been modified. It also means that your modified template files will not be overwritten during a software upgrade.

Plugins can also support multiple template paths which allows for template files to be included with a plugin install for more than one theme. Currently the core plugins, media gallery and the forum support this. For more information on this and how to implement it please read [[Theme_Developers_Guide#Theme_Specific_Plugin_Templates |Theme Specific Plugin Templates]].

== Benefits ==

Benefits of the Caching Template Library include:

* It is extremely fast.
* It is efficient since the PHP parser does the dirty work.
* No template parsing overhead, only compiles once.
* It is smart about recompiling only the template files that have changed.
* The {!if}..{!else}..{!endif} constructs are passed to the PHP parser, so the {!if…} expression syntax can be as simple or as complex an evaluation as you like.
* It is possible to embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so customizable.
* Built-in caching support.
* Multiple template sources.

Overall, the Caching Template Library brings a significant amount of value and features to a Geeklog site.

= Developer Information =

== Template Variable Naming Convention ==

Template variables follow a strict naming convention. A template variable consist of letters, digits, one or more underscore, period, dash or square brackets, and are delimited by curly brackets. Examples can be found in Geeklog theme files (files with the extension thtml).
<pre>
{template_variable}
</pre>
If any other character is found within curly brackets then the text is not considered a template variable at all, and therefor doesn’t follow the template class rules for unknown setting of remove, comment or keep. The text will just be left as is.

There are a few special cases where a '$' and ':' may be used in a template variable. This includes the use of the [[Caching_Template_Library#Automatic_Language_File_Variables|Automatic Language File Variables]] and the [[Caching_Template_Library#Replacement_Variable_Manipulation_Modifiers |Variable Manipulation Modifiers]].

== Version Checks ==

You can tell that the caching template library is installed and what version of the library is running by checking if TEMPLATE_VERSION is defined using the PHP function defined().

== TEMPLATE_OPTIONS ==

At the top of the file is an array of TEMPLATE_OPTIONS. These options are global options for all templates created by Geeklog. They are:

''' 'path_cache' (required) '''

This option points to the cache directory. If you don't like the name “layout_cache”, this is where you change it. By default it is equal to “$_CONF['path_data']”.”layout_cache/”.

''' 'path_prefixes' (required) '''

This is a list of ALL paths under which templates may be found. The cached name of the template file is based on the path of the template file. These array entries are used to strip off the redundant portions of the path. The order they appear here is important because once a match is found other prefixes will not be checked. Basically they should be included in this entry with the longest paths going first.

By default, the options are:

* the root of your themes directories ($_CONF['path_html']/layout).
* the root of your plugins directory ($_CONF['path']/plugins).
* the root of your server ('/') Do not remove this one!!

In a hosted environment, you might want to add your account's home directory before the last entry.

''' 'unknowns' (optional) '''

Sets the default unknown handler. If it isn't set, default unknowns become 'remove', as usual. The other options are 'comment' and 'keep'.

''' 'force_unknowns' (optional) '''

Sets the unknown handler regardless of the calling code's settings. This is useful for debugging a set of templates as you only have to modify the template class in one place.

''' 'default_vars' (optional) '''

This is a list of template variables that is set for every instance of the template object. The most obvious use for this is stuff like $_CONF['site_url']. This way the theme author doesn't have to rely on the dev team remembering to include such variables in every template.

The default values are:

* 'site_url' ⇒ $_CONF['site_url']
* 'site_admin_url' ⇒ $_CONF['site_admin_url']
* 'layout_url' ⇒ $_CONF['layout_url']
* 'XHTML' ⇒ XHTML
* 'anonymous_user' ⇒ COM_isAnonUser(),
* 'device_mobile' ⇒ $_DEVICE->is_mobile(),
* 'front_page' ⇒ COM_onFrontpage(),
* 'current_url' ⇒ COM_getCurrentURL()

''' 'incl_phpself_header' (optional) '''

This boolean option is used to control the inclusion of anti-spoofing text in the resulting cache files. It defaults to true. If your cache directories can be accessed by remote browser (because you cannot create files outside your webroot) you must set this value to true or risk a security issue with your cache files.

When true, the following is added to the top of every cached template file with filename replaced with the current filename:

<pre>
<?php if (strpos($_SERVER['PHP_SELF'], basename($filename)) !== false) {
die ('This file can not be used on its own.');
} ?>
</pre>

''' 'cache_by_language' (optional) '''

This boolean variable determines whether or not to create unique cache files per language instance. When cache_by_language is on, a directory is created under the data/layout_cache directory for each language enabled and accessed on your website. Templates that take advantage of the Automatic Language file variables features are described below. These variables are replaced when the cache file is created instead of dynamically each time the cache is hit.

Unless you have tight filesystem restrictions, you should set this variable to true to maximize your potential system speed up.

''' 'hook' (optional) '''

This advanced feature is designed for use by developers and theme makers. It is described more fully elsewhere in this documentation. It provides ways for a developer to hook calls to various methods on the Template class in order to modify the generated output without modifying the code creating the output.

== TEMPLATE->set_root() ==

The set_root method now accepts an array of root directories. When files are added to the class using set_file, the files are checked against the array of root directories in order. The first path listed overrides subsequent paths. So the most common use for multiple roots is in plugins that might be themed. The theme directory should come first followed by the plugin's template directory. That way the theme's file take precedence over the plugin's default templates.

Plugins typically create templates using a function to guess at the correct path:
<pre>
function calendar_templatePath ($path = '')
{
global $_CONF;

if (empty ($path)) {
$layout_path = $_CONF['path_layout'] . 'calendar';
} else {
$layout_path = $_CONF['path_layout'] . 'calendar/' . $path;
}

if (is_dir ($layout_path)) {
$retval = $layout_path;
} else {
$retval = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty ($path)) {
$retval .= '/' . $path;
}
}

return $retval;
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
This is potentially a problem if the theme doesn't copy over all the files needed by set_file. Now this is possible:
<pre>
$template = new Template(
array($_CONF['path_layout'].'calendar/additional/path',
$_CONF['path'].'plugins/calendar/templates/additional/path'
)
);
</pre>
or
<pre>
function calendar_templatePath($path = '')
{
global $_CONF;

$layout_path = $_CONF['path_layout'] . 'calendar';
$plugin_path = $_CONF['path'] . 'plugins/calendar/templates';
if (!empty($path)) {
$layout_path .= '/' . $path;
$plugin_path .= '/' . $path;
}

return Array($layout_path, $plugin_path);
}

$template = new Template(calendar_templatePath('additional/path'));
</pre>
Another benefit of this is that if you only want to modify a subset of a plugin's templates for your theme, you only need to put the subset of files in the theme directory. Having multiple root directories means any files not in the themes directory are taken from the default directory.

== Replacement Variable Manipulation Modifiers ==

Modifiers can be applied to replacement variables using the format {variable:m} where variable is a normal replacement variable and m is the modifier. Multiple modifiers can be applied in series {variable:u:s}. The following modifiers currently exist:

* :u Call urlencode on the variable before output.
* :s Call htmlspecialchars on the variable before output.
* :t### Truncates the variable to ### characters.

Using these options should be done with care, making sure the calling code hasn't already applied an output filter to the data. Likewise, these calls should not be used on any variable containing HTML.

== Automatic Language File Variables ==

Add any text you want to the template while still following the Geeklog text internationaliztion guidelines. Any variable in the form {$LANG_abc[xx]} will lookup the index in the stated language array. So {$LANG_ADMIN['save']} will be replaced by the same text as that placed on all the Save buttons in the system. Template files are no longer limited to the text labels delivered by the coder. Text from the language variable is automatically passed through htmlspecialchars before output. Language variables cannot be used in simple action variables. Advanced action variables can use them.
<pre>
// code like this
$T->set_var('lang_username',$LANG_USER['name']);
$T->set_var('username', $username);

// becomes
$T->set_var('username', $username);

// and the template
<tr><td>{lang_username}:</td><td>{username}</td></tr>

// becomes
<tr><td>{$LANG_USER[name]}:</td><td>{username}</td></tr>
</pre>
There are plans to do research at some future date into which is faster, setting a variable from a LANG array, or putting the LANG array reference directly into the template.

== Template Blocks ==

One way to save on having a large number of template files is use template blocks. 1 or more blocks can exist inside a template file and these blocks can also be nested (blocks within blocks). In the example below the template file contains a select control called "select1" with a template variable called "options". There is also a template block called "select-option" with some other variable names.

<pre>
<select name="select1">
{options}
</select>


<option value="{value}" {selected}>{option_name}</option>

</pre>

The sample PHP code below makes use of this template and it's block and loads in some options from the database.

<pre>
$t = COM_newTemplate($_CONF['path_layout']);
$t ->set_file('control', 'control.thtml');
$t ->set_block('control', 'select-options');

$selectedvalue = 2;
$sql = "SELECT * FROM some_table";
$result = DB_query($sql);
$numRows = DB_numRows($result);
for ($i = 0; $i < $numRows; $i++) {
$A = DB_fetchArray($result, true);
$t ->set_var('value', $A['somevalue']);
$t ->set_var('option_name', $A['somename']);
if ($A['somevalue'] == $selectedvalue) {
$t ->set_var('selected', 'selected="selected"');
} else {
$t ->set_var('selected', '');
}
$t->parse('options', 'select-option', true);
}

$t->finish($t->parse('output', 'control'));
</pre>

== Logic Processing ==

One of the biggest benefits of the Template Caching Library is the ability to place logic into the templates. This section assumes you know how to use the old template library.

=== Usage ===

The template library uses variable substitution in template files to create output. All template constructs are contained within braces: {variable}. The simplest construct is the variable as just shown.
The new library adds action variables to the mix. Actions are also contained within braces and the first character of an action is an exclaimation point: '''{!'''action parameters'''}'''. Actions usually do not output anything to the final output. Instead they control what is output around them. In these cases, the action will act as a block within the template contained between two actions. The second action is usually the same as the first with the word 'end' prepended: '''{!'''endaction'''}'''.

CTL v2.2 introduced advanced actions. These have the format '''{!!'''action parameter '''!!}'''. The space and exclamation point are required. Advanced actions allow you to place more complicated values as the parameter field. Instead of assuming parameters are template variables, advanced action parameters that reference template variables must include the braces just like they do in other parts of the template. So while a simple if might look like this '''{!'''if var'''}''', the advanced if can look like this '''{!!'''if {var} == 'a' || {var} == 'b' '''!!}''' (note the number of exclamation points) Advanced actions are closed by standard '''{!'''endaction'''}''' constructs. (note: one exclamation point). Complex conditions can also contain calls to any global function and if you want you can also include template variables within the function call (ie as a function variable).

In this example we use a template variable {uid} (defined by some other process) in an Advanced Action. We use it to call the function COM_isAnonUser to see if the id is the anonymous Geeklog user:
<pre>
{!!if COM_isAnonUser({uid}) !!}
<p>User {uid} is an anonymous user.</p>
{!else}
<p>User {uid} is NOT an anonymous user.</p>
{!endif}
</pre>

=== Actions ===

==== Simple Actions ====

{| border=1
! Action || Description
|-
|| {!if variable}
{!endif}
|| The !if action shows the contained block if the variable evaluates to true. Note that the value 0 evaluates to true.
|-
|| {!else}
|| This action must appear between !if and !endif. It breaks the !if block into true and false halves. The block from !if to !else contains the text displayed if the condition is true. The block between !else and !endif contains the text displayed if the condition is false.
|-
|| {!elseif variable}
|| This combines else and if together to allow multiple possible conditions to be evaluated.
|-
|}

==== Looping Actions ====

{| border=1
! Action || Description
|-
|| {!while variable}
{!endwhile}
|| Similar to if, the contained block is displayed repeatedly as long as variable is true. If the variable starts out false the block is never displayed.
|-
|| {!loop variable}
{!endloop}
|| Creates a variable called variable__loopvar. The contained block is executed 'variable' times with varialbe__loopvar counting from 1 to 'variable' for each iteration. If variable is less than zero, counting goes downward starting at -1. variable__loopvar is deleted (unset) when the loop exits.
|-
|| {!break}
|| Exits a loop prematurely. The rest of the block is not processed and processing continues after the !endwhile or !endloop.
|-
|| {!continue}
|| Ends a loop block prematurely. The rest of the block is not processed and processing continues for the next iteration of the loop.
|-
|}

==== Other Actions ====

{| border=1
! Action || Description
|-
|| {!inc variable}
|| The variable is incremented by 1. If it is a non-numeric string, the value '1' is placed in it.
|-
|| {!dec variable}
|| The variable is decremented by 1. If it is a non-numeric string, the value '-1' is placed in it.
|-
|| {!inc+echo variable}
|| As !inc and the number is displayed.
|-
|| {!dec+echo variable}
|| As !dec and the number is displayed.
|-
|| {!unset variable}
|| Removes the variable from the template's internal variable list.
|-
|}

==== Advanced Actions ====

{| border=1
! Action || Description
|-
|| {!!if condition !!}
|| The condition may contain any template construct that does not end with !}.
|-
|| {!!while condition !!}
|| Works like the simple {!while var} but can take any complex condition.
|-
|| {!!global var,… !!}
|| Pulls the global vars into the cached PHP output.
|-
|| {!!echo condition !!}
|| Echo's the complex condition to the cached PHP output.
|-
|| {!!set var value/expression !!}
|| Assign the variable the listed value or set any complex expression or condition.
|-
|| {!!autotag ... !!}
|| Works like so '''{!!autotag story:welcome !!}''' (this is for autotag '''[story:welcome]''') and allows you to set an autotag in a template file.

Works with autotags that have a close tag as well but you must encompass the entire autotag (including the close tag) in one action and include one half of the square brackets for example '''[tag:foo]some text here[/tag]''' would become '''{!!autotag tag:foo]some text here[/tag !!}''' in the template.

'''Note:''' You cannot embed template variables within autotags or any other Actions.
|-

|}

=== Comments ===

You can include comments in the template files that do not appear in the cached PHP file by enclosing the comment within {# and #} symbols. This is useful for explaining why you have some weird construct in your code without cluttering the cached template with lots of HTML comments.

=== Examples ===

==== Example 1 ====
In this example we use a template variable in an Advanced Action if, elseif, and else condition:
<pre>
{!!if {display_type} == '12' !!}
<p>Display this text when display_type template variable equals 12.</p>
{!!elseif {display_type} == 'yawn' !!}
<p>Display this text when display_type template variable equals yawn.</p>
{!else}
<p>Display this text when display_type template variable is anything else.</p>
{!endif}
</pre>

==== Example 2 ====
In this example we use a template variable in an Advanced Action if condition:
<pre>
{!!if {template_var} == 'info' OR {template_var} == 'info2' !!}
<p>Display this text when template_var equals info or info2.</p>
{!endif}
</pre>

==== Example 3 ====
In this (contrived) example, the only template variable is 'count' and it is set to 3:
<pre>
{# This is an example of a comment #}

{!!set count 3 !!}

{!loop count}
{count__loopvar} of {count}: {!inc+echo total}
{!!if count__loopvar == "2" !!}{!inc count}{!endif}<br>
{!endloop}
</pre>
If the template is parsed twice without resetting count between parses, the output looks like this:
<pre>
1 of 3: 1
2 of 3: 2
3 of 4: 3
4 of 4: 4
1 of 4: 5
2 of 4: 6
3 of 5: 7
4 of 5: 8
5 of 5: 9
</pre>

==== Example 4 ====
This example is Geeklog specific to help illustrate how you might use even the simplest !if construct:
<pre>
if ( $_USER['uid'] >= 2 ) { // user is logged in...
$T->set_var('onlyloggedinusers', 'Some feature only for logged in users');
}
</pre>

In the template, you can now check whether the user is logged in by checking for the existence of the {onlyloggedinusers} variable:
<pre>
<div id="pageheader">
Show the page header
</div>
{!if onlyloggedinusers}
<div class="boldtext">Logged in users can do more here, thanks for logging in!</div>
{!else}
<div class="boldtext">If you login, you can do more!</div>
{!endif}
</pre>
This is a simple example, but it does illustrate the capability and the power. No longer in the PHP code do you need to handle the non-logged in case.

== PHP Code in a Template Files ==

This feature allows you to embed PHP code directly in templates. To embed PHP code directly in a template, use the following example:
<pre>
<div class="welcomeanddate-text">
<span class="gl_user-menu-right">
<?php global $_USER, $_CONF; if (isset($_USER['uid']) && $_USER['uid'] > 1) { ?>
<a href="{site_url}/usersettings.php?mode=edit">{$LANG01[48]}</a><br{xhtml}>
<a href="{site_url}/users.php?mode=logout">{$LANG01[35]}</a>
<?php } else {
if ($_CONF['disable_new_user_registration']==0) {?>
<a href="{site_url}/users.php?mode=new">{$LANG04[27]}</a><br{xhtml}>
<?php } ?>
<a href="{site_url}/users.php?mode=login">{$LANG01[58]}</a>
<?php } ?>
</pre>
Notice how all PHP is surrounded by <?php ''' php_code_here ''' ?>

Here is another example that will return the template variable 'title' from the template class (if it is set).
<pre>
<?php
echo $this->get_var('title');
?>
</pre>

== Troubleshooting ==

The most common problem you will run into with the template cache is forgetting they are there. If you go into a .thtml file and make a change and it isn't showing up, you may need to delete the cached file as the algorithm to overwrite them only works when the file dates are correct. Some FTP systems and web consoles screw up the file times of uploaded files preventing the class from updating the cached PHP file. To ease this process, there is an entry in the Admin Command & Control screen labeled Clear Template Cache.

== Tip 'n Tricks ==

The Caching Template Class works with variables and array's may be used in its interface (API). You may encounter a GOTCHA when you mix simple arrays and hashes in some places.

The set_var call has two forms: set_var($var_name, $var_value) and set_var($var_names_array). This array is definitely a hash (a key-value pair).
The get_var call has two forms: get_var($var_name) and get_var($var_names_array). This array is definitely a simple array (numeric keys).
So, setting variables using set_var($myArray) would work, while get_var($myArray) would NOT work. Instead use get_var(array_keys($myArray)).
The API call get_vars however is suited to accept a hash, but only a hash.

Same goes for clear_var($myArray). One easily mistakes here when processing data from mySql as rows: set_var($row) and clear_var(array_keys($row)).
And now, there is no API call clear_vars available.

----

Using php code in a template, the following could be useful:
<pre>
<?php $this->set_var('newvar', 'newvalue'); ?>
</pre>

----

Using php code in a template, a global variable could be used to hand over data to the next template in a chain of templates. In case the template does specific calculations, generates a graph, or else. This comes in handy with auto tags.
<pre>
<?php $GLOBALS['myVar'] = $this->get_var('some_variable'); ?>

<?php $this->set_var('some_variable', $GLOBALS['myVar']) ?>
</pre>

This page is based on original content from the glFusion Wiki - https://www.glfusion.org/wiki/glfusion:development:usingtemplates - modified for Geeklog - Licensed under [https://creativecommons.org/licenses/by-sa/4.0/ CC Attribution-Share Alike v4.0].

Geeklog Release Procedures

2018-06-26T15:17:49Z

Tom: /* Geeklog Sites */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.xml
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” in the top directory).
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.
* Backup the server files and database.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Main Page

2018-06-26T14:41:51Z

Tom: /* Geeklog Documentation */

[[Image:Logo.gif]]

== Geeklog Documentation ==

This is the main entry for Documentation for the [https://www.geeklog.net/ Geeklog] CMS and weblog engine. The current version is 2.2.0. For more information about this version please read [https://www.geeklog.net/article.php/geeklog-v2-2-0 this announcement article].

If you are upgrading from Geeklog v2.1.3 or older please make sure your 3rd party Geeklog plugins are updated to the latest version and support Geeklog v2.2.0. Plugins are now required to use the function COM_createHTMLDocument. This replaces the depreciated functions COM_siteHeader and COM_siteFooter. If you are unsure if a plugin supports Geeklog v2.2.0 then either disable it before you upgrade Geeklog, or uninstall it.

Also, there have been some changes with blocks and topics between Geeklog 2.0.0 and 1.8.2sr1 so not all plugins may work with 2.1.0 or higher unless they have been updated. If you are upgrading your site that is 2.0.0 or older make sure all the plugins you use are compatible with Geeklog 2.1.0 or higher.

This documentation is a result of community action. Everyone is invited to [http://wiki.geeklog.net/wiki/index.php?title=Special:Userlogin sign up] and participate. If you see an omission you can fill it in. If you see a mistake, correct it. If you see where things could be better organized, change it. If you have a note about a particular configuration, add it. In other words: We need your help to make it better!

* [[Geeklog Documentation]]:
*# [[Introduction]]
*# [[Installation]]
*# [[Administration]]
*# [[Users Documentation|User's Documentation]]
*# [[Programmers/Developers Documentation]]
* Quick Links:
*# [[Complete Table of Contents]]
*# [[Special:AllPages|List of all Articles]]
*# [[Getting Started]] with Geeklog Development
*# [[Google Summer of Code]]

Geeklog Release Procedures

2018-06-26T14:28:26Z

Tom: /* Geeklog Sites */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.xml
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” in the top directory).
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download. (may have to delete template cache)
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2018-05-24T16:16:37Z

Tom: /* Other Files */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.xml
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” in the top directory).
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* If you change the database name on the Geeklog upgrade (which we have been for each new version) remember to change the cron-jobs to reflect the new database name, username, and password

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download.
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2018-05-24T14:29:47Z

Tom: /* Other Files */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.xml
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” in the top directory).
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
** If updating lib-custom make sure to add the functions phpblock_current_versions_downloads and phpblock_whos_new
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download.
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2018-05-23T14:28:43Z

Tom: /* glnet_curve Theme */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.xml
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” in the top directory).
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. No other themes should be present on Geeklog.net.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* <tt>lib-common.php</tt>: add the <code>require_once</code> line for the Bad Behavior plugin. '''Do this after the upgrade of Geeklog.'''

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download.
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2018-05-23T14:27:49Z

Tom: /* glnet_curve Theme */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.xml
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” in the top directory).
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory.
** On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required.
** As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* <tt>lib-common.php</tt>: add the <code>require_once</code> line for the Bad Behavior plugin. '''Do this after the upgrade of Geeklog.'''

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download.
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Geeklog Release Procedures

2018-05-23T14:26:30Z

Tom: /* glnet_curve Theme */

This page outlines the necessary steps to perform before, during, and after the release of a new Geeklog version.

= Pre-Announcements =

* Obviously, plans for a new release should have been discussed on [http://eight.pairlist.net/mailman/listinfo/geeklog-devel geeklog-devel]. For security releases, the discussion may happen on [http://www.geeklog.net/staticpages/index.php?page=GeeklogSecurity geeklog-security] only.
* Notify the [http://eight.pairlist.net/mailman/listinfo/geeklog-translations geeklog-translations] mailing list to give translators a chance and a timeframe to update their translations.

= The Tarball =

* Make sure you update history file in docs with version and release date (and readme in root directory if needed)
* Confirm correct Geeklog version number in /public_html/sitconfig.php, /public_html/admin/install/classes/installer.class.php, and /build.xml
* Make sure all language files are synched
** This process will use the English language files and synch with all other languages for Geeklog, The Installer, and all core plugins
** Open your command prompt and to the top directory of your local Geeklog repository
** Type: .\system\build\vendor\phing\phing\bin\phing.bat lang
** Once complete commit any updated language files
* For building an install package we use phing (which uses a config file called “build.xml” in the top directory).
** Go to your Geeklog repository top directory in command prompt
** Confirm latest repository and make sure no old compressed install packages exist (or they will be rolled into the new package).
** Type: .\system\build\vendor\phing\phing\bin\phing.bat dist
** Once the process complete you will get a file “geeklog-2.1.2.tar.gz” in the top directory
** If this is a beta or release candidate then the file will need to be renamed to: geeklog-2.1.2-b1.tar.gz or: geeklog-2.1.2-rc1.tar.gz
* Create a new release on GitHub
** Visit https://github.com/Geeklog-Core/geeklog/releases
** Create a release and make sure to tag it the correct version number (it will be tagged in the repository), for example: v2.1.2 or v2.1.2-rc1 (for release candidate) or v2.1.2-b1 (for beta)
* Visit Geeklog.net
** Add the new release to the downloads plugin
** Add a new article about the release pointing to the correct download
* unpack tarball on the server
* update site

= Updating geeklog.net =

* '''IMPORTANT:''' Disable Bad behavior plugin before upgrading Geeklog.net and then re-enable after. If you don't it may cause issues.

The following files need special handling when updating geeklog.net:

== glnet_curve Theme ==
* As of Geeklog 2.1.2 the glnet_curve is now the default theme used by Geeklog.net. It is a copy of on the Denim Curve theme with only a few changes to the header and footer template files (along with the name changes, etc.. required in functions.php). This theme is based on the Denim theme which is also required in the themes directory. On upgrades for the glnet_curve remember to update the jquery_ui directory and the images directory with any changes from the Denim Curve theme. The fonts, css, css_ltr, and css_rtl directories are also required. As far as template files are concerned only the files we modified directly for Geeklog.net should be in the glnet_curve directory and the Denim theme should be the stock theme from the release. Most changes in these files are marked with the"GLNET CUSTOM" comment.
* For glnet_curve theme take a copy of the <tt>footer.thtml</tt> from denim and add it to glnet_curve. Make sure the version number is visible and add the "hosted by pair.com" link (as per our agreement with pair Networks).
* The Download block on the top right uses a block header template without a title, so add this to the theme's <tt>functions.php</tt>: <pre>$_BLOCK_TEMPLATE['download'] = 'blockheader-notitle-right.thtml,blockfooter.thtml';</pre> and make sure the <tt>blockheader-notitle-right.thtml</tt> template file exists.

== Other Files ==
* remove the bundled <tt>lib-custom.php</tt> and <tt>robots.txt</tt> and use the copies already present on the webserver instead
* check <tt>db-config.php</tt> and <tt>siteconfig.php</tt> for any required changes
* <tt>lib-common.php</tt>: add the <code>require_once</code> line for the Bad Behavior plugin. '''Do this after the upgrade of Geeklog.'''

= Information to Update =

== Geeklog Sites ==

* Create a new download for the install in the Downloads plugin. Easiest way is to copy and older version of a Geeklog download.
** A full install tarball download belongs in the '''Geeklog''' category and the '''Geeklog''' project. An Update tarball belongs in the sub category '''Updates'''.
** Make sure any release previous betas or release candidates are moved to '''Old Versions''' Downloads category.
** Confirm Downloads button on homepage block points to the latest Geeklog download.
* Publish an '''article''' on geeklog.net:
** summarize the changes in this release
** include a link to the entry in the download area
** Convention for the story ID: <tt>geeklog-x.y.z</tt>, e.g. geeklog-1.5.2, geeklog-1.4.0sr6
** Add story to the Geeklog topic and the Announcements topic (default). Make sure both are set to inherit
** Announcements of new versions go into the [http://www.geeklog.net/index.php?topic=announcements Announcements] topic. For security releases, either post the announcement in the [http://www.geeklog.net/index.php?topic=Security Security] topic, or post two articles (one in Announcements and the details of the security issues in Security).
** don't forget to send '''pingbacks''' and '''ping''' weblog directories
* Update the '''versionchecker.php script''' (not for betas/release candidates).
** Once updated, the new version of the script should be added to the [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/tools/ tools repository].
* Send out an '''email''' to the [http://eight.pairlist.net/mailman/listinfo/geeklog-announce geeklog-announce] mailing list.
** Provide a brief description of the release and link to the geeklog.net article for details.
* Update the '''wiki frontpage''' (not for betas/release candidates)
* Update the '''GitHub Issue Tracker''' (not for betas/release candidates). Make sure you have a later milestone create and then move all incomplete issues and feature requests from current milestone to a later milestone. Close current milestone
* Notify Ironmax at Spacequad.com that the demo site needs to be updated to use the latest version of Geeklog (not for betas/release candidates). Once updated you will also need to update the Resources block with the correct version number of the demo site.

== External Sites ==

These sites should only be notified about final and security releases (i.e. not for betas and release candidates):

* [http://freshmeat.net/projects/geeklog/ freshmeat.net]
* [http://cmsmatrix.org/matrix/cms-matrix/geeklog cmsmatrix.org]
* [http://php.opensourcecms.com/scripts/details.php?scriptid=32&name=Geeklog opensourcecms.com]
* [https://sourceforge.net/projects/geeklog sourceforge.net]
* [https://www.ohloh.net/p/geeklog ohloh.net]

[[Category:Internals]]

Upgrade Instructions

2018-03-30T19:33:24Z

Tom:

Upgrading is no different than a New Installation except your database already exists and needs to be updated.

Take extreme care to back up any files from your current Geeklog installation that have any custom code in them, especially lib-custom.php (where all custom code should reside). Be sure to back up any modified themes, images, and static pages from your current installation.

Also, please be sure to back up your database. We can't stress the importance of backing up your files and database enough.

'''YOU HAVE BEEN WARNED'''.

:1. Download the current version of Geeklog from Geeklog.net.
:2. Unpack the downloaded tarball file by running:
::tar -zxvf geeklog-2.0.0.tar.gz
::'''Note:''' Some users have reported that WinZip corrupts certain Geeklog files during decompression. This will cause errors during the installation process. You are strongly urged not to use WinZip. Try 7-Zip or WinRAR if you must decompress the file locally.
:3. Place the contents of geeklog-2.0.0/ into the same directory your old installation was located. For instance, if your old Geeklog was in /usr/home/www/geeklog/, then your new installation should also be in /usr/home/www/geeklog/.
:4. Depending on the version you're upgrading from:
::* '''When upgrading from Geeklog 1.4.1 or earlier:''' Put the config.php files from your old install back into their place now (the main config.php and those for the plugins). The install script will read these files during the upgrade to pre-populate the new Configuration admin panel with your settings. If you skip this step, you will end up with default settings for Geeklog and the pre-installed plugins.
::* '''When upgrading from Geeklog 1.5.0 or later:''' Put the db-config.php and siteconfig.php from your old install back into their place now, overwriting the files of the same name that came in the tarball. Otherwise, you would have to enter your database credentials and other information during the upgrade process again.
:5. Open your browser and navigate to the Geeklog installation wizard file admin/install/index.php on your web server. The path to this file will depend on where you chose to put the Geeklog files on your web server. The default location is:
:: http://[your_geeklog_site]/admin/install/index.php

:6. The Geeklog installation wizard was designed to automate the upgrade process. Simply follow the installation steps.

Once you have completed the upgrade be sure to delete the admin/install directory.