Forums / Developer / Tutorial: How to make module

Tutorial: How to make module

Author Message

Jerry Jalava

Sunday 27 July 2003 4:53:19 am

Hi,
I wrote this to another thread, but I think It's easier to find in here... Here is a small example of howto build your own module.
This version isn't as much documented as the first one that I wrote and lost...

In this example we make a module named "mymodule".
"mymodule" has 1 view called "list".
We have one template where we use fetch to list all our data from our database table called "mytable".

Folders and files:
-----------
In your ezpublish directory there is "extension"-folder (If not, create one).
Inside that folder we make folder for our module "mymodule".
Inside that folder we make folder structure like this:
(/extension/mymodule)/modules/mymodule
(extension/mymodule)/settings

The we create folder under the "standard" design.
/design/standard/templates/mymodule/

Inside folder: extension/mymodule/modules/mymodule,
we put all the files expect the "list.tpl" -file.

Inside folder: extension/mymodule/settings,
we put the module.ini.append file.

Inside folder: /design/standard/templates/mymodule/,
we will put the list.tpl -file.
-----------

1. Our module.ini.append file:
-----------
[ModuleSettings]
ExtensionRepositories[]=mymodule
-----------

2. The database:
-----------
We create a table named "mytable" to ez database and make 2 cells, "id" and "name".
We add some data to the table:
id name
1 First row
2 Second row
-----------

3. Our module.php file:
-----------
$Module = array( 'name' => 'mymodule' );

$ViewList = array();
$ViewList['list'] = array(
'script' => 'list.php',
"unordered_params" => array( "offset" => "Offset" ) );

What happens here is that we make a view "list" for the module,
witch points to file "list.php" and we send parameter "Offset" to it.
----------

4. Our list.php file:
----------
$Module =& $Params['Module'];

$Offset = $Params['Offset'];
if ( !is_numeric( $Offset ) )
$Offset = 0;

$viewParameters = array( 'offset' => $Offset );

include_once( 'kernel/common/template.php' );
$tpl =& templateInit();

$tpl->setVariable( 'view_parameters', $viewParameters );

$Result = array();
$Result['content'] = $tpl->fetch( "design:mymodule/list.tpl" );
$Result['path'] = array( array( 'url' => false,
'text' => 'MY Module' ),
array( 'url' => false,
'text' => 'List' ) );

In here we receive the parameters from module.php and send them forward to list.tpl with "setVariable" function.
Then we load the list.tpl to screen...
-----------

5. Our list.tpl file:
-----------
{let data_limit=10
data_list=fetch('mymodule','list',hash(offset,$view_parameters.offset,limit,$data_limit))}
<h1>All Data</h1>
{section name=DATA loop=$data_list sequence=array(bglight,bgdark)}
<b>{$:item.id}</b>{$:item.name}
{/section}
{/let}

Actually we don't need that "data_limit" and "hash(offset...)" thing in our example now,
but it's there just to show how the Offset parameter goes around the files...

Hint: {$:item.xxx} is the name of our database tables cell...
-----------

6. Our fetch function:
-----------
To archieve in this we need 2 files: mymodulefunctioncollection.php and function_definition.php.

First, function_definition.php
-----
$FunctionList = array();
$FunctionList['list'] = array(
'name' => 'list',
'operation_types' => array( 'read' ),
'call_method' => array( 'include_file' => 'extension/mymodule/modules/mymodule/mymodulefunctioncollection.php',
'class' => 'MyModuleFunctionCollection',
'method' => 'fetchList' ),
'parameter_type' => 'standard',
'parameters' => array( array( 'name' => 'offset',
'required' => false,
'default' => false ),
array( 'name' => 'limit',
'required' => false,
'default' => false ) ) );
-----

Second, mymodulefunctioncollection.php:
-----
include_once( 'extension/mymodule/modules/mymodule/mymodule.php' );

class MyModuleFunctionCollection
{

function MyModuleFunctionCollection()
{
}

function &fetchList( $offset, $limit )
{
$parameters = array( 'offset' => $offset,
'limit' => $limit );
$lista =& Mymodule::fetchListFromDB( $parameters );

return array( 'result' => &$lista );
}

}

