Dotclear Documentation 2.0:resources:plugins

2.0:resources:plugins:admin

Wed, 16 Oct 2013 09:55:25 +0200

	current
Line 1:	Line 1:
	+	====== Writing a plugin back-end ======

	+	===== Minimal Structure =====
	+	==== _admin.php ====
	+
	+	The plugin should contain an ''_admin.php file'' :
	+
	+	<code php>
	+	if (!defined('DC_CONTEXT_ADMIN')) {return;}
	+
	+	# add the plugin in the plugins list of the administration menu
	+	$_menu['Plugins']->addItem(
	+	# link name
	+	__('Example'),
	+	# base URL of the back-end
	+	'plugin.php?p=example',
	+	# URL of the image used as an icon
	+	'index.php?pf=example/icon.png',
	+	# URL regular expression
	+	preg_match('/plugin.php\?p=example(&.*)?$/',
	+	$_SERVER['REQUEST_URI']),
	+	# permessions needed to display the link
	+	$core->auth->check('usage,contentadmin',$core->blog->id));
	+	</code>
	+
	+	<note important>In the previous code, remplace ''example'' by the plugin directory's name. The icon should be 16×16 pixel wide, you can find some in the [[http://www.famfamfam.com/lab/icons/silk/\|Silk Icons]] pack.</note>
	+
	+	A link to the administration page is now visible in the sub-menu Extensions of the administration page:
	+
	+	{{:2.0:resources:plugins:admin:menu_item.png\|}}
	+
	+	<note tip>
	+	Besides the fact that the plugin defins general permissions in the [[public-page#le-fichier-_define.php\|_define.php]] file, it can sometimes be necessary to limit access to the back-end page to fewer users. For that purpose, you have to add after <code php>if (!defined('DC_CONTEXT_ADMIN')) {return;}</code> the following code:
	+
	+	<code php>
	+	if (!$core->auth->isSuperAdmin()) {return;}
	+	</code>
	+
	+	It is of course possible to adapt this code to specific permissions with the ''check()'' function from the ''dcAuth'' class.
	+	</note>
	+
	+	==== index.php ====
	+
	+	Here is the base structure of the ''index.php'' file. Note that the ''<html>'' doesn't have any attributes : Dotclear adds them when the page is displayed.
	+
	+	<code html>
	+	<?php
	+	# insert PHP code here
	+	?>
	+	<html>
	+	<head>
	+	<title><?php echo(__('Example')); ?></title>
	+	</head>
	+	<body>
	+
	+	<h2><?php echo html::escapeHTML($core->blog->name).' &rsaquo; '.
	+	__('Example'); ?></h2>
	+
	+	<?php echo(__('Hello World!')); ?>
	+
	+	</body>
	+	</html>
	+	</code>
	+
	+	Here is the result :
	+
	+	{{:2.0:resources:plugins:admin:page.png?300\|}}
	+
	+	===== Download the example plugin =====
	+
	+	[[http://lab.dotclear.org/raw-attachment/wiki/plugin/adminExample/plugin-adminExample.zip\|plugin-adminExample.zip]]
	+
	+	===== Customize the administration page =====
	+
	+	{{{pagetoc
	+	.:admin:tabs
	+	.:admin:message
	+	.:admin:columns
	+	.:admin:forms
	+	.:admin:example
	+	.:help
	+	}}}

2.0:resources:plugins:auto-install

Wed, 16 Oct 2013 09:55:25 +0200

1366340599		current
Line 173:		Line 173:
	</code>		</code>

-	Like index method, this method can take more than two parameters if the key is made of several table fields.	+	Just like index method, this method can take more than two parameters if the key is made of several table fields.

	==== Add a unique key ====		==== Add a unique key ====
Line 181:		Line 181:
	</code>		</code>

-	Like index method, this method can take more than two parameters if the key is made of several table fields.	+	Just like index method, this method can take more than two parameters if the key is made of several table fields.

	==== Add a reference to another table ====		==== Add a reference to another table ====

2.0:resources:plugins:dashboard

Wed, 16 Oct 2013 09:55:25 +0200

	current
Line 1:	Line 1:
	+	====== Add an icon to the dashboard ======

	+	===== Introduction =====
	+
	+	Sometimes, a plugin needs to display information relative to its operation directly in the dashboard. For instance, the daInstaller plugin adds an orange icon when updates are available. This page will explain you how to get to this result.
	+
	+	===== Adding a favorite icon =====
	+
	+	Dotclear 2.3 introdcued a new user interface that allowed users to define their own favorites. Here is how a plugin can add an icon to the list of available icons:
	+
	+	In the plugin ''_admin.php'' file:
	+
	+	<code php>
	+	$core->addBehavior('adminDashboardFavs',array('myPluginBehaviors','dashboardFavs'));
	+
	+	class myPluginBehaviors
	+	{
	+	public static function dashboardFavs($core,$favs)
	+	{
	+	$favs['myplugin'] = new ArrayObject(array(
	+	'myplugin',
	+	__('My Plugin'),
	+	'plugin.php?p=myplugin',
	+	'index.php?pf=myplugin/icon.png',
	+	'index.php?pf=myplugin/icon-big.png',
	+	'usage,contentadmin',
	+	null,
	+	null));
	+	}
	+	}
	+	</code>
	+
	+	The arguments to provide when calling the ''dashboardFavs()'' function are:
	+
	+	* Favorite identifier (with no space, accent, …), must be unique
	+	* Favorite label
	+	* Favorite URL (can be almost anything)
	+	* Icon URL (16x16 pixels)
	+	* Icon URL (64x64 pixels)
	+	* Permissions (use null to deny everyone but superadmin, use *''** to allow everyone)
	+	* ID (optional) added in the favorites menu item (on the left)
	+	* class (optional) added in the favorites menu item (on the left)
	+
	+	A plugin can register as many favorites as needed. The icons used in Dotclear come from a package made specially for Dotclear, check [[http://dotclear.org/blog/post/2011/11/13/Dotclear-2.4\|the Dotclear 2.4 announcement post]] for more information.
	+
	+	Moreover, the plugin can customize the information (title, small icon and big icon) of a favorite registered and displayed on the dashboard.
	+
	+	Here is how:
	+
	+	In the plugin''_admin.php'' file:
	+
	+	<code php>
	+	$core->addBehavior('adminDashboardFavsIcon',array('myPluginBehaviors','dashboardFavsIcon'));
	+
	+	class myPluginBehaviors
	+	{
	+	public static function dashboardFavsIcon($core,$name,$icon)
	+	{
	+	if ($name == 'myplugin')
	+	{
	+	$icon[0] = __('My plugin');
	+	$icon[1] = 'plugin.php?p=myplugin';
	+	$icon[2] = 'index.php?pf=myplugin/icon-big.png';
	+	}
	+	}
	+	}
	+	</code>
	+
	+	The arguments to provide when calling the ''dashboardFavsIcon()'' function are:
	+
	+	* Favorite identifier (with no space, accent, …), same as the one used when registering
	+	* An array containing:
	+	* Favorite title
	+	* Favorite URL
	+	* The 64x64 pixels icon URL
	+
	+	The link name, the URL and the image can be modified according to the tests added in ''dashboardFavsIcon()''.
	+
	+
	+	<note related>
	+	The [[admin#download-the-example-plugin\|adminExample]] plugin provide a code example.
	+	</note>

2.0:resources:plugins:files

Wed, 16 Oct 2013 09:55:25 +0200

1281895906		current
Line 10:		Line 10:
	* [[widgets#creation-du-widget-et-administration\|_widgets.php]] : used by _admin.php and _public.php when widget is available outside of the sidebar via the [[/2.0/resources/themes/tags/widget\|<tpl:Widget>]] tag.		* [[widgets#creation-du-widget-et-administration\|_widgets.php]] : used by _admin.php and _public.php when widget is available outside of the sidebar via the [[/2.0/resources/themes/tags/widget\|<tpl:Widget>]] tag.
	* _xmlrpc.php : xmlrpc interface of the plugin.		* _xmlrpc.php : xmlrpc interface of the plugin.
-	* [[services#creation-du-service\|_services.php]] : contains all //Ajax// services used by the plugin.	+	* [[services#service-creation\|_services.php]] : contains all //Ajax// services used by the plugin.
	* [[admin#structure-minimale\|index.php]] : contains the plugin's administration page.		* [[admin#structure-minimale\|index.php]] : contains the plugin's administration page.
	* style.css : contains CSS rules for the plugin if needed.		* style.css : contains CSS rules for the plugin if needed.
Line 47:		Line 47:
	* [[admin#structure-minimale\|index.php]]		* [[admin#structure-minimale\|index.php]]
	* [[auto-install#le-fichier-_install.php\|_install.php]]		* [[auto-install#le-fichier-_install.php\|_install.php]]
-	* [[services#creation-du-service\|_services.php]]	+	* [[services#service-creation\|_services.php]]
	* files containing classes used in the back-end		* files containing classes used in the back-end

2.0:resources:plugins:prefs

Wed, 16 Oct 2013 09:55:25 +0200

1366261112		current
Line 11:		Line 11:
	<note>''addWorkSpace()'' parameter must only contain digits or characters without accents.		<note>''addWorkSpace()'' parameter must only contain digits or characters without accents.

-	Allowed : [a-zA-Z][a-zA-Z0-9]	+	Allowed: [a-zA-Z][a-zA-Z0-9]

	It is recommended to use the plugin name as workspace to avoid 2 plugins have the same workspace.</note>		It is recommended to use the plugin name as workspace to avoid 2 plugins have the same workspace.</note>

2.0:resources:plugins:public-page

Wed, 16 Oct 2013 09:55:25 +0200

	current
Line 1:	Line 1:
	+	====== Creating a front-end page ======

	+	We just learned how to [[.:tutorial#premier-plugin\|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.
	+
	+	===== The _define.php file =====
	+
	+	<code php>
	+	<?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'
	+	);
	+	?>
	+	</code>
	+
	+	===== The _prepend.php file =====
	+
	+	First, we register the URL in the ''_prepend.php'' file :
	+	<code php>
	+	<?php
	+	if (!defined('DC_RC_PATH')) {return;}
	+
	+	# register the "publicexample" URL
	+	$core->url->register('publicexample','publicexample',
	+	'^publicexample(?:/(.+))?$',array('publicExampleDocument','page'));
	+	?>
	+	</code>
	+
	+	The parameters of the register function are :
	+	- the URL type, used by Dotclear to identify it
	+	- the base URL of the page
	+	- the URL regular expression
	+	- 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:
	+
	+	<code php>$core->blog->url.$core->url->getBase('publicexample')</code>
	+
	+	''publicexample'' is the URL type.
	+
	+	===== The _public.php file =====
	+
	+	==== Creating the page ====
	+
	+	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.
	+
	+	<code php>
	+	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');
	+	}
	+	}
	+	</code>
	+
	+	The ''$_ctx->publicExample'' is defined according to the ''$args'' value. It will be used later.
	+
	+	==== Tag declaration ====
	+
	+	See [[..:tpl\|Creation of a tpl tag for a plugin or a theme]] for more informations.
	+
	+	<code php>
	+	# 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); ?>');
	+	}
	+	}
	+	</code>
	+
	+	==== The complete _public.php file ====
	+
	+	<code php>
	+	<?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); ?>');
	+	}
	+	}
	+
	+	?>
	+	</code>
	+
	+	===== The template file =====
	+
	+	The template file public_page.html is ocated in the ''default-templates'' directory. It contains the following code:
	+
	+	<code html>
	+	<!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>
	+	</code>
	+
	+	It uses the the <code tpl>{{tpl:PublicExampleValue}}</code> tag that we defined in the _public.php file.
	+
	+	===== Download the example plugin =====
	+
	+	[[http://lab.dotclear.org/raw-attachment/wiki/plugin/publicExample/plugin-publicExample.zip\|plugin-publicExample.zip]]

2.0:resources:plugins:services

Wed, 16 Oct 2013 09:55:25 +0200

	current
Line 1:	Line 1:
	+	====== Create an Ajax service ======

	+	===== What is an Ajax service? =====
	+
	+	An Ajax service collects and returns data as an XML file. This service will be called dynamically via an Ajax request and will be processed by some Javascript to update a part of a Doctlear administration page. This is, for instance, what is used to display the list of tags when writing a post. When clicking __//See all tags//__ link, the associated Ajax service is called, returns the list of tags, and this list is displayed to the user.
	+
	+	===== Prerequisites =====
	+
	+	To create an Ajax service, you will need to:
	+	* Create a public and static PHP function. This function will be the one returning the expected results.
	+	* Declare the new service to Dotclear.
	+	* Call the service and process the data using Javascript.
	+
	+	<note>In the following part, we will create a service to dynamically display, on the post creation page, the time left before a scheduled post is put online.</note>
	+
	+	===== Service creation =====
	+
	+	The function name will be the service identifier. Be careful not to choose a name that is already used by another service. In our case, we will call it //getPostRemainingTime//.
	+
	+	<code php>
	+	<?php
	+
	+	class myPluginRestMethods
	+	{
	+	public static function getPostRemainingTime($core,$get)
	+	{
	+
	+	}
	+	}
	+
	+	?>
	+	</code>
	+
	+	<note>As a convention, we will write our services code in the [[files#general-organization-of-a-plugin\|_services.php]] file, in the plugin root. If you wish to use several services, they can all be written there.</note>
	+
	+	To retrieve the wanted information, we need the current post ID. We will get it using the id parameter that is passed in the URL. We also need the <php>$core</php> object to retrieve the post associated to this ID. In order to do this, we will use the parameters of the method defined earlier:
	+
	+	<code php>
	+	$id = isset($get['id']) ? $get['id'] : null;
	+
	+	$rs = $core->blog->getPost(array('post_id' => $id));
	+
	+	$date = strtotime($rs->post_dt);
	+
	+	# Time difference (in seconds) between now and the publication date
	+	$delta = $date - time();
	+	</code>
	+
	+	Now we have the information we need, it is possible to manipulate it to use the format we want. We can for instance pass the format we want as a parameter in the URL and convert the <php>$delta</php> accordingly. After that we have to return this data as an XML. For this, Dotclear has a special //xmlTags// class allowing to create this kind of structure very easily. As a convention, our responses will be encapsulated in a //rsp// node:
	+
	+	<code php>
	+	# Creation of the wrapper
	+	$rsp = new xmlTag();
	+	# Add the "value" node in the "rsp" node containing the $delta variable
	+	$rsp->value($delta);
	+
	+	# Return everything
	+	return $rsp;
	+	</code>
	+
	+	The generated XML file will look like this:
	+
	+	<code xml>
	+	<rsp status="ok">
	+	<value>65765432456</value>
	+	</rsp>
	+	</code>
	+
	+	<note>It is possible to add attributes to the node, and to combine them. For more details, you can check the other plugins using this system, or you can check Dotclear itself!</note>
	+
	+	===== Service declaration =====
	+
	+	Dotclear uses its own generic service dispatcher in the //services.php// file. To use it, the service has to be declared to Dotclear using the following method:
	+
	+	<code php>
	+	$core->rest->addFunction('getPostRemainingTime',array('myPluginRestMethods','getPostRemainingTime'));
	+	</code>
	+
	+	This code has to be put in the plugin [[files#general-organization-of-a-plugin\|_prepend.php]] file. Now our service is declared, we can access it throught the //ADMIN_URL/services.php?f=getPostRemainingTime&id=1// URL. Check if it works correctly before going further.
	+
	+	<note>Don't forget to load the _services.php file before declaring the service.</note>
	+
	+	===== Data processing =====
	+
	+	We will now go through the //Ajax// part of the service. The Javascript shown here will allow us to request data to the service and to display the response in the page without reloading it. We are going to use //jQuery//, which is bundled with Dotclear:
	+
	+	<code javascript>
	+	$(function(){
	+	$('#remaining-time').click(function(){
	+	$.get('services.php',
	+	{f: 'getPostRemainingTime',id: $('#id').val()},
	+	function(rsp){
	+	$('#remaining-time-display').html('<p>Remaining time before online publishing:'+$(rsp).find('value').text()+'</p>');
	+	});
	+	});
	+	});
	+	</code>
	+
	+	When clicking on the element with ID remaining-time, a request is made to the getPostRemainingTime service, passing the service we want to use and the current post ID (retrieved using the hidden id field of the form) as parameters. The response is displayed in the block with ID remaining-time-display.
	+
	+	===== Error handling =====
	+
	+	The code above does not handle errors that may happen when requesting the service. The advantage of using the //xmlTags// class to generate the XML is that if an exception is raised, the returned XML will look like:
	+
	+	<code xml>
	+	<rsp status="err">
	+	<message>Exception message</message>
	+	</rsp>
	+	</code>
	+
	+	For instance, for our service, if no ID is passed in parameter, we will raise an exception to inform the user:
	+
	+	<code php>
	+	$id = isset($_GET['id']) ? $_GET['id'] : null;
	+
	+	if ($id === null) {
	+	throw new Exception(__('No ID given'));
	+	}
	+	</code>
	+
	+	It is therefore very easy to catch this kind of XML to handle it differently. For instance:
	+
	+	<code javascript>
	+	$(function(){
	+	$('#remaining-time').click(function(){
	+	$.get('services.php',
	+	{f: 'getPostRemainingTime',id: $('#id').val()},
	+	function(data){
	+	var rsp = $(data).children('rsp')[0];
	+	if (rsp.attributes[0].value == 'ok') {
	+	$('#remaining-time-display').html('<p>Remaining time before online publishing:'+$(rsp).find('value').text()+'</p>');
	+	} else {
	+	alert($(rsp).find('message').text());
	+	}
	+	});
	+	});
	+	});
	+	</code>
	+
	+	This code will inform the user through an //alert()// message that an error appeared when requesting the service, or during the service processing.

2.0:resources:plugins:settings

Wed, 16 Oct 2013 09:55:25 +0200

	current
Line 1:	Line 1:
	+	====== Plugins parameters ======

	+	===== Saving a parameter =====
	+
	+	First, you need to select the //namespace// associated to the parameters with the ''setNameSpace()'' function:
	+
	+	<code php>
	+	$core->blog->settings->setNameSpace('example');
	+	</code>
	+
	+	<note>The setNamespace() argument should only contain letters (without accents) or numbers.
	+
	+	Allowed characters are [a-zA-Z][a-zA-Z0-9]</note>
	+
	+	Use the ''put()'' function to save a parameter. Its arguments are:
	+	- the parameter name (a string containing alphanumeric characters or underscore ''_'')
	+	- its value
	+	- its type (optional)
	+	- its label (optional)
	+	- wheter to overwrite the previous value or not (optional) (default value is true)
	+	- where the parameter is global or not (optional) (default value is false)
	+
	+
	+	==== Example with a string and a label ====
	+
	+	<code php>
	+	# we set the namespace
	+	$core->blog->settings->setNameSpace('example');
	+
	+	# we save the parameter
	+	$core->blog->settings->put('example',__('Hello World!'),'string','My label');
	+
	+	# we go back to the default namespace
	+	$core->blog->settings->setNameSpace('system');
	+	</code>
	+
	+	==== Parameters types ====
	+
	+	Saving a float:
	+
	+	<code php>
	+	$core->blog->settings->put('float',415618155.5181,'float');
	+	</code>
	+
	+	Saving an integer:
	+
	+	<code php>
	+	$core->blog->settings->put('integer',21767426,'integer');
	+	</code>
	+
	+	Saving a boolean:
	+
	+	<code php>
	+	$core->blog->settings->put('bool',true,'boolean');
	+	</code>
	+
	+	Saving a string:
	+
	+	<code php>
	+	$core->blog->settings->put('string',__('Hello World!'),'string');
	+	</code>
	+
	+	<note warning>
	+	To store a string containing more than one line, you should use the ''[[http://fr.php.net/manual/fr/function.base64-encode.php\|base64_encode()]]'' function when saving, and the ''[[http://fr.php.net/manual/fr/function.base64-decode.php\|base64_decode()]]'' when reading the parameter. This will prevent line break when editing the parameter with [[:2.0:admin:aboutconfig\|about:config]].
	+	</note>
	+
	+	===== Reading a parameter =====
	+
	+	A parameter is associated to the $core->blog->settings->parameter name variable, for example :
	+
	+	<code php>
	+	$string = $core->blog->settings->string;
	+	</code>
	+
	+	===== Deleting a parameter =====
	+
	+	You have to use the ''drop()'' function :
	+
	+	<code php>
	+	$core->blog->settings->setNameSpace('example');
	+
	+	$core->blog->settings->drop('example');
	+	</code>

2.0:resources:plugins:translate

Wed, 16 Oct 2013 09:55:25 +0200

1352197566		current
Line 1:		Line 1:
	====== Plugin Localization ======		====== Plugin Localization ======

		+	This page is about plugin localization, i.e. creation of a ''locales'' directory, a sub-directory per language and finally a ''main.po'' file that will contains the plugin translation in one language.
		+
		+	===== Localization files user guide =====
		+
		+	==== General process ====
		+
		+	Each plugin contains text that must be adaptable for every language and not simply hardcoded in the source code. To achieve this, files with a ''po'' extension are added. Once parsed by Dotclear2 engine, these files will replace codes like <code php><?php echo __('Maintenance'); ?></code> by the word or the sentence in the blog language. To do this, the plugin must have a translation in the given language. You will find below the detail of all the files used.
		+
		+	==== Files organization ====
		+
		+	=== The locales directory ===
		+
		+	The directory named locales contains one sub-directory per language the plugin is translated in. For instance it can contain:
		+
		+	* an en directory that will contain the English translation files
		+	* an es directory that will be for the Spanish version (optional)
		+	* etc.
		+
		+	==== The main.po file ====
		+
		+	Localization example:
		+
		+	<code>
		+	# French translation of DotClear
		+	# Copyright (C) 2006.
		+	# Olivier Meunier <olivier@dotclear.net>, 2006.
		+	#
		+	msgid ""
		+	msgstr "Content-Type: text/plain; charset=UTF-8\n"
		+	...
		+	#: plugins/maintenance/index.php:74
		+	#, php-format
		+	msgid "Indexing entry %d to %d."
		+	msgstr "Index des billets %d à %d"
		+	...
		+	</code>
		+
		+	The three first lines contain the translator comments:
		+	* The translation language,
		+	* The license associated to the file,
		+	* The author's name and e-mail address as well as the date of translation.
		+
		+	Let's break down this piece of code to define the use of each line:
		+
		+	<code>
		+	msgid ""
		+	msgstr "Content-Type: text/plain; charset=UTF-8\n"
		+	</code>
		+
		+	These two lines define the file format as well as the character encoding method. Here it's using text type and UTF-8 enconding.
		+
		+	<note>
		+	For more information on encondig: [[http://www.w3.org/International/O-HTTP-charset.en.php\|W3C website]]
		+	</note>
		+
		+	<code>
		+	#: plugins/maintenance/index.php:74
		+	</code>
		+
		+	This line indicates in which file the translation is used and in which line of that file it is used.
		+
		+	If the same translation is used several times, you just have to indicate all the lines like in the following example:
		+
		+	<code>
		+	#: plugins/maintenance/index.php:87 plugins/maintenance/index.php:111
		+	</code>
		+
		+	If it is really used a lot, you can also use the following syntax that fits on several lines:
		+
		+	<code>
		+	#: inc//core/class.dc.blog.php:1497 inc//core/class.dc.blog.php:1503
		+	#: inc//core/class.dc.blog.php:1565
		+	msgid "No such comment ID"
		+	msgstr "Identifiant du commentaire inconnu"
		+	</code>
		+
		+	Optionally, you can indicate that the translation contains PHP variables:
		+
		+	<code>
		+	#, php-format
		+	</code>
		+
		+	In this case, the %d is an integer PHP variable:
		+
		+	<code>
		+	msgid "Indexing entry %d to %d."
		+	</code>
		+
		+	<note warning>
		+	There are other types of variables. For instance to pass a string, you'll have to use %s instead of %d. For more information on variables and how to use them, please refer to the [[http://php.net/manual/en/function.sprintf.php\|PHP sprintf function documentation]].
		+	</note>
		+
		+	The msgid keyword associates a unique identifier to the translation. It is therefore important never to have the same identifier referring to two different translations.
		+
		+	<code>
		+	msgstr "Index des billets %d à %d"
		+	</code>
		+
		+	Finally the msgstr keyword contains the translation.
		+
		+	If we have a look at the index.php file, line 74... err 90 ;-):
		+
		+	<code php>
		+	echo '<p>'.sprintf(__('Indexing entry %d to %d.'),$start,$start+$limit).'</p>';
		+	</code>
		+
		+	Voici donc l'appel de la traduction. À la place de "%d to %d", elle contiendra le contenu des variables $start et $start+$limit.
		+	Here is where the translation is called. The two ''%d'' will be replaced by the content of $start and $start+$limit variables, respectively.
		+
		+	<note tip>
		+	As this example shows, the comment regarding the translation line is not correct anymore, many lines seems to have been added in the index.php file of the plugin. It is important to update the translation files when the plugin files containing texts to be translated are modified.
		+	</note>
		+
		+	Please also note that:
		+	* the msgid keyword cannot end with a space. For instance, "My string" will be found and replaced by its translation, but not "My string ".
		+	* there is a shell script to create a template, please check [[http://dev.dotclear.org/2.0/browser/locales/po_update.sh\|po_update.sh]]
		+	* there is a translation plugin called [[http://lab.dotclear.org/wiki/plugin/translater\|Translater]]
		+
		+	==== The public.po file ====
		+
		+	It is created the same way as the main.po file and will translate the strings that appear on the public side of the blog.
		+
		+	<note warning>
		+	Do not forget to add l10n::set(dirname(__FILE__).'/locales/'.$_lang.'/public'); in the theme/plugin _public.php file.
		+	</note>
		+
		+
		+	===== Exceptions for some plugins =====
		+
		+	Some plugins prefer the old methods used on Dotclear 1 or to mix both methods. These methods should not be used, therefore we'll only see them quickly.
		+
		+	==== The Dotclear 1 method ====
		+
		+	Peut être dans le but d'une adaptation rapide vers Dotclear2 tel que le plugin newsletter,
		+	Might have been done in order to quickly migrate to Dotclear 2, such as the [[http://lab.dotclear.org/wiki/plugin/newsletter\|newsletter plugin]].
		+
		+	=== The main.lang.php file ===
		+
		+	Same principle as Dotclear 2 except everything is on the same line and we don't know what files are calling it.
		+
		+	<code>$GLOBALS['__l10n']['Newsletter'] = 'Lettre d\'informations';</code>
		+
		+	<note tip>Les fichiers ''.lang.php'' sont traités plus rapidement que les fichiers ''.po''. Il est possible de créer les traductions dans un fichier ''.po'' puis de générer un fichier ''.lang.php'' correspondant.</note>
		+	<note tip>The ''.lang.php'' files are parsed faster than the ''.po'' files. It is possible to put the translations in a ''.po'' file then to generate the corresponding ''.lang.php'' file.</note>
		+
		+	==== Dotclear 1 & 2 method ====
		+
		+	Some plugins use both ''main.po'' and ''main.lang.php'' files.
		+
		+	<note tip>The ''main.lang.php'' file has the priority over the ''main.po'' file.
		+	If one of those is not available Dotclear 2 will chose the other, but by default it will use ''main.lang.php''.</note>
		+
		+	==== No translation ====
		+
		+	Some plugins do not use any files. Avoid this at all cost!

2.0:resources:plugins:tutorial

Wed, 16 Oct 2013 09:55:25 +0200

1175095730		current
Line 1:		Line 1:
-	====== Manuel de création de plugins pour Dotclear 2 ======	+	====== Writing a plugin for Dotclear 2 ======

	===== Introduction =====		===== Introduction =====

-	Les plugins sont des fragments applicatifs permettant d'ajouter des fonctionnalités à Dotclear, comme par exemple une liste de liens, un outil pour importer un blog depuis un autre logiciel ou encore une nouvelle syntaxe de rédaction des billets.	+	Plugins are pieces of code that add features to Dotclear, as for example a blogroll, a tool allowing import from another blogging software or a new syntax for writing posts.

-	La réalisation d'un plugin demande simplement des connaissances assez solides en PHP, notamment en programmation orientée objet. Dans la mesure du possible des liens vers des points précis de la documentation PHP seront fournis tout au long de ce manuel.	+	Writing a plugin requires solid PHP knowledge, in particular object-oriented programming. Whenever its needed, direct links to the PHP documentation will be included in this tutorial.

-	===== Premier plugin =====	+	===== First plugin =====

-	Nous allons réaliser un premier plugin qui ne sert à rien d'autre qu'afficher un texte sur la partie publique du blog. Nous y ajouterons ensuite quelques agréments permettant de survoler une bonne partie de ce que peuvent faire des plugins Dotclear.	+	We are going to write a plugin that will display a text on the blog front-end.

-	==== Définition d'un plugin ====	+	==== Definition of plugin ====

-	Un plugin est un répertoire se trouvant dans le répertoire des plugins (défini par DC_PLUGIN_ROOT). Nous allons donc créer un répertoire HelloWorld?. Dans ce répertoire, pour que le plugin existe, nous devons ajouter un fichier _define.php contenant le code suivant :	+	A plugin is a directory located in the plugins directory (defined by DC_PLUGIN_ROOT). We are going to create an HelloWorld directory. In this directory, for the plugin to exists, we have to add a _define.php file containing the following code:

	<code php>		<code php>
	<?php		<?php
		+	if (!defined('DC_RC_PATH')) { return; }
		+
	$this->registerModule(		$this->registerModule(
	/* Name */ "Hello World",		/* Name */ "Hello World",
Line 27:		Line 29:
	</code>		</code>

-	Les champs de la fonction registerModule sont accompagnés de commentaires afin de faciliter la lecture et l'édition du fichier _define.php. Tous ces champs sont simples à comprendre, nous nous arrêterons donc uniquement sur le champ Permissions. Ce champ prend une liste de permissions séparées par des virgules et ne sert que pour contrôler l'activation du plugin sur l'interface d'administration du blog. Si les permissions de l'utilisateur ne sont pas remplies, le plugin ne sera jamais chargé par l'interface d'administration.	+	All those fields are pretty simple to understand. Permissions takes a list of permissions and is used only to control the plugin activation. If the user doesn't have the rights, the plugin won't be load in the back-end.

-	Ici, nous décidons que le plugin sera chargé pour n'importe quel utilisateur pouvant se connecter sur l'interface d'administration, ce qui correspond aux droits //usage,contentadmin//. Si nous avions voulu restreindre ce plugin aux seuls administrateurs d'un blog donné, nous aurions assigné le droit //admin//.	+	We decided here that the plugin will be loaded for any user that can log in the back-end, which corresponds to the //usage,contentadmin// rights. For an administrator's only usage, we would have chosen the //admin// right.

	<note>		<note>
-	Notez bien que les droits définis correspondent à ceux pour le blog en cours d'utilisation. Si le plugin avait la permission //admin// et qu'un utilisateur soit administrateur sur un blog A mais uniquement rédacteur sur un blog B, le plugin ne serait actif que sur le blog A.	+	Note that defined rights only works for the current blog. If the plugin had the //admin// permission and a user was administrator on blog A, but only a redactor on blog B, the plugin would be only active on blog A.
	</note>		</note>

-	Enfin, si vous souhaitez rendre un plugin uniquement utilisable par les super-administrateurs la permission doit être mise à //null// (sans guillemets).	+	Finally, if you want to allow the plugin only to super-administrators, permission should be //null// (without quotes).

-	==== Structure d'un plugin ====	+	==== Organization of a plugin ====

-	Notre plugin ne sert pour l'instant à rien du tout. Pour lui faire réaliser des actions, nous devons définir d'autres fichiers.	+	Our plugin does, for now, nothing. We need to write other files for it to do something.

-	Un plugin possède deux autres fichiers (qui ne sont pas obligatoires selon les cas) :	+	A plugin contains 3 other files (not always required):

-	* _admin.php : définit le comportement du plugin sur l'interface d'administration.	+	* _admin.php : defines the plugin's behaviour in the administration panel.
-	* _public.php : définit le comportement du plugin sur le blog.	+	* _public.php : defines the plugin's behaviour on the front-end.
		+	* _prepend.php : defines files that have to be loaded.

-	Nous verrons le fichier _admin.php plus tard et allons nous concentrer sur _public.php.	+	We will study the _admin.php file later. For now, let's learn about the _public.php and _prepend.php files.

-	C'est grâce à lui que nous allons afficher un texte sur la partie publique du blog. Nous créons donc **_public.php avec le code suivant :**	+	**_prepend.php allows us to load files needed by the plugin.**

	<code php>		<code php>
	<?php		<?php
		+
		+	$__autoload['phpClassName'] = dirname(__FILE__).'/inc/class.name.of.the.class.php';
		+
		+	?>
		+	</code>
		+
		+	This file is also used for calling behaviors.
		+
		+	<note>
		+	A file can contain more than one class. In this case, you only need to include once the file, and use as a key for the $__autoload array the first class in the file. Other classes will be automatically loaded.
		+	</note>
		+
		+	<note>
		+	For more informations about a plugin organization, see [[http://fr.dotclear.org/documentation/2.0/resources/plugins/files\|cette page]]
		+	</note>
		+
		+	_public.php allows us to display a text on the front-end. We are going to write a _public.php file with the following code:
		+
		+	<code php>
		+	<?php
		+	if (!defined('DC_RC_PATH')) { return; }
		+
	$core->url->register('HelloWorld','HelloWorld','^HelloWorld$',array('HelloURL','HelloWorld'));		$core->url->register('HelloWorld','HelloWorld','^HelloWorld$',array('HelloURL','HelloWorld'));

Line 66:		Line 91:
	</code>		</code>

-	Ce code est court mais nous allons y préter toute notre attention. Nous venons d'ajouter une URL /HelloWorld (tout comme il existe /post/...) à notre blog.	+	Let's explain this code. We just added an URL to our blog : /HelloWorld (just like /post/...).

-	La fonction register de l'objet $core->url prend 4 paramètres :	+	The register function of the $core->url object takes 4 parameters :

-	* Un type, sorte d'identifiant unique de l'URL.	+	* A type, unique id for the url.
-	* La **forme de base de l'URL que l'on peut obtenir par** $core->url->getBase(<url>).	+	* The **URL base that can be obtain with** $core->url->getBase(<url>).
-	* Une expression rationnelle** permettant à l'interface publique de savoir quand réagir**.	+	* A **regular expression that indicated the front-end when to react**.
-	* La **fonction à appeler quand l'URL est reconnue. Cet argument peut-être n'importe quoi du moment qu'il s'agit d'une [[http://www.php.net/manual/fr/language.pseudo-types.php#language.types.callback\|déclaration de callback valide**]].	+	* The **function to call when the URL is detected. This argument can be anything as long as it's a [[http://www.php.net/manual/fr/language.pseudo-types.php#language.types.callback\|valid callback declaration**]].

-	Dans le cas qui nous intéresse, nous disons à Dotclear d'appeler la méthode statique HelloWorld de la class HelloURL quand il reconnaît l'URL /HelloWord sur le blog. L'URL en question a le type HelloWorld? et pourra être obtenue par $core->url->getType('HelloWorld').	+	In our case, Dotclear will call the static method HelloWorld contained in the HelloURL class when the URL /HelloWord is visited on the blog. This url has the HelloWorld? type and can be obtained with $core->url->getType('HelloWorld').

-	La méthode HelloWorld de la class HelloURL prend un seul argument : $args. Celui-ci contient l'éventuelle capture de l'expression rationnelle passée dans la définition de l'URL. Ici nous n'en avons pas, nous n'utilisons donc pas cet argument.	+	The HelloWorld method of the HelloUrl class takes only one argument : $args. It potentially contains the match of the regular expression defined before. Where, we didn't use one so we won't use this argument.

-	La méthode en elle-même est très simple, elle se contente de créer une page de type //text/plain// contenant les mots //Hello World//.	+	The method is quite simple : it creates a //text/plain// pages containing the words //Hello World//.

	<note>		<note>
-	La class HelloURL hérite de dcUrlHandlers. Dans notre cas, ce n'était pas nécessaire mais vous pouvez en avoir besoin si par exemple vous souhaitez envoyer une page d'erreur 404. Il suffirait alors d'appeler self::p404() pour obtenir immédiatement une page d'erreur 404 avec les bons en-têtes HTTP et le template correspondant.	+	The HelloURL class inherits from dcUrlHandlers. In our case, it wasn't necessary, but could be if you wanted to return an 404 error page for example. You would then only have to call self::p404() to immediately get a 404 error page with HTTP headers and template corresponding.
	</note>		</note>

-	Votre plugin fonctionne ? Bravo ! Nous allons maintenant voir comment lui apporter quelques améliorations.	+	Your plugin works ? Congratulation ! We will now improve it a little bit. [[admin\|Writing an administration page for a plugin]]

2.0:resources:plugins:widgets

Wed, 16 Oct 2013 09:55:25 +0200

1366257646		current
Line 148:		Line 148:

	<note>		<note>
-	The setting() method of the widget takes an additional parameter containing the data when it is a combo one.	+	The setting() method of the widget takes an additional parameter containing the data when it is a combo option.
	</note>		</note>