How to: Develop your first block
This document explains the basic part of how to develop blocks. To practice this document, you need your first module like sample modules which are explained here.
Declare blocks in xoops_version
Blocks have to be recognized as Legacy's resources. For that, you need declare your blocks in xoops_version of your module. That's complex a little, because the format has to include the compatibility format for XOOPS2.
$modversion['blocks'][1]['func_num'] = 1;
$modversion['blocks'][1]['file'] = "LatestArticleBlock.class.php";
$modversion['blocks'][1]['name'] = "Latest Article Blocks";
$modversion['blocks'][1]['description'] = "Show Latest Articles";
$modversion['blocks'][1]['class'] = "LatestArticleBlock";
$modversion['blocks'][1]['options'] = "";
$modversion['blocks'][1]['template'] = 'mymodule_latest_articles.html';
One block have to be contained into one factor of $modversion['blocks']. And, other informations are the following.
func_num | An identification number of blocks that you have to manage. It has to start from 1, and be running number. |
file | A name of a file including code which defines classes about your blocks. This file has to be under blocks directory of your module's root. |
name | A name of the block. You should define this with constants in modinfo.php of languages. |
description | A brief of the block. You should define this with constants in modinfo.php of languages. |
class | A base name of the class extending Legacy_AbstractBlockProcedure. This class has to be defined in the file you specified. |
options | Say later |
template | A name of template file used by this block. This file has to be under the template/blocks directory of your module's root. |
Define the class implementing Legacy_AbstractBlockProcedure
You have to define a sub class of Legacy_AbstractBlockProcedure and implement the logic of your block. When Legacy executes the block process, it generates an instance of your class declared in xoops_version and calls some methods of the instance.
Legacy_AbstractBlockProcedure defines many methods as interfaces which exchange informations with Legacy_Controller to process blocks. To answer requests of Legacy about blocks, you have to implement many methods. But, Legacy offers some standard sub-classes to module developers. These classes are easy to use. By these classes, you can implement your class quickly.
Legacy_BlockProcedure is one of them. With this class, you can complete implementation by writing one method only.
class MyModule_LatestArticleBlock extends Legacy_BlockProcedure
{
function execute()
{
// Write your code.
}
}
Implement required methods
Finally, Legacy_Controller gets the render buffer including the output of the block by getRenderTarget(). This method manages an instance of the render-target. Therefore, you just have to get the instance by getRenderTarget() and renders it with RenderSystem.
The process in blocks doesn't have its own module as the current module. You must pay attention to it. In other words, you may not use xoops_getmodulehandler() correctly. When you use this method, you have to specify the second parameter which is a dirname of module.
function execute()
{
// At first, get RenderTarget through the helper method.
$renderTarget =& $this->getRenderTarget();
// Process lime modules
$handler =& xoops_getmodulehandler('articles', 'mymodule');
$criteria =& new Criteria('is_public', 1);
$criteria->addSort('publish_date', 'DESC');
$criteria->setLimit(10);
$articles =& $handler->getObjects($criteria);
$renderTarget->setTemplateName('mymodule_latest_articles.html');
$renderTarget->setAttribute('articles', $articles);
// Get the render system, and render the target with it.
$root =& XCube_Root::getSingleton();
$renderSystem =& $root->getRenderSystem($this->getRenderSystemName());
$renderSystem->renderBlock($renderTarget);
}
Page Info | |
---|---|
Page Name : | XOOPSCubeLegacy/ProgrammingGuide/Block/HowToDevelopFirstBlock |
Page aliases : | None |
Page owner : | Anonymous |
Can Read | |
Groups : | All visitors |
Users : | All visitors |
Can Edit | |
Groups : | Support Site Webmasters |
Users : | No one |