Part 4 - Xoops Blocks

Part 1 Building a simple module
[ Part 2 - using Smarty templates in a module]
Part 3 - Building an AJAX module
Xoops blocks are an important part for any module, however they aren't easy to learn, especially block options, so I've written this tutorial to help.

Missing image: Tutorial.png
Completed Module from part 3

A xoops block has 2 distinct zones to it:
1- A php function. This controls what happens in the block.
2- A smarty template. This gives the block it's "design".
This is all defined in xoops_version.php so let's start there

Step 1 - Setting up a xoops block in xoops_version.php

Open tutorial/xoops_version.php. Add the following code at the end of the file, right BEFORE ?> // Blocks $modversion['blocks'][1]['file'] = "tutorial_block.php"; $modversion['blocks'][1]['name'] = 'Block for Tutorial'; $modversion['blocks'][1]['description'] = 'This is a Block for the tutorial module'; $modversion['blocks'][1]['show_func'] = "tut_blockList"; $modversion['blocks'][1]['template'] = 'tutorial_block.html'; $modversion['blocks'][1]['file'] = "tutorial_block.php"; This first line tells xoops which file has our php function that will control this block. 1 file can hold several functions. I normally place all my functions inside a single file, unless those functions are really big due to code. In that case it would be better to separate functions into several files. $modversion['blocks'][1]['name'] = 'Block for Tutorial'; This is the name that will show above our block. For good Xoops coding standards you should use a language constant instead of writing the name directly here. I've done it this way for easier understanding. $modversion['blocks'][1]['description'] = 'This is a Block for the tutorial module'; This one is self-explanatory, the block description. This basicly only appears in the block management part. $modversion['blocks'][1]['show_func'] = "tut_blockList"; This is the actual php function that will control our block. As a rule of thumb, always append an abreviation of your module name to this function so that it doesn't colide with other functions in xoops. Function names that sound logical tend to be used a lot by diferent developers. I've run into this problem before, so has Hervet with his excelent News module, just to name 2 of us. $modversion['blocks'][1]['template'] = 'tutorial_block.html'; This is the smarty template part of my function.

When creating templates and blocks in xoops_version.php. You start numbering as:
// Templates $modversion['templates'][1]['file'] = 'tut_form.html'; $modversion['templates'][1]['description'] = ''; $modversion['templates'][2]['file'] = 'tut_client_list.html'; $modversion['templates'][2]['description'] = ''; $modversion['templates'][3]['file'] = 'tut_main.html'; $modversion['templates'][3]['description'] = ''; Now let's suppose you need to insert a template between number 2 and 3? With a small number of templates, changing the numbering would be relativly easy, but for a large module; say with 40 templates or more, this would be a real pain in the butt. So how do you solve this? Easy, using a helper variable (I will refer to variable as var from now on):
// Templates $i=1; $modversion['templates'][$i]['file'] = 'tut_form.html'; $modversion['templates'][$i]['description'] = ''; $i++; $modversion['templates'][$i]['file'] = 'tut_client_list.html'; $modversion['templates'][$i]['description'] = ''; $i++; $modversion['templates'][$i]['file'] = 'tut_main.html'; $modversion['templates'][$i]['description'] = ''; $i++; So now I can easily add more templates inbetween existing templates without worring about their numbering. I let $i take care of the numbers. It starts at 1 ($i=1;)and adds 1 ($i++;) after each template.

Step 2 - Creating the necessary files.

Lets create 2 directories: tutorial/blocks tutorial/templates/blocks Inside directory tutorial/blocks create a file called tutorial_block.php with the following code in it: There are a couple of notes about this function:

  • A block function must ALWAYS return a var called $block.
  • $block must ALWAYS be an array.
  • You can place as much info inside the array as you want, even associative arrays.
  • Block functions can be called outside of their module "homebase". If you have included (or required) files from your module, always be certain that your blocks know where those files are.

Inside directory tutorial/templates/blocks create a file called tutorial_block.html with the following code in it: <{$block.mytext}> Now let's go to module administration and update the tutorial module, so that Xoops processes our new block. Now go to block administration and make block 'Block for Tutorial' visible on the front page. Go to your xoops front page to see your new block.

''Excelente! You've created your first block!''

Step 3 - Creating Block options

This is a tricky subject. When done properly it can give your blocks a lot of flexibility.
Open tutorial/xoops_version.php and INSERT these 2 lines in red: // Blocks $modversion['blocks'][1]['file'] = "tutorial_block.php"; $modversion['blocks'][1]['name'] = 'Block for Tutorial'; $modversion['blocks'][1]['description'] = 'This is a Block for the tutorial module'; $modversion['blocks'][1]['show_func'] = "tut_blockList"; $modversion['blocks'][1]['template'] = 'tutorial_block.html'; $modversion['blocks'][1]['edit_func'] = "tut_blockList_edit"; $modversion['blocks'][1]['options'] = 'Hello|1'; The first line tells Xoops which function controls the editing part of this block. This function must be in the same file, in this case tutorial_block.php. The second line provides xoops with the default values for the block options. In this example the block will have 2 options, one will have a default value of "Hello" and the other "1". What separates the values here is '|'. Open tutorial/blocks/tutorial_block.php Replace all code with this: $options){ $block=array(); $block['textOne']=$options[0]; $block['textTwo']=$options[1]; return $block; } function tut_blockList_edit($options){ $form = "Option 1: "; $form .= "
"; $form .= "Option 2: "; $form .= "
"; return $form; }
?> We now have a function tut_blockList_edit) that controls block options. The first function tut_blockList now receives our options $options) from xoops.
A couple of notes:

  • The options function (in this case tut_blockList_edit)must ALWAYS return a var called $form.
  • $form is always a string and never an array.
  • You can create as many options as you like.
  • Xoops saves them in it's own database structure so you don't have to worry about creating tables for them. This is actually very good since you don't have to worry tables, saving or updating.
  • $form must always contain form elements named 'options'.
  • options ALWAYS has to start with 0, for ex: name='options[0]'.

Open tutorial/templates/blocks/tutorial_block.html and replace the code with this:

My First option is: <{$block.textOne}>

My Second option is: <{$block.textTwo}>

Ok. Now we need to reinstall the tutorial module so that Xoops creates the necessary changes for our block options.
With the module reinstalled, go to block administration. Make our tutorial block visible on the front page. Now click on edit next to the block. You will see two options; one says 'Hello' and the other says '1'. Replace 'Hello' with 'I like Xoops' and '1' with '5'. Now goto the front page.

Missing image: Tutorial.png
Completed Module from part 4

Category: Getting Started <[Languages |Module Blocks]>

Last modified on 2010/11/28 by Anonymous
The comments are owned by the poster. We aren't responsible for their content.