![[Main Page]](/modules/mediawiki/images/mediawiki.png)
Contents |
Tutorial
TO: Forum Pool
Kaotik Index
- Basic content of a module
- using Smarty templates in a module
- Building an AJAX module
- Xoops Blocks
- Guidelines for Module Development
- Theme Development
- $_SUPER GLOBALS
- DB Operations and Classes
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.
|
Download and install the completed module from Part 3. |
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.
HELPER TIP
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:
<?php
function tut_blockList(){
$block=array();
$block['mytext']="Hello world! This is my new Block!";
return $block;
}
?>
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.
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:
<?php
function tut_blockList($options){
$block=array();
$block['textOne']=$options[0];
$block['textTwo']=$options[1];
return $block;
}
function tut_blockList_edit($options){
$form = "Option 1: <input type='text' size='9' name='options[0]' value='$options[0]' />";
$form .= "
";
$form .= "Option 2: <input type='text' size='1' name='options[1]' value='$options[1]' />";
$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:
<p>My First option is: <{$block.textOne}></p>
<p>My Second option is: <{$block.textTwo}></p>
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.
|
Completed module from part 4. Check to see if your code matches. |
Completed Module from part 4 |