-----

Third, mymodule.php:
-----
include_once( 'kernel/classes/ezpersistentobject.php' );

class Mymodule extends eZPersistentObject
{

function Mymodule( $row )
{
$this->eZPersistentObject( $row );
}

function &definition()
{
return array( 'fields' => array(
'id' => array(
'name' => 'id',
'datatype' => 'integer',
'default' => 0,
'required' => true ),
'name' => array(
'name' => 'name',
'datatype' => 'string',
'default' => '',
'required' => true ) ),
'keys' => array( 'id' ),
'increment_key' => 'id',
'class_name' => 'mymodule',
'name' => 'mytable' );
}

function &fetchListFromDB( $parameters = array() )
{
return Mymodule::handleList( $parameters, false );
}

function &handleList( $parameters = array(), $asCount = false )
{
$parameters = array_merge( array( 'as_object' => true,
'offset' => false,
'limit' => false ),
$parameters );
$asObject = $parameters['as_object'];
$offset = $parameters['offset'];
$limit = $parameters['limit'];
$limitArray = null;
if ( !$asCount and $offset !== false and $limit !== false )
$limitArray = array( 'offset' => $offset,
'length' => $limit );

return eZPersistentObject::fetchObjectList( Mymodule::definition(),
null, null, null, $limitArray,
$asObject );
}

}
-----

Now we just login to our admin site and goto url: /mymodule/list.
We see our list.tpl showing the 2 variables from the database... (Hopefully)

I'm sorry but I cannot write anymore notes right now... I'm too tired. (And still pissed,
because I lost the original example what I was writing... It had a lot more notes and hints...)

Hope this helps,
Jerry

liu spider

Sunday 27 July 2003 8:05:15 am

I think a better place this kind of article should be is the documentation areas ;)

http://liucougar.scim-im.org
SCIM Input Method Platform
http://scim.sf.net
SJSD Online Editor
http://sf.net/projects/sjsd

Jerry Jalava

Sunday 27 July 2003 8:38:29 am

Yes, I will add it there after it's complete... ;)
I have to add few views more and few functions more and improve the documentation of the tutorial...

Regards,
Jerry

Tony Wood

Sunday 27 July 2003 12:41:41 pm

Nice going, I look forward to reading the article.

Tony

Tony Wood : twitter.com/tonywood
Vision with Technology
Experts in eZ Publish consulting & development

Power to the Editor!

Free eZ Training : http://www.VisionWT.com/training
eZ Future Podcast : http://www.VisionWT.com/eZ-Future

liu spider

Sunday 27 July 2003 8:51:26 pm

After you submit you still can edit your article in Documentation, so I deem it can be submitted right now ;)

Another thing I want to mention is that a tutorial should keep simply and clear: a too complex one may not be easily catched up with.

So I think you can split your tutorial into several parts, the first only gives out a minimal framework, and add a function/view to it in each of the subsequent series.

http://liucougar.scim-im.org
SCIM Input Method Platform
http://scim.sf.net
SJSD Online Editor
http://sf.net/projects/sjsd

Jerry Jalava

Monday 28 July 2003 12:59:52 am

Hi,

I now contributed my first documentation page... The layuot of the document ain't at it's best yet, 'cause I don't know how should I make those "code tables"... I haven't used that editor before...

But, here it is: http://www.ez.no/developer/ez_publish_3/documentation/development/extensions/module/module_tutorial_part_1

Regards,
Jerry

liu spider

Monday 28 July 2003 7:58:37 am

Ok, I have edited your article, adding code blocks and some source indents.

http://liucougar.scim-im.org
SCIM Input Method Platform
http://scim.sf.net
SJSD Online Editor
http://sf.net/projects/sjsd

Jerry Jalava

Monday 28 July 2003 8:26:07 am

Thanks Liu,
By the way, how can I add those in the editor? Just for future...

Thanks,
Jerry

liu spider

Monday 28 July 2003 8:51:53 pm

Just click the Edit button in the top-right of that page, and you'll see all my changes ;)

http://liucougar.scim-im.org
SCIM Input Method Platform
http://scim.sf.net
SJSD Online Editor
http://sf.net/projects/sjsd