GSoC final report: MessageViewer ( Kmail ) and Akregator ported to Grantlee.

It has been a long time without posting, but well GSoC finished and it’s time to share with the community the result of the project.

First, I want to thank you my mentors Thomas McGuire and Stephen Kelly for the support, the knowledge shared and of course coding tips.  I really learned a lot from them and one important thing:  How the Open Source development works.

The MessageViewer

Well, inside kdepim there is a library called MessageViewer which job is to provide a widget that can show a message. The first goal of the project was to port the MessageViewer to the Grantlee template system for both reasons: First, to have a clean, readable and more maintainable code and second to have a solid theming system to show/get those cool themes users and some developers like.

The MessageViewer had two classes  HeaderStyle and HeaderStrategy that had the job to show and manage the header data.  The header style is the class that generates those fancy, brief, enterprise… styles you see in kmail and the header strategy is the class that decides which data to show/hide.

When I started the GSoC project, both, the styles and the strategies were  hardcoded each one and the styles had a mix of QT + HTML code. So these classes were removed and a new one ( HeaderTheme ) was created to combine that style/strategy functionality:  So Actually HeaderTheme is a combination of those two classes, but with the static HTML removed, the code cleaned up and the Grantlee integration.

In general, the HeaderTheme class is the responsible to setup and make the connection to Grantlee so it can set/show the themes.  So now we have “themes” instead of “styles”.

Themes

Let’s stop for a moment and see some screenshots.

Fancy Theme

Air Theme

Qt Theme

Nokia Theme

I created these themes just to show the theming capabilities. Of course, we can have some by default in Kmail like the fancy one for example. So a “Themes” menu replaced the old one “Styles”.

The default themes folder is inside the MessageViewer and has the following structure. Similar to wallpapers or themes from other KDE projects.

A theme consists of a folder with: An images directory (If the theme has images), a default.desktop file with the metadata information and the default.html that has the styles and the data variables need to be shown.

MessageViewer Themes Structure

Note that the themes menu is created with the themes subdirectories that are in all the KDE data directories like kde, .kde and .kde4.

The ObjectTreeParser

The ObjectTreeParser is the class inside the MessageViewer that parses messages and generates the HTML code for the Viewer. The ObjectTreeParser is a very very complex class. Actually, this was my face the first time I looked at it:

But anyway, after some work, the ObjectTreeParser was partially ported to Grantlee. Partially, because there are some parts on it that generates HTML dynamically, so the static parts were ported to Grantlee and now that static part is divided in small pieces of HTML to identify them faster. There are no theming possibilities here, this port was to improve the code readability and make the maintenance tasks easier.

Inside the MessageViewer there is a htmlOTP folder with the HTML files that has the ObjectTreeParser data of static information:

Akregator

The Akregator ported to Grantlee was really similar to the MessageViewer with the difference that Akregator has the concepts of views  ( Normal, combined and widescreen). In Akregator the situation was the same, Those views were hardcoded with identical Qt + HTML + CSS.

So, that presentation stuff was extracted to themes, and a new method renderTheme() was created in the ArticleFormatter  to setup up the Grantlee magic and call the themes. Now, no matter which view is chosen, the same theme will be always called and looks the same in the three different views while you still not choose another theme.

We had the problem that Akregator, as  based on KHTML,  doesn’t allow you to load images from the hard disk, no relative neither absolute paths work, my mentors told me it has to be with the KHTML internals for security.  ( The MessageViewer is based on WebKit. ) A web URL works, but I think this doesn’t solve our problem. So no images atm in Akregator themes. The logos and some backgrounds I created could not be shown. Just enjoy the theming.

But we really need to fix this. Maybe a KHTML hacker can provide some help. Some Akregator themes screenshots:

GHNS

No much to say here. Get Hot New Stuff was integrated in the MessageViewer and now you can start downloading themes from kde-look, our themes provider. There is just one theme to download for Kmail atm.  Thanks to Frank Karlitschek from OpenDesktop.org for creating the Kmail and Akregator categories. Actually, we had a discussion to instead of having applications themes have a Kontact Theme. I think a Kontact theme could be hard to maintain, because it will be full of conditionals about the different kdepim applications based on Grantlee.

