Imaginemos un mundo libre

La paz interior comienza en el momento en el que decides no permitir, que ninguna persona o evento, tome el control de tus emociones.

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

with 15 comments

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.

kmail Fancy Theme

Fancy Theme

kmail Air Theme

Air Theme

kmail Qt Theme

Qt Theme

kmail Nokia 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

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:

OTP

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:

OTP HTML

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:

Planet KDE Theme

Linux Foundation Theme

Nokia Conversations Theme

Planet openSuse Theme

Planet Kubuntu Theme

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

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.

Written by Ronny Yabar

August 26, 2010 at 3:41 pm

Posted in KDE, Planet KDE, Qt

15 Responses

Subscribe to comments with RSS.

  1. Excellent work, thank you.

    About Akregator and KHTML, so there’s no plans of porting it to kdewebkit that you know of?

    Teho

    August 26, 2010 at 4:28 pm

  2. Really good article. It’s nice for people like me who haven’t been following along to see what GSoC students get up to, and I know that writing such a comprehensive report takes a lot of time. The theming work you’ve done seems nice, and I’m looking forward to seeing it roll out in new releases.

    Jeffery MacEachern

    August 26, 2010 at 4:42 pm

  3. Nice work on the theming, blogging and I wish you well for your green belt!

    Diederik van der Boor

    August 26, 2010 at 4:49 pm

  4. Awesome work! Thanks for taking the time to upload the screenshots too. It really helps to give a visual when explaining what you’re doing. I think the Grantlee theme should be for each application, because as you said, some themes might look good in one app and then not as well in another app. What might work though is to create a configuration KCM module in the appearances and have the ability to set the grantlee theme for all apps or for each individual app.
    Hopefully someone will put some work into akregator and fix those issues, or better yet, port it to webkit and get rid of the deprecated khtml.
    Thanks for all your hard work!

    Supreme1012

    August 26, 2010 at 5:28 pm

  5. Great blog & astonishing work. Thanks you very much for :)

    adjam

    August 27, 2010 at 3:12 am

  6. Good luck with tae kwon do! May your coding powers grow in tune with your fighting prowess! ;)

    Punit

    August 27, 2010 at 4:07 am

  7. Don’t know who the hell told you khtml is deprecated, but it is not.

    Albert

    August 27, 2010 at 4:53 am

  8. you should prolly head over to the official konqueror-khtml mailing list and ask about that : https://mail.kde.org/mailman/listinfo/kfm-devel

    dear-lazyweb-style doesn’t work all that great during holidays =)

    but your problem could be related to the way you load the generated html. Is it from a string using begin()/write(s)/end()? from a temp file? from a “data:” url? I believe all but the latter will give you expected results.
    If the source, for some reason, doesn’t seem fully trustable, or could be remote, then of course it won’t load random files from disk… duh

    Spacer

    August 28, 2010 at 5:26 pm

  9. Very nice report. It’s great to be showing the results of your work for all to see.

    The Akregator images issue presents some challenges, relating to security but I don’t think webkit would solve those. KMail just happens to work a different way and not hit the bug. Options are data:/ urls and temporary files with local urls instead of remote urls, or maybe an iframe. We can look at the technical solutions in the coming weeks though.

    Thanks again and well done on completing the Summer of Code.

    steveire

    August 30, 2010 at 4:36 am

  10. Hi.. I’ve added a method to KHTML trunk that should permit the use you want. I’ve CC’ed you on the commit.

    SadEagle

    September 1, 2010 at 10:16 am

    • Thank you very much SadEagle for adding this feature. I’ll eventually update my akregator code.

      Ronny Yabar Aizcorbe

      September 6, 2010 at 3:30 pm

  11. Thanks everyone for their words. As you see, SadEagle has added the feature we needed in KTHML. So stay tuned for the updates in Akregator.

    Ronny Yabar Aizcorbe

    September 13, 2010 at 3:30 am

  12. Hi, congratulations for the great work in KDE.

    I find your blog pretty interesting, the Randy last lecture is amazing, thanks for posting, and I’m going to read more articles when get some time.

    Also noted that you’re involved in some spreading and community activities so I wanted to talk you about Zona Qt, a spanish speakers community site for Qt programmers, we started about half year ago and we have been mainly answering questions in the forums, but now we are trying to involve in some official translations or development projects.
    Maybe you find it interesting and want to collaborate.

    Saludos :D

    Miguel

    November 1, 2010 at 2:11 pm

    • Hey Miguel.

      Yes, I am really spreading QT and KDE here in Peru. Thank you very much for the invitation, will look the Zona Qt site today and see where I can help.

      Ronny Yabar Aizcorbe

      November 1, 2010 at 2:52 pm

  13. […] can see my full report of the Google Summer of Code project in which I worked in the past. In this post I talked about […]


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: