Writing a Block Plugin - Revision history

Jmacgreg: /* A Basic Block Plugin */

2011-05-02T03:39:28Z

‎A Basic Block Plugin

Mcrider at 19:06, 3 April 2009

2009-04-03T19:06:53Z

Mcrider at 19:05, 3 April 2009

2009-04-03T19:05:21Z

Mcrider at 19:02, 3 April 2009

2009-04-03T19:02:36Z

Mcrider at 18:40, 3 April 2009

2009-04-03T18:40:44Z

Mcrider at 17:48, 3 April 2009

2009-04-03T17:48:53Z

Mcrider at 17:27, 3 April 2009

2009-04-03T17:27:52Z

Mcrider: New page: =OJS Block Plugin Development Guide= '''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 ...

2009-04-03T17:27:09Z

New page: =OJS Block Plugin Development Guide= '''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 ...

New page

=OJS Block Plugin Development Guide=

'''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 [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.

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:
# Rename ''DevelopedByBlockPlugin.inc.php'' to ''MyPlugin.inc.php''.
# 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.
#:<pre>@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</pre>
#*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''
# 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();'''
# 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.
#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).

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 that function 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:

<pre>function getContents(&$templateMgr) {
$templateMgr->assign('isAdmin', Validation::isSiteAdmin());
return parent::getContents($templateMgr);
}</pre>
You can now call the ''$isAdmin'' variable anywhere in your block.tpl template, for example
<pre>{if $isAdmin}
<h1>Smile, you're an admin!</h1>
{/if}</pre>

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 [http://pkp.sfu.ca/support/forum/viewforum.php?f=28 plugin gallery]!

@@ Line 41: / Line 41: @@
 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) {

@@ Line 39: / Line 39: @@
 ===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.

@@ Line 34: / Line 34: @@
 #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).
 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 1: / Line 1: @@
 ===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.
@@ 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:
-# 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:
 #* Edit the comments at the top of the file to reflect your new plugin name, e.g.

@@ Line 13: / Line 13: @@
 # 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.
-#:<pre>@file MyPluginBlockPlugin.inc.php
+#:<pre>   @file MyPluginBlockPlugin.inc.php
 #:
 #:Copyright (c) 2009 George Clinton
@@ Line 32: / 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.
 #* 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).

@@ Line 20: / Line 20: @@
 #:@class MyPluginBlockPlugin
 #:@ingroup plugins_blocks_myPlugin
 #:@brief Class for "myPlugin" block plugin</pre>
 #*Change the class name from ''DevelopedByBlockPlugin'' to ''MyPluginBlockPlugin''

@@ Line 1: / Line 1: @@
-=OJS Block Plugin Development Guide=
+===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.
@@ Line 9: / Line 7: @@
 Note: These instructions reference OJS, but are just as applicable to OCS and Harvester.
-'''A Basic Block Plugin'''
+===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:
@@ Line 40: / Line 38: @@
 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'''
+===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.