IMO, it would be better to have applications themes and share duplicated code with the Grantlee inheritance feature that is just a:  {% include “your_code_to_share.html” %}. Maybe we can have a central place with the code similar in all themes for all applications. It will give us more flexibility because although the styles could be similar, the data and the applications views are not always the same.  Trust me, I tried the fancy theme in both Kmail and Akregator and it looks a little bit deformed in Akregator for the views it has. But this is debatable of course, I would like to here your feedback here.

In my next post for users, I will talk about how to write a Kmail/Akregator theme, the variables you need, the styling, Grantlee cool features, etc.

GHNS in Kmail

Lessons learned from GSoC

1._ Stephen was really helpful and always gave me good comments in my Qt/KDE code and even sent me a couple of patches to improve my work and the same with Thomas, as the ex Kmail maintainer for a couple of years, usually gave me good and detailed explanations of how the code works inside Kmail and the MessageViewer. I learned from them that you just simple need to commit more often to get feedback faster about your code. I usually had the habit of waiting to complete some stuff or couple of tasks and then commit. As they told me: Even one line change that solves a minor issue count. So go ahead and commit that little change or improvement.

2._ Practice, practice and practice more C++/Qt/KDE code. The more you practice this stuff, the more you understand the code written in KDE. Also, have a copy of the KDE API in case you lose your internet connection and need to work offline.

3._ I remember on the first days of the project that I got an Akonadi problem that prevented me to start Kmail correctly. I was searching the problem in Google, I followed the Akonadi TroubleShooting page, kde forums and had no luck. Then on IRC Leo Franchi (lfranchi) told me about a couple of more “rm commands” inside my kde-devel home directory, stop/start Akonadi and the problem was gone( Thanks Leo).

To be honest, I usually try to solve problems myself, but I realized sometimes this is not the way to go. So whenever you have a problem like this don’t made this stupid mistake and ask the KDE community about it, you can save a lot of time.

4._ Related to point 3.  It was really funny how a simple thing to add as an “Action List” to the menu took me some time.  My KXMLGUIClient code was ok and I found the API documentation really clear.  I was really frustrated about my code not doing what I wanted to do, so I entered on #kde-devel and David Faure (dfaure) came to the rescue. Really thanks David for the KXMLGUIClient explanation. My themes action list code really needed to be in the MessageViewer, however this stuff had to be called in the Kmail side after createGUI(). So a Kmail->MessageViewer connection was made to make this action list working.

Don’t underestimate my knowledge, go and code the Kmail/MessageViewer stuff and you’ll see the complex thing. Really complicated for an initial KDE developer.

5._ Usually Stephen and Thomas asked me for my kdebug() outputs and sometimes the information I showed them wasn’t enough to debug a problem. Why? Maybe, because you don’t have the  right debug information enabled :). So beginner KDE developers, please run kdebugdialog, enable the information you need and make your mentors/KDE Developers happy.

6._ And finally GSoC was a real learning experience that motivates me to do more KDE work. Specially code and promo. So stay tuned.

Next steps

• Fixed the current code minor issues to merge the kmail/MessageViewer/Akregator code to trunk. I really want all this theming stuff to be part of KDE SC 4.6.
• As I told my mentors in our last GSoC meeting, I will stay on KDE to get more programming knowledge and to know better the community. My goal in short-medium term is to maintain all the theming code in kdepim and help on porting more KDE applications to Grantlee (If they need the port of course). I think with the experience gained and more practice I can do it.
• Give more talks about KDE (I already gave two), more involvement with the community and continue spreading the work about KDE in South America and specially in Peru.

In unrelated KDE notes, After some months I returned to enjoy my other passion: Tae Kwon Do.  I will have real challenges in the next days and need to prepare well to get my Green Belt. This belt means “Power begins to develop” and the color green represents growth. The same color as the Qt one and exactly how I feel now on my KDE development experiences,  just a coincidence.

So wish me luck guys and I promise you some pictures of my Green Belt next to the Qt logo .

Then my  KDE work will be usually at nights.

Thanks to the KDE community, the KDE GSoC admin team, my mentors and Google for the opportunity to work in an Open Source Project I love.

Advertisement