For a previous article I covered the various ways you can export user data using eZ Publish. In the article, I suggested how you can export all users who have logged in over the previous month using an extended attribute filter. In this article I will cover creating several different Extended Attribute Filters so you can see how they may be implemented in your code.
We’ll start by creating an extension to house our filters followed by building a basic filter to return a list of users who have forgotten their passwords. We will then create a filter to tell us how many/which users have logged in over the past month. We’ll also cover how you can add Extended Attribute Filters to both your template files and your PHP scripts.
All fetch statements in eZ Publish construct SQL statements to query the database for relevant objects. Extended attribute filters allow you to extend the built in functionality by adding completely custom clauses into the SQL statements. This is especially useful to tie in your fetch statements to other tables in the CMS, both custom tables and those not usually referenced in Fetch statements. It is also useful to query the ezcontentobject_attribute table in ways not possible with standard Fetch statements.
The Extended Attribute Filters code is available on Github for this tutorial. This and content for all future tutorials will exist in the http://github.com/davidlinnard/eztutorials repository (all content for this tutorial can be found on this commit ).
Basic setup
We’ll start by ensuring all of the Fetch statements we are using are showing their underlying SQL queries in the debug at the bottom of the screen. If you are comfortable doing this, and you are confortable enough creating your own extensions then I would recommend jumping to the next section .
Enabling the Debug
There is a couple of key settings to change, all within your main site.ini file. We firstly need to make sure our debug is enabled for the site and we then need to make sure that all the SQL statements used to construct the page are shown in it. The following code will do this for us:
site.ini.append.php
Creating our Extension
Now that the changes have been made, let’s create our extension. Go into your source code and under the extensions directory create a folder with the name you want to give your extension, I’m going to call mine onequarterenglish so rename yours accordingly in the next step (I’ll show the name of the extension in bold whenever it is used).
We now need to activate the extension, this will cause eZ Publish to look into the onequarterenglish extension directory for other settings and definition files which will store details of what functionality is provided in the extension. You can do this through the CMS or manually in your code. If you want to add it through the CMS go to Setup and then choose “Extensions” from the left hand column. If you are not using the default eZ Publish file permissions you may find you have an issue adding the extension in this way.
To add the extension manually, go into your main site.ini file again and you should see a section titled “ExtensionSettings” (in the default override it is usually at the top). Underneath this contains a list of extensions which are enabled on the site. When eZ Publish enables or disables an extension, it merely adds or removes it from this list. The other thing to note with the extensions is that the order matters. If for example you had two extensions which contained template files you may at some point have a situation where both contain overrides to a single file. In this case the extension called first in the list would be used.
Below is a sample list of extensions you should expect to see, I’ve added my one to the bottom line so just replace onequarterenglish on the last line with the name of your extension:
Creating an example filter: Users who have forgotten their passwords
Now that we’ve got a working extension and the debug we need is being displayed, let’s create our first extended attribute filter. Extended attribute filters consist of two parts:
- A settings file supplies eZ with a list of extended attribute filters and where these are implemented
- A class file is created to store one or more filters. These will construct the additional custom SQL created for our fetch statements
Creating the settings file
Our first step is to create a settings file so that eZ Publish can find our filter. To do this, we need to create a settings file called extendedattributefilter. This can be used to store as many as you want but for now, we’ll stick with the one. In your extensions directory, create a folder called settings (if one does not already exist). Within this create a file called extendedattributefilter.ini.append.php. Add the following to your new file (comments are supplied):
extensions/onequarterenglish /settings/extendedattributefilter.ini.append.php
Now lets get into the real task of making our filter. We will explain how eZ Publish uses the settings information once we have created our class.
Creating our class file
Filters work through methods within a class. As you can see from the settings above, eZ publish can translate where it needs to go by looking up the extension name and the location of the class file within this. It’s then simply a matter of going to the correct method (which is also specified in our settings file). Our class therefore is very simple to structure. We just need an empty constructor and then the method we have just specified. Below is an empty implementation of a class:
extensions/onequarterenglish /classes/userfilters.php
There is our basic class. Now we’ll add some custom code to pull out the users who can’t remember their passwords. For our Extended Attribute Filter to work, we have to provide eZ with the additional tables we want to use and also the extra conditions we want to place on the data returned. For our first filter, we need to use the eZ Publish table ezforgot_password . This stores the content object ID of each user who has forgotten their password. We then need to make sure in our join that we only count the content objects with an ID in the ezforgot_password table. Below is the code which will do this for us:
extensions/onequarterenglish /classes/userfilters.php
There are a couple of nuances with the code I’ve noted in the comments:
- You need to ensure there is a comma at the start of the list of the additional tables you want to add to the query.
- Your conditions need to finish in an “AND” to ensure other conditions are also used
- You need to manually add conditions to add join each additional table you want to link to
Adding the fetch to your template
As you would expect, by default user information is hidden to people viewing the site. If you want to test this functionality you need to either ensure you are logged in as a user with administrator privileges in the front of the site or ensure the template is only visible in the CMS itself.
In my next tutorial I will cover how you can add functionality such as custom templates into the CMS. In the meantime let’s add the functionality to an existing page in the front of the site.
Go into the template you want to add the fetch statement to and add the following code:
Example 2 – Showing the users who last logged in between custom dates
Luckily, the process of adding another filter is much quicker than creating your first one. We already have all of the files we need in place we just need to add additional code to a couple of files. Our function will make use of two parameters, these will store the start and end dates to give us the date range we need to check between.
Please note that eZ Publish does not track every single login by the user, only the most recent (although you can also extract when a user account was created or last updated). Therefore if you are looking at logins over a month in the distant past your script will not display users who have logged in since this time. If you do need to run this script, I would recommend running it in a cronjob so you are running it as close as possible to the dates being searched through as possible (please see this tutorial for a guide for doing this).
extensions/onequarterenglish /settings/extendedattributefilter.ini.append.php
The first file we need to update is the extendedattributefilter.ini file we created for our first filter. Add the following after our previous filter:
Since this example is a bit more complicated, let’s step through the script. The script depends on the ezuservisit table. This stores details of failed logins, most recent login time and how many times users have been logged in. Our first task is to link the ezuservisit into our SQL statement:
As we are looking at custom dates, we now need to make sure we use the parameters the user passes in. These are accessed using the parameter array passed into our function (in our case the parameters will be in the $params array). Parameters can be easily missed so we need to make sure we account for parameters which are not supplied. In our case we ignore an end date if this is not supplied but if no start date is supplied we assume we should return all users who have logged in to the site. We also ensure that the dates are sent to queries as integers to avoid invalid input:
Once this has been carried out we just need to return our SQL:
We can now include the fetch in our templates using the following code (be sure to make a note of how the parameters are set):
The code returned from the fetch in the debug should be similar to the following, again note that our query is shown second after the debug notice (look for ezuservisit in the debug):
Using Filters in PHP Scripts
So now we’ve looked at using two Extended Attribute Filters in our templates but what happens if you need to add them to a script? Luckily this is straightforward. The following example assumes the logged in user has access to the user information:
Let’s step through the script to see what’s happening:
First we establish the values we need to pass into the Extended Attribute Filter (in our case we are looking over the previous month). We then store this in an array with the ID of the Extended Attribute Filter so eZ Publish knows which filter to use. We can then store the other limitations we are going to add to our fetch, namely our sort order and our classes to include. Finally we store these details in one single array so they are ready to be passed into the fetch.
This part of the script is important as it limits where eZ needs to look for the users. In this case, we have limited it to the members section of the users tab (so do not be surprised if the admin user does not show up when you run the query). If you wanted to move the query up to be all users, make sure to add a depth filter to the parameters array we just created to ensure eZ goes to a greater depth than it’s default of one.
$monthly_logged_in = eZContentObjectTreeNode::subTreeByNodeID( $params,$parent_node_id );
$monthly_logged_in_count = eZContentObjectTreeNode::subTreeCountByNodeID( $params,$parent_node_id );
$cli->output(‘Users Logged in over the past month: ‘.$monthly_logged_in_count);
The final part of our script then merely runs the fetch statements. All we do with the information is to output the number of users. Please see my previous tutorial on Fetching User Information with eZ Publish if you wish to print off more user information.
Conclusion
In this tutorial we have covered how you can create and use your own Extended Attribute Filters, both in your templates and in your scripts. If you do need to create your own, you may want to check if what you’re after already exists by checking out those created by eZ Publish community . My next tutorial will cover how you can create your own templates within the eZ Publish CMS so that the user information extracted here is only presented in templates available to admin users.
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
