Wednesday, 07 September 2011 22:34
In the last few days I took another attempt at contributing code to Joomla, specifically the platform project, after Andrew Eddie encouraged me in the comments to this blog post. Today that code was accepted, but boy was it a journey.
My contribution is a class to generate HTML tables. I had a need to have a view of all articles with an added column with some custom data. So, should I create my completely own component to do that? Or override the view in com_content for that? All that seemed pretty cumbersome, requiring way to much copy&paste and code in general. So I wanted to have a way to let a component render its standard layout/table and then later manipulate that table with a plugin without having to resort to nasty regular expressions. The end result is this JGrid class, which basically only delays rendering of the table. Instead of writing hardcoded HTML into the layout, the view class already creates and fills the object with the data for the different cells. Then the whole thing is sent to the layout, where you do a simple toString() and the table is generated. With some further tricks that I'm going to describe further down, you can modify the table object with a plugin after it has been filled by the view and before it has been rendered in the layout, adding columns and rows and changing the order of columns.
Lets see what it took me to get the code in: I had to get a github account. No problem here. I had to fork the joomla-platform repository. No problem either. I wanted to create a branch and make the pull request from that branch against the platform repository. That actually took me more than a day to properly figure out, but in the end, this is just something that you have to learn when using Git.
So far so good, that was the easier part and even though it took me some time, it shouldn't be a big issue for new contributors. The difficult part began then. First of all, I wasn't aware that pull request had to happen against the staging branch. Maybe this is documented somewhere and I just didn't see it. Second, you have to provide unittests. This is not an unreasonable request, but I actually didn't have that much experience in that area. So it took me some time to get this right. Third and worst part however was the coding style guidelines.
The Joomla platform tries to enforce a series of coding style guidelines and only accepts code when it meets these guidelines. Again, a reasonable request, but unfortunately a major hurdle for me. Installing PHP_CodeSniffer was no real issue, but Joomla has its own standard, which you have to install. However, before installing it, you have to find it first! Because the only documentation on the whole coding style guidelines can be found in the Joomla Wiki and that article unfortunately was outdated. That outdated information made me use a completely obsolete standard from an ancient joomlacode project which had basically nothing to do with the current coding style. Took quite some time to figure that one out.
When I then actually found the "right" coding style standard in the joomla-platform repo under the docs folder, I still had the problem of integrating the coding standard into my Eclipse. Turns out, PHP_CodeSniffer and the Eclipse plugin for its integration don't work on Indigo releases, so I had to use a Helios release. All the testing, installing and issue-analyzing for that took me yet another day...
Remember that the code for the JGrid class actually was ready and done way before I started with all the rest...
Now that I had my system set up (unittests, coding standard, github setup, etc.) I thought my code was ready. Turns out the coding standard is not complete yet... It neither enforces the @since tag, nor does it enforce new lines for curly braces for the "else" in an if-statement. On a side note: I find this rule of new lines for curly braces completely ridiculous. For me its not easier to read and considering the limited screen real-estate on my notebook (which is my development machine) I kinda resent the waste of screen-space. I would be more than happy to change the standard to only have new lines for curly braces in the context of a class or function definition.
Anyway, Andrew was so kind to accept the class this morning and now I'm confident to prepare more of my code for the platform project. The question however is: Will the CMS adopt the code? This first class is pretty much standalone and while it would make the CMS better (and faster. The JGrid object renders tables several times faster than the current way tables are written in Joomla layouts.) they could simply ignore it and no harm would be done. The other code that I want to contribute however changes existing classes and in one case forces the CMS to adopt the change. I'd love to ask that on a mailinglist but I'm still banned on all Joomla mailinglists and thus I'm asking the question here, so that someone from the project can answer.
I have code ready and tested, but not brought up to standard for the platform project for the following things:
So, what to do?