Creating a front-end page

We just learned how to write our first plugin. Let's see now how to create a dynamic page on the blog. We are going to create a Public example plugin, its files will be located in a /publicExample/ directory.

<?php
if (!defined('DC_RC_PATH')) {return;}
 
$this->registerModule(
	/* Name */			'Public example',
	/* Description */		'A public page',
	/* Author */			'Dotclear Documentation',
	/* Version */			'0.1',
	/* Permissions */		'usage,contentadmin'
);
?>

First, we register the URL in the _prepend.php file :

<?php
if (!defined('DC_RC_PATH')) {return;}
 
# register the "publicexample" URL
$core->url->register('publicexample','publicexample',
	'^publicexample(?:/(.+))?$',array('publicExampleDocument','page'));
?>

The parameters of the register function are :

1. the URL type, used by Dotclear to identify it
2. the base URL of the page
3. the URL regular expression
4. a callback : a function name or an array containing a class name and a function to call when the URL is visited

To access this URL, whatever the context is, we will use this code:

$core->blog->url.$core->url->getBase('publicexample')

publicexample is the URL type.

The "publicexample" URL that we registred in the _prepend.php files calls the page function of the publicExampleDocument class. This function takes one parameter : the URL regular expression. Here ^publicexample(?:/(.+))? select text right after publicexample/ if there's one. The plugin will display a different message if the "publicexample/lorem" URL is asked.

class publicExampleDocument extends dcUrlHandlers
{
	public static function page($args)
	{
		global $core;
 
		# $_ctx is the context, we can add to it everything we want
		$_ctx =& $GLOBALS['_ctx'];
 
		# $_ctx->publicExample will be a string
 
		# if the URL is "publicexample/lorem"
		if ($args == 'lorem')
		{
			$_ctx->publicExample = __('Lorem ipsum');
		}
		# else, if the URL is "publicexample"
		else
		{
			$_ctx->publicExample = __('Public');
		}
 
		# save the directory that contains the default template
		# the public_example.html file
		$core->tpl->setPath($core->tpl->getPath(),
			dirname(__FILE__).'/default-templates/');
 
		self::serveDocument('public_example.html','text/html');
	}
}

The $_ctx→publicExample is defined according to the $args value. It will be used later.

See Creation of a tpl tag for a plugin or a theme for more informations.

# Declaration statement of the {{tpl:Public}} tag
$core->tpl->addValue('PublicExampleValue',
	array('publicExampleTpl','PublicExampleValue'));
 
class publicExampleTpl
{
	public static function PublicExampleValue()
	{
		return('<?php echo($_ctx->publicExample); ?>');
	}
}

<?php 
# ***** BEGIN LICENSE BLOCK *****
# 
# This program is free software. It comes without any warranty, to
# the extent permitted by applicable law. You can redistribute it
# and/or modify it under the terms of the Do What The Fuck You Want
# To Public License, Version 2, as published by Sam Hocevar. See
# http://sam.zoy.org/wtfpl/COPYING for more details.
# 
# ***** END LICENSE BLOCK *****

if (!defined('DC_RC_PATH')) {return;}
 
class publicExampleDocument extends dcUrlHandlers
{
	public static function page($args)
	{
		global $core;
 
		# $_ctx is the context, we can add to it everything we want
		$_ctx =& $GLOBALS['_ctx'];
 
		# $_ctx->publicExample will be a string

		# if the URL is "publicexample/lorem"
		if ($args == 'lorem')
		{
			$_ctx->publicExample = __('Lorem ipsum');
		}
		# else, if the URL is "publicexample"
		else
		{
			$_ctx->publicExample = __('Public');
		}
 
		# save the directory that contains the default template
		# the public_example.html file
		$core->tpl->setPath($core->tpl->getPath(),
			dirname(__FILE__).'/default-templates/');
 
		self::serveDocument('public_example.html','text/html');
	}
}
 
# Declaration statement of the {{tpl:Public}} tag
$core->tpl->addValue('PublicExampleValue',
	array('publicExampleTpl','PublicExampleValue'));
 
class publicExampleTpl
{
	public static function PublicExampleValue()
	{
		return('<?php echo($_ctx->publicExample); ?>');
	}
}
 
?>

The template file public_page.html is ocated in the default-templates directory. It contains the following code:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="{{tpl:BlogLanguage}}" lang="{{tpl:BlogLanguage}}">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta name="MSSmartTagsPreventParsing" content="TRUE" />
 
  <title>{{tpl:lang Public example}} - {{tpl:BlogName encode_html="1"}}</title>
 
  {{tpl:include src="_head.html"}}
</head>
 
<body class="dc-publicExample">
<div id="page">
{{tpl:include src="_top.html"}}
 
<div id="wrapper">
 
<div id="main">
  <div id="content">
 
  <div id="content-info">
    <h2>{{tpl:lang Public example}}</h2>
  </div>
 
  <div class="content-inner">  
  	<h3>{{tpl:PublicExampleValue}}</h3>
 
		<ul>
			<li><a href="{{tpl:BlogURL}}publicexample">{{tpl:lang publicexample}}</a></li>
			<li><a href="{{tpl:BlogURL}}publicexample/lorem">
				{{tpl:lang publicexample/lorem}}</a></li>
		</ul>
  </div>
 
  </div>
</div> <!-- End #main -->
 
<div id="sidebar">
  <div id="blognav">
    {{tpl:Widgets type="nav"}}
  </div> <!-- End #blognav -->
 
  <div id="blogextra">
    {{tpl:Widgets type="extra"}}
  </div> <!-- End #blogextra -->
</div>
 
</div> <!-- End #wrapper -->
 
{{tpl:include src="_footer.html"}}
</div> <!-- End #page -->
</body>
</html>

It uses the the

{{tpl:PublicExampleValue}}

tag that we defined in the _public.php file.

plugin-publicExample.zip