Creating Custom Admin Modules & Views

Creating the view Template files

Move back into the root of your extension and create a folder called “design”. In our case we are just storing template files but any specific CSS, Javascript or images for your extension should be stored in here, if required.

Create a directory called “admin” and within this a folder called “templates” (the templates folder will have the following path /extension/mynewsletter/design/admin/templates).

Our templates have been placed in a subdirectory of templates called “newsletter” so create a folder called newsletter within templates (the path will be /extension/mynewsletter/design/admin/templates/newsletter).

We are now ready to create our templates. Firstly, we will create an empty implementation of the left navigation. Create a file called “leftmenu.tpl” within newsletter (/extension/mynewsletter/design/admin/templates/newsletter/leftmenu.tpl). In the template, do nothing but enter some static text for now (for example “MENU HERE”. This will act as a placeholder while we create the main template for the page.

Next, create a template called “userlist.tpl” in the newsletter design folder (/extension/mynewsletter/design/admin/templates/newsletter/userlist.tpl). In this template we need to pull out all users who have said they wish to receive the newsletter. For now, we will carry out a fetch statement limited to which users want to receive the newsletter and then print the name and email address of each user to screen. After we have done this we will extend the functionality to allow admin users to remove users from this list.

Enter the following code in your userlist.tpl template:

{def $users_folder = fetch( 'content', 'node', hash( 'node_path', 'Users/Members'))
     $newsletter_users = fetch( 'content', 'list', 
                                hash( 'parent_node_id', $users_folder.node_id,
                                      'attribute_filter', array( array( 'user/newsletter','=',1))))
}
<div class="box-header">
    <div class="button-left">
        <h2 class="context-title">Newsletter Users ({$newsletter_users|count()})</h2>
    </div>
    <div class="float-break"></div>
</div>

<div class="box-content">    
    <div class="content-navigation-childlist">
        {if $newsletter_users|count()}
            <table cellspacing="0" class="list" id="ezasi-subitems-list">
                     <thead>
                   <tr>
                      <th>Name</th>
                       <th>Email</th>
                </tr>
                  </thead>
                  <tbody>
                {for 0 to $newsletter_users|count()|dec() as $counter}
                    <tr class="eq($counter|mod(2),0)}bglight{else}bgdark{/if} {if">
                        <td>{$newsletter_users[$counter].name}</td>
                        <td>{$newsletter_users[$counter].data_map.user_account.content.email}</td>
                    </tr>
                  {/for}
                 </tbody>
            </table>
        {else}
            <p>No users are signed up!</p>
    </div>
</div>
{undef}

The code does look quite long but this is just to ensure our template follows the same style as the rest of the admin site. All we are doing is carrying out a simple fetch at the start and then looping through the data. If we strip the styling the code is simply the below:

{def $users_folder = fetch( 'content', 'node', hash( 'node_path', 'Users/Members'))
     $newsletter_users = fetch( 'content', 'list', 
                                 hash( 'parent_node_id', $users_folder.node_id,                          'attribute_filter',array(array('user/newsletter','=',1))))
}
<h2>Newsletter Users ({$newsletter_users|count()})</h2>
{if $newsletter_users|count()}
<table>
<thead>
<tr>
<th>Name</th>
<th>Email</th>
</tr>
</thead>
<tbody>
{for 0 to $newsletter_users|count()|dec() as $counter}
<tr><td>{$newsletter_users[$counter].name}</td>
<td>{$newsletter_users[$counter].data_map.user_account.content.email}</td>
{/for}
</tbody>
</table>
{else}
<p>No users are signed up!</p>
{undef}

If you visit the page now you should see the list of users which looks similar to the below (http://www.yoursite.com/admin/newsletter/userlist) :

The only task left to make our view usable is to make sure the users can access it in the first place. Once we have done this you will have a simple working view which you should be able to extend however you want.

Providing Navigation

There are two things we now need to do to ensure so that the user can easily navigate to and around our module:

• Add a tab to the options running along the top of the site access
• Provide a menu within the module to allow the user to navigate around the module

Since we currently only have one view the more important of the two is definitely the first but we will do both of these now.

Adding a menu tab

Adding a menu tab will do two things. As well as providing an easy way to navigate to your module it will also ensure the new tab is highlighted rather than the default “Content Structure” highlight. We need to do this in two steps.

Creating the tab requires you to create a settings file within our extension and add the details to the new module we have created in the new file. eZ Publish will then pick this up automatically and our tab is ready to use.

The settings file we need to create is “menu.ini.append.php”. Navigate to the root of your extension and then navigate to your settings directory (/extension/mynewsletter/settings/). Once you are in there create a file called menu.ini.append.php and enter the following content:

[NavigationPart]
Part[newslettersnavigationpart]=Newsletters

[TopAdminMenu]
Tabs[]=newsletters

[Topmenu_newsletters]
NavigationPartIdentifier=newslettersnavigationpart
Name=Newsletters
Tooltip=Managing the Newsletter list and sending emails
URL[]
URL[default]=newsletter/userlist
Enabled[]
Enabled[default]=true
Enabled[browse]=false
Enabled[edit]=false
Shown[]
Shown[default]=true
Shown[edit]=true
Shown[navigation]=true
Shown[browse]=true

The code is very straightforward. The NavigationPart section of the file allows us to target the tab as our current one when we are in our module. The tab is added using the Tabs[] array. The other settings specify a name, tool tip and behaviours associated with this tab. For instance, our tab does not allow you to navigate to our tab while you are editing an object (although the tab is still shown).

With the tab now showing we now need to ensure that the Newsletter tab is highlighted whilst we are in our module. Go to the module.php file you created earlier (/extension/mynewsletter/modules/newsletter/module.php) and add the line of code in bold,

<?php
$module = array( 'name' => 'newsletter' ); //the name of our module

$ViewList = array();//add as many views as you want here
$ViewList['userlist'] = array( 'script' => 'userlist.php', 
                               <b>'default_navigation_part' => 'newslettersnavigationpart'</b>,
                               'functions' => array( 'read' ));//the script used to setup the template plus the user permissions required for it (also see below)
 
//setting user permissions required by our module:
$FunctionList = array(); 
$FunctionList['read'] = array(); 
?>

The extra line will links our view with the extra tab we have just created.

Adding a left menu

For the left menu, we just need to update the code in the template file we have already created (/extension/mynewsletter/design/admin/templates/newsletter/leftmenu.tpl). At the current time we only have the one link but we will add to this later. The styling used on other parts of the admin site is used here to ensure the module is consistent with the rest of the CMS:

{def $has_read_permission = fetch( 'user', 'has_access_to',
                                    hash( 'module',   'newsletter',
                                          'function', 'read', 
                                          'user_id', $current_user.contentobject_id  ) )}
<div class="box-header"><div class="box-tc"><div class="box-ml"><div class="box-mr"><div class="box-tl"><div class="box-tr">
<h4>Newsletters</h4>
</div></div></div></div></div></div>

<div class="box-bc"><div class="box-ml"><div class="box-mr"><div class="box-bl"><div class="box-br"><div class="box-content">
<ul>
{if $has_read_permission}
    <li><div><a href={'/newsletter/userlist'|ezurl()}>Users signed up</a></div></li>
{/if}
</ul>    
</div></div></div></div></div></div>

Although the majority of the code is static HTML, it is worth noting how permissions can be used to restrict which menu items are shown. This is carried out on the first couple of lines with a Fetch built in to eZ Publish. We then use the variable we set to store the value of this when we display the menu item. As the module currently only has one view, this is actually not needed as the only time the menu will show is when the user is on this particular page anyway. We are adding the code here as we will soon be adding another view with a different permission set and so it will then be needed.

Your view should now look like this:

Although our example does not provide much functionality it demonstrates the basics for creating modules and views. Let’s extend the view we’ve created to allow some user interaction to show how additional functionality can be added to your code.