Difference between revisions of "Writing a Block Plugin"

From PKP Wiki
Jump to: navigation, search
(A Basic Block Plugin)
 
(5 intermediate revisions by one user not shown)
Line 1: Line 1:
 
===Introduction===
 
===Introduction===
  
In recent versions of OJS and OCS, the content in the sidebars of each page is comprised of block plugins, allowing users to move each block around the page using the setup interface (instead of having to modify the template code).  Each block, or piece of content, exists as its own directory in the plugins/blocks/ directory, and creating a new block is as easy as duplicating an existing directory and customizing its contents.
+
In recent versions of OJS and OCS, the content in the sidebars of each page is comprised of block plugins, allowing users to move each block around the page using the setup interface (instead of having to modify the template code).  Each block, or piece of content, exists as its own directory in the ''plugins/blocks/'' directory, and creating a new block is as easy as duplicating an existing directory and customizing its contents.
  
 
For simple block plugins that only contain HTML and images, we recommend using Juan Pablo Alperin's excellent [http://pkp.sfu.ca/support/forum/viewtopic.php?f=28&t=3459&p=12801&hilit=blocks#p12801 Custom Block Manager] that automates the process of creating simple block plugins.  For educational purposes, this guide will continue to describe how to create a simple block plugin by hand, then give some tips on making your block more dynamic and powerful.
 
