Creating Custom Admin Modules & Views

Passing parameters to Views

A simple requirement asked when dealing with newsletters is the ability to remove users from the mailing list. Let’s add that functionality to our view to allow admin users to remove a user from the mailing list by clicking on a link alongside the email address of each user. This will allow us to demonstrate how we can pass and handle parameters with Views.

Accounting for Parameters

Parameters being sent to the page need to be specified within the module.php file so our first step is to return to ours and add the parameters to the file (/extension/mynewsletter/modules/newsletter/module.php).

There are two types of parameters within eZ Publish and both are accessed in the same way. The only difference is how they appear in the URL and where they are defined in module.php. To remove a user from the mailing list we just need to supply one parameter into our view which will be the user ID of the user to remove from the mailing list. Let’s see how we would do this with both types of parameter.

Ordered Parameters

These always come first out of the two types. When declaring ordered parameters the name of the parameter does not appear in the URL. For example, if the user ID of the user we were removing from our mailing list was 42 the parameter would appear as follows if it was ordered:

http://www.yoursite.com/admin/newsletter/userlist/42

If we were to declare the parameter in the module.php file this is how our view declaration would be written:

$ViewList['userlist'] = array( 'script' => 'userlist.php', 
                               'default_navigation_part' => 'newslettersnavigationpart',
                               'params' => array( 'remove'),
                               'functions' => array( 'read' ));

You can then access the parameter within your View PHP file as follows:

$Params['remove']

If we want to add more parameters into the module.php file just add more array elements to the “params” array.

Unordered Parameters

These always come last out of the two types and they can be written in any order. This is because both the name and the value are defined in the URL. Following on from our previous example, if the user ID of the user we were removing from our mailing list was 42 the parameter would appear as follows if it was unordered:

http://www.yoursite.com/admin/newsletter/userlist/(remove)/42

If we were to declare the parameter in the module.php file this is how our view declaration would be written:

$ViewList['userlist'] = array( 'script' => 'userlist.php', 
                               'default_navigation_part' => 'newslettersnavigationpart',
                               'unordered_params' => array( 'remove'    => 'remove' ),
                               'functions' => array( 'read' ));

You can then access the parameter in the same way within your View PHP file as follows:

$Params['remove']

As with the ordered parameters, adding new parameters is as easy as adding more array items to an array, in this case the “unordered_params” array.

The key in the unordered_params array is used to specify what is used within the URL. The value is then used within the $Params array in your view.

Implementing Parameters

We are going to use unordered parameters in our example. This is mainly because out of habit I tend to only use ordered items when it makes as much semantic sense as possible.

For instance, if we were to extend our newsletters functionality with the ability to have different newsletters we would want to display the mailing list for each newsletter. If we had a newsletter called news and another called sport the URLs for the mailing list could be:

• http://www.yoursite.com/admin/newsletter/userlist/news
• http://www.yoursite.com/admin/newsletter/userlist/sport

This infers that our url is for a list of users of a news/sports newsletter and so it makes sense in terms of the page we are viewing.

In the current view we are implementing, the user ID we are removing has no semantic meaning attached. By having it as an unordered parameter so it has some meaning applied as the name of the parameter is also supplied:

• Ordered: http://www.yoursite.com/admin/newsletter/userlist/42
• Unordered: http://www.yoursite.com/admin/newsletter/userlist/remove/42

In the code examples that follows (and the code which you can download at the end of the tutorial) we will cover the code for implementing both ordered and unordered parameters so in future you can use both when necessary.