Category Item Count: To a Generic Solution
Last month I described how a new feature was developed to count the number of articles in each category. At the end of the 2nd day of JoomlaDay France 2015, the feature was working… that is, it counted all articles (for com_content) in the Category Manager for Articles. I got it working by adding a hard-coded “if extension = com_content” check in the Category Manager. That’s not a solution but a workaround, I was fully aware of that.
When I had returned home from Joomladay France, I had no idea how to make it generic so that all core components (or even 3rd party ones) that would make use of com_categories could display an item counter for their own items.
Thomas Hunziker and Robert Deutz gave me some suggestions to make it more generic. I tried using a specific helper file. That file included in your component some code to extend the query object with some extra joins. The com_categories component would look for it and add it to its own SQL query. It worked!
However, why create an extra helper file while every component that uses Joomla’s Category Manager already has a helper file? Roland Dalmulder helped me with accessing the existing helper files. So I was able to move the extra query code to that existing file. This made the feature generic: Now the Category Count Items feature had become a generic feature that you could use in your own components… I’ll show you that later in this article. First, in order to use it, the new feature has to be tested, and added to the Joomla core.
Improving the Joomla core
So what if you find a bug (or hidden feature) in Joomla? Or if you want to make an improvement?
You don’t need to code to report bugs. Just visit issues.joomla.org, login (or register) and create a new issue. Before doing so, please search the issue tracker to see if it has already been known. Another useful procedure to do is to install the latest version from Joomla (on github the “staging” version) to see if it has already been solved in the next version...
If not known or still present in the next version, please create a new issue. Give all necessary details and describe the steps to reproduce the error. And because a picture is worth a thousands words, please make some screen shots to visualize the problem.
If other users are able to reproduce the error, some developers might dig into the problem and create a patch for it.
Creating a Patch
To fix issues or add new features developers will create some code that will be put in a patch. A patch describes in code all the differences from the latest Joomla version. The code & patches are managed using git (= software versioning) and is available at github ( = sort of wikipedia for code).
A developer will make changes in their copy of Joomla CMS. All changes are recorded and can be submitted to the original Joomla CMS with a Pull Request (PR). In other words, the developer asks Joomla to pull their changed code into the Joomla core.
Before the Joomla project considers taking such PRs into the Joomla core code, they need to be tested by other people than the developer. Your PR needs at least 2 successful tests before it will be marked RTC (Ready To Commit), meaning it’s ready to be added to the Joomla core code.
Testing a Patch
The testing of a Patch can be done by anyone who knows how to use Joomla. Yes, you read it well, you can help with testing too. All you need is…
- some free time
- a default Joomla installation (please use the latest test “staging” version from https://github.com/joomla/joomla-cms), install it with “Test English (GB) sample data” and do not remove the /installation/ folder like you have to do with a normal website)
- to install a “Patchtester Component” (com_patchtester, see https://docs.joomla.org/Component_Patchtester_for_Testers)
- a Patch (“PR”) that needs to be tested (see http://issues.joomla.org/),
test if you can reproduce the issue, install the Patch & test if it solves the issue & report back.
Full instructions: https://docs.joomla.org/Testing_Joomla!_patches & Quick Reference Guide: https://docs.joomla.org/Testing_Joomla!_patches_QuickReferenceGuide
To make it easier, and even more fun, special “bug patch testing events” are organized frequently in the Joomla community. Those are known under the name “Joomla Pizza, Bugs and Fun”: A group of people help new users with testing patches. The upside: you will learn something about the process of open source software development, experience the fun in testing patches, learn about new features in Joomla, and share your enthusiasm for Joomla and open source. The downside: it can be addictive :-)
Back to Category Item Count
A lot of people helped me with this PR! I already mentioned some people who helped me out. Some people in particular (you know who you are! And, if not: Tobias Zulauf, Thomas Hunziker, Marc Dechèvre, and Peter Lose. Thanks!) gave me much valuable feedback on errors they found. Which I managed to solve.
Finally Hans Kuijpers, Marc Dechèvre and Stefan Wendhausen were able to test my PR successfully which gave me the two positive tests needed to get the PR to RTC.
On the way, during the whole testing and feedback process, some labels have been assigned to the PR (you can see them on the top left of #6916)
- Language Change - there have been some changes in the language strings. Translation Teams need to know that in order to translate the new/changed strings to the language files of all different Joomla languages (for an overview on all language packs, see https://community.joomla.org/translations/joomla-3-translations.html)
- New Feature - the PR is not a bug fix but a new feature. Bugfixes are included in every (minor) update (eg 3.4.2, 3.4.3, etc). New features will only be added in major releases (3.5.0, 3.6.0, etc)
- PR-staging - the PR has been added to the current staging release.
- RTC - Ready To Commit
- Because it’s a new feature, it has been marked as Milestone Joomla! 3.5.0, meaning that it will certainly not be added to the next minor release 3.4.2 but that it might be added to a next Joomla version.
Oops - we have a small problem…
I decided to add the new feature to some core components that also use com_categories: Banners (PR #6934), Contacts (PR #6938) and Newsfeeds (PR #6936). Those PR’s all followed the same procedure: got tested & marked RTC & Milestone Joomla! 3.5.0. However, one of them gave some problems: Banners.
Due to the new feature, the Category Manager (com_categories) will create some number counters with hyperlinks underneath. Those hyperlinks all have a status filter &filter[published]= so that you can click to the items that will be filtered on the status. All components listen for the "Select Status" filter to &filter[published]= (and expect a statuscode of 0,1,2 and -2). Except for the Banners component, which listens to &filter[state]=
After making a small change in the banners model & its filter_banners.xml, the banner component filters its items in a similar way as all other core components. Hence, the Category Item Count now works for Banner items too...
How to use it in your own component?
Let’s hope that this new feature will be in Joomla 3.5.0. If so, then you should be able to use the feature in your own component! To include this new feature in your own extension, you'll have to edit just one file: a Helper File
If your component uses Joomla's Categegory Manager (com_categories) for managing categories, then you'll probably have a helper file in your component's administrator folder already. When you open the Category Manager from your component via /administrator/index.php?option=com_categories & extension=com_yourcomponent the Category Manager will retrieve the helper file of your component. It will than use the addSubmenu method to create a submenu with links to your extension. That makes it easy to return from the Category Manager to your own component.
We'll add a new function to this helperfile to extend the Category Manager's $query object with some SQL queries. Those SQL queries count the number of items for each category, and for four different status: published, unpublished, archived and trashed.
Add to the helper file /administrator/components/com_yourcomponent/helpers/yourcomponent.php within the
class YourcomponentHelper extends JHelperContent
the following method:
public static function countItems(&$query)
// Join articles to categories and count published items
$query->select('COUNT(DISTINCT cp.id) AS count_published');
$query->join('LEFT', '#__yourcomponent_items AS cp ON cp.catid = a.id AND cp.state = 1');
// Count unpublished items
$query->select('COUNT(DISTINCT cu.id) AS count_unpublished');
$query->join('LEFT', '#__yourcomponent_items AS cu ON cu.catid = a.id AND cu.state = 0');
// Count archived items
$query->select('COUNT(DISTINCT ca.id) AS count_archived');
$query->join('LEFT', '#__yourcomponent_items AS ca ON ca.catid = a.id AND ca.state = 2');
// Count trashed items
$query->select('COUNT(DISTINCT ct.id) AS count_trashed');
$query->join('LEFT', '#__yourcomponent_items AS ct ON ct.catid = a.id AND ct.state = -2');
If you don't use "state" for the state of your items, but "published" then you'll have to modify your SQL accordingly. If your component does not have "archived" items, then you can leave it out of the function. The Category Manager will automatically show columns for count_published, count_unpublished, count_archived and count_trashed.
At this moment it is unsure if the Category Item Count will get in the Joomla core. If so, it might be integrated in the future Joomla 3.5. And if it gets in the core, you could use it for your own components (that make use of Joomla’s Category Manager for their categories).
I hope that I have given you a small insight into how features can get integrated in the Joomla core. And how you can help improving the Joomla core code (even without knowing how to code).
If you want to know more about developing PRs, testing patches and the development process of Joomla, please visit any of the Pizza Bugs and Fun events.
Finally, thanks again to everybody who helped me developing this feature!
(The Bug, Patch & Testdummy images are from https://commons.wikimedia.org)