For simple block plugins that only contain HTML and images, we recommend using Juan Pablo Alperin's excellent [http://pkp.sfu.ca/support/forum/viewtopic.php?f=28&t=3459&p=12801&hilit=blocks#p12801 Custom Block Manager] that automates the process of creating simple block plugins.  For educational purposes, this guide will continue to describe how to create a simple block plugin by hand, then give some tips on making your block more dynamic and powerful.
Line 10: Line 10:
  
 
The simplest block plugin to start off with is the ''developedBy'' plugin.  To create your new block, duplicate the developedBy directory in ''plugins/blocks/'' and rename it to whatever you like (let's call it ''myPlugin'').  Then make the following modifications:
 
The simplest block plugin to start off with is the ''developedBy'' plugin.  To create your new block, duplicate the developedBy directory in ''plugins/blocks/'' and rename it to whatever you like (let's call it ''myPlugin'').  Then make the following modifications:
# Rename ''DevelopedByBlockPlugin.inc.php'' to ''MyPlugin.inc.php''.
+
# Rename ''DevelopedByBlockPlugin.inc.php'' to ''MyPluginBlockPlugin.inc.php''.
 
# Open ''MyPluginBlockPlugin.inc.php'' and make the following adjustments:
 
# Open ''MyPluginBlockPlugin.inc.php'' and make the following adjustments:
 
#* Edit the comments at the top of the file to reflect your new plugin name, e.g.
 
#* Edit the comments at the top of the file to reflect your new plugin name, e.g.
#:<pre>@file MyPluginBlockPlugin.inc.php
+
#:<pre>   @file MyPluginBlockPlugin.inc.php
 
#:
 
#:
 
#:Copyright (c) 2009 George Clinton
 
#:Copyright (c) 2009 George Clinton
Line 20: Line 20:
 
#:@class MyPluginBlockPlugin
 
#:@class MyPluginBlockPlugin
 
#:@ingroup plugins_blocks_myPlugin
 
#:@ingroup plugins_blocks_myPlugin
#:
 
 
#:@brief Class for "myPlugin" block plugin</pre>
 
#:@brief Class for "myPlugin" block plugin</pre>
 
#*Change the class name from ''DevelopedByBlockPlugin'' to ''MyPluginBlockPlugin''
 
#*Change the class name from ''DevelopedByBlockPlugin'' to ''MyPluginBlockPlugin''
Line 33: Line 32:
 
#* Change the ''displayName'' and ''description'' values as appropriate.  If you want to add new text to your plugin, you can add new message keys and values here, and reference them in your templates using the Smarty {translate} function.
 
#* Change the ''displayName'' and ''description'' values as appropriate.  If you want to add new text to your plugin, you can add new message keys and values here, and reference them in your templates using the Smarty {translate} function.
 
#* Repeat the process for any other languages you can translate to.  If you can't translate the plugin to a particular language, it is best to delete the directory for that language so that users of that language will not see incorrect information.
 
#* Repeat the process for any other languages you can translate to.  If you can't translate the plugin to a particular language, it is best to delete the directory for that language so that users of that language will not see incorrect information.
#Don't worry about '''settings.xml''', it should be fine as it is.
+
#Don't worry about ''settings.xml'', it should be fine as it is.
 
#Open up ''plugins/block/myPlugin/block.tpl'' -- This is the Smarty template that will display the content of your plugin.  You can pretty much write straight HTML in here, but you can also harness the power of Smarty (http://www.smarty.net), which is necessary for e.g. localizing the text of the plugin (using the {translate} function).  For any dynamic content, you will have to make use of smarty functions and template variables, and likely also some PHP (introduced in the next section).
 
#Open up ''plugins/block/myPlugin/block.tpl'' -- This is the Smarty template that will display the content of your plugin.  You can pretty much write straight HTML in here, but you can also harness the power of Smarty (http://www.smarty.net), which is necessary for e.g. localizing the text of the plugin (using the {translate} function).  For any dynamic content, you will have to make use of smarty functions and template variables, and likely also some PHP (introduced in the next section).
 +
#Open up "plugins/blocl/myPlugin/version.xml". This file contains version and plugin description information that must be fed into the OJS database. You will wan to change the following:
 +
#* change the <application>...</application> value from "developedBy" to "myPlugin";
 +
#* change the <date>...</date> value from eg. 2009-07-13 to the current date (in YYYY-MM-DD format);
 +
#* change the <class>...</class> value from developedByBlockPlugin to MyPluginBlockPlugin.
 +
# You will then need to register the plugin in the OJS database. You can do this by running the following from your OJS root directory on your server:
 +
php tools/upgrade.php upgrade
  
 
Start up OJS, go to Journal Setup Step 5.6, and ensure that your plugin exists in the list and is in the right vertical position.  Behold, your first OJS plugin!
 
Start up OJS, go to Journal Setup Step 5.6, and ensure that your plugin exists in the list and is in the right vertical position.  Behold, your first OJS plugin!
Line 40: Line 45:
 
===Advanced Block Plugins===
 
===Advanced Block Plugins===
  
Making dynamic block plugins will require some knowledge of Smarty and also probably some PHP.  Your best source of information is the other block plugins--A good next step is to look at the user block plugin.  The block.tpl file in that directory provides examples of how to create links to other pages in your system using the Smarty {url} function, and also how to use template variables that have been assigned to the template.   
+
Making dynamic block plugins will require some knowledge of Smarty and also probably some PHP.  Your best source of information is the other block plugins--A good next step is to look at the ''user'' block plugin.  The block.tpl file in that directory provides examples of how to create links to other pages in your system using the Smarty {url} function, and also how to use template variables that have been assigned to the template.   
  
For example, a commonly used template variable is ''$isUserLoggedIn''.  This variable is global, or assigned to all templates in the constructor function of ''classes/template/TemplateManger.inc.php''.  You can look through that function to find other global template variables by looking at other assigned variables in that function.     
+
For example, a commonly used template variable is ''$isUserLoggedIn''.  This variable is global, or assigned to all templates in the constructor function of ''classes/template/TemplateManger.inc.php''.  You can look through here to find other global template variables by looking at other assigned variables in that function.     
  
Non-global variables are assigned to the plugin in the ''getContents()'' function of the plugin's class file.  Your myPlugin class does not have one, so you'll have to create one to be able to assign plugins to your plugin.  Here is a basic example:
+
Non-global variables are assigned to the plugin in the ''getContents()'' function of the plugin's class file.  Your myPlugin class does not have one, so you'll have to create one to be able to assign variables to your plugin.  Here is a basic example:
  
 
<pre>function getContents(&$templateMgr) {
 
<pre>function getContents(&$templateMgr) {

Latest revision as of 19:39, 1 May 2011

Introduction

In recent versions of OJS and OCS, the content in the sidebars of each page is comprised of block plugins, allowing users to move each block around the page using the setup interface (instead of having to modify the template code). Each block, or piece of content, exists as its own directory in the plugins/blocks/ directory, and creating a new block is as easy as duplicating an existing directory and customizing its contents.

For simple block plugins that only contain HTML and images, we recommend using Juan Pablo Alperin's excellent Custom Block Manager that automates the process of creating simple block plugins. For educational purposes, this guide will continue to describe how to create a simple block plugin by hand, then give some tips on making your block more dynamic and powerful.

Note: These instructions reference OJS, but are just as applicable to OCS and Harvester.

A Basic Block Plugin

The simplest block plugin to start off with is the developedBy plugin. To create your new block, duplicate the developedBy directory in plugins/blocks/ and rename it to whatever you like (let's call it myPlugin). Then make the following modifications:

  1. Rename DevelopedByBlockPlugin.inc.php to MyPluginBlockPlugin.inc.php.
  2. Open MyPluginBlockPlugin.inc.php and make the following adjustments:
    • Edit the comments at the top of the file to reflect your new plugin name, e.g.
       @file MyPluginBlockPlugin.inc.php
    
    Copyright (c) 2009 George Clinton
    Distributed under the GNU GPL v2. For full terms see the file docs/COPYING.
    @class MyPluginBlockPlugin
    @ingroup plugins_blocks_myPlugin
    @brief Class for "myPlugin" block plugin
    • Change the class name from DevelopedByBlockPlugin to MyPluginBlockPlugin
    • Change the return value of the getName() function from DevelopedByBlockPlugin to MyPluginBlockPlugin
    • Change the return value of the getDisplayName() and getDescription() functions from plugins.block.developedBy.x to plugins.block.myPlugin.x
  3. Modify plugins/blocks/myPlugin/index.php
    • Change the comments so they reflect the modifications in MyPluginBlockPlugin.inc.php
    • Change require_once('DevelopedByBlockPlugin.inc.php'); to require_once('MyPluginBlockPlugin.inc.php');
    • Change return new DevelopedByBlockPlugin(); to return new MyPluginBlockPlugin();'
  4. Change the locale files for the plugin. Assuming you want it in English, open plugins/block/myPlugin/locale/en_US/locale.xml
    • Change the locale keys from plugins.block.developedBy.x to plugins.block.myPlugin.x
    • Change the displayName and description values as appropriate. If you want to add new text to your plugin, you can add new message keys and values here, and reference them in your templates using the Smarty {translate} function.
    • Repeat the process for any other languages you can translate to. If you can't translate the plugin to a particular language, it is best to delete the directory for that language so that users of that language will not see incorrect information.
  5. Don't worry about settings.xml, it should be fine as it is.
  6. Open up plugins/block/myPlugin/block.tpl -- This is the Smarty template that will display the content of your plugin. You can pretty much write straight HTML in here, but you can also harness the power of Smarty (http://www.smarty.net), which is necessary for e.g. localizing the text of the plugin (using the {translate} function). For any dynamic content, you will have to make use of smarty functions and template variables, and likely also some PHP (introduced in the next section).
  7. Open up "plugins/blocl/myPlugin/version.xml". This file contains version and plugin description information that must be fed into the OJS database. You will wan to change the following:
    • change the <application>...</application> value from "developedBy" to "myPlugin";
    • change the <date>...</date> value from eg. 2009-07-13 to the current date (in YYYY-MM-DD format);
    • change the <class>...</class> value from developedByBlockPlugin to MyPluginBlockPlugin.
  8. You will then need to register the plugin in the OJS database. You can do this by running the following from your OJS root directory on your server:
php tools/upgrade.php upgrade

Start up OJS, go to Journal Setup Step 5.6, and ensure that your plugin exists in the list and is in the right vertical position. Behold, your first OJS plugin!

Advanced Block Plugins

Making dynamic block plugins will require some knowledge of Smarty and also probably some PHP. Your best source of information is the other block plugins--A good next step is to look at the user block plugin. The block.tpl file in that directory provides examples of how to create links to other pages in your system using the Smarty {url} function, and also how to use template variables that have been assigned to the template.

For example, a commonly used template variable is $isUserLoggedIn. This variable is global, or assigned to all templates in the constructor function of classes/template/TemplateManger.inc.php. You can look through here to find other global template variables by looking at other assigned variables in that function.

Non-global variables are assigned to the plugin in the getContents() function of the plugin's class file. Your myPlugin class does not have one, so you'll have to create one to be able to assign variables to your plugin. Here is a basic example:

function getContents(&$templateMgr) {
	$templateMgr->assign('isAdmin', Validation::isSiteAdmin());
	return parent::getContents($templateMgr);
}

You can now call the $isAdmin variable anywhere in your block.tpl template, for example

{if $isAdmin}
	<h1>Smile, you're an admin!</h1>
{/if}

More complex assignments will require a deeper knowledge of OJS. Consult the various technical guides, API references, and source code for more information on that.


We hope that you will choose to share your plugin with the rest of the community--Please upload them to the plugin gallery!