Including plugins

From phpCMS

Contents 1 Including plugins 1.1 General Information About Plugins 1.1.1 Advantages of plugins compared to included scripts 1.1.2 Disadvantages of plugins compared to included scripts 1.2 Plugin capabilities 1.3 Including a plugin 1.3.1 Including plugins in template files 1.3.2 Including plugins in content files 1.4 An Example 1.4.1 The Template File 1.4.2 The Content File 1.4.3 The Plugin (user_time.php) 1.4.4 The resulting page

[edit] Including plugins

[edit] General Information About Plugins

Plugins are an interface to the phpCMS core. Contrary to the including of scripts, the output isn't processed directly to the browser, but is available for further processing through phpCMS. Thus a content file can be manipulated by a plugin.

[edit] Advantages of plugins compared to included scripts

• (static) returned values can be cached
• (static) returned values can be gzipped
• fields in the content file can be manipulated at runtime
• global settings like Proxy-Cache-Time or Client-Cache can be overwritten for every single page
• Plugins can be included either in a template file or in a content file
• Plugins are also executed in Editing Mode

[edit] Disadvantages of plugins compared to included scripts

• Existing scripts have to be adapted
• A good knowledge of PHP and phpCMS is required
• Handling of global variables is slightly more complicated
• Partly caching of pages (like it's done with scripts) isn't supported

All plugin authors are invited to publish their own plugins at the phpCMS website. In the future, a plugin certification is planned as well.

[edit] Plugin capabilities

A plugin can modify your page in different ways. Depending on the plugin you use, the modifications can be:

• using tags: A plugin loaded from a template can modify the tags used to parse the current page or add new one. Plugins doing so need top be loaded early, just because the new tags take effect only for that part of the page that follows the loading.
• direct changes: Plugins are capable of changing content on the page (but only as far as the page has been processed already). This allows for plugins that process the page code and change content according to what they find.
• plugin output: A plugin can simply create output that is used on the page. Depending on the way the plugin is included, different ways of specifying the location this output will be included in the resulting file are needed (see below).

[edit] Including a plugin

To include a plugin, you use a line like this:

{PLUGIN FILE="path_to_plugin/pluginname.php" TYPE="DYNAMIC"}

FILE 

The keyword FILE describes the path where the plugin can be found. Path names can be absolute or relative, additionally the phpCMS-variable $home can be used.

TYPE 

The keyword TYPE determines if the plugin will be executed only once or if it's re-executed at every page call. Possible values for this parameter are DYNAMIC and STATIC. Type DYNAMIC plugins are executed at every single request. This means also, that server- and client-cache will be disabled for this page by default. With plugin type STATIC all global phpCMS settings will be kept.

[edit] Including plugins in template files

A plugin included in the template file will be executed on every requested page. Use this plugin type for example to display the site creation date or to create keywords or metatags for your page. Plugins are executed during parsing at the place they are located on. So if you use the plugin to extend the phpCMS tag replacement routine, the newly added tags are only valid below the plugin call.

Possible plugin outputs will be put exactly to the place where they are located in the template file.

[edit] Including plugins in content files

If you use plugins in the content file, you can choose if it shall be included or not for every single page. Such a plugin will be executed before parsing - but after the reading - of the document (content file). This means, that the content file's content has been read already, but there hasn't been any tag replacement or processing of menu templates yet. Note that plugins loaded in a content file are not capable of modifying the tag list.

If the plugin produces any output, you need to tell phpCMS where the output shall be shown up. For this you have to add a placeholder like {CONTENT_PLUGIN_X} to the according place in the template. The "X" represents a numerical order, beginning with 0, which means, the first content file plugin submits its output to {CONTENT_PLUGIN_0}.

If a plugin doesn't produce any output or simply changes the field value of another content field within the content file, it isn't necessary to add a placeholder in the template.

A plugin placeholder in the template file will be filled only if an according plugin in the content file is given. This provides the opportunity to define a placeholder in the default template.

[edit] An Example

With this little example we want to display the visitor's IP. The plugin can be included optionally in the template or in the content file. In the example we include the plugin in the content file, and the output will be added to the field {CONTENT_PLUGIN_0} (this is a plugin that produces output - and as it's the only one, it's output gets inserted at the position of {CONTENT_PLUGIN_0} in the template). Alternatively we could include it in the template directly, where it would produce it's output right at the position it is called.

[edit] The Template File

<html>
<body>
{MENU NAME="MAIN"}
<h1>Heading</h1>
{CONTENT}
{CONTENT_PLUGIN_0}
</body>
</html>

[edit] The Content File

{PROJECT} /somewhere/project.ini
{MENU} 00.01.01
{PLUGIN FILE="user_time.php" TYPE="DYNAMIC"}
{CONTENT}
This is the content.

[edit] The Plugin (user_time.php)

<?php
// Add the information we want to the plugin output buffer
$PluginBuffer[0] = '<p>It is '. date("H:i", time() ).' now.<br />'.
                   'You have the IP number: '.$_SERVER["REMOTE_ADDR"].'</p>';
?>

[edit] The resulting page

Now the following will be displayed on the page:

This is the content.
It is 00:00 now.
You have the IP number 127.0.0.1

Attention: Please make sure that there aren't any Whitespaces or empty lines before the opening and after the closing PHP-tag, or the parser will exit the process with an error!

see also: How to write plugins (Developer documentation) | Docu for existing phpCMS plugins (Developer documentation)