XOOPSCubeLegacy​/ProgrammingGuide​/Block​/HowToDevelopFirstBlock

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.

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);
}

Write templates

<ul>
<{foreach item=article from=$articles}>
  <li><{$article->getShow('title')}></li>
<{/foreach}>
</ul>