PIM/KJots

This page is about how to contribute to KJots.

Development

KJots is part of the kdepim module. To build it, you will need at least the kdelibs development headers. On Kubuntu you can get all dependencies with the command

sudo aptitude install cmake subversion build-essential kdelibs5-dev

Then get and build the latest code. Note that this method will not create a kontact plugin for kjots. This method is only suitable for new contributors to KJots. To build with the kontact plugin, download and build the entire KDE PIM module.

# Download the latest code.
svn co svn://anonsvn.kde.org/home/kde/trunk/KDE/kdepim/kjots
cd kjots
# Create a directory to build kjots in. The build creates several files and must
# be separate to the source.
mkdir build
cd build
# Create a directory under home to install kjots to. This way you are installing it for only one user and you don't need to be root to install it.
mkdir ~/kdelocalprefix
# Configure the build. The application is installed to a different location to
# the regular kjots from your distibution. Also, we create debug symbols
# so that we can use a debugger on the application.
cmake .. -DCMAKE_INSTALL_PREFIX=~/kdelocalprefix/ -DCMAKE_BUILD_TYPE=debug
# Build and install the application
make
make install

It makes sense to keep your real data separate from the data kjots uses when you're developing with it.

To run kjots without harming your existing data, you can start it like this:

export PATH=~/kdelocalprefix/:$PATH
KDEHOME=~/.kdelocal kjots

Or put those environment variables into a file and source it when you want to work on KJots.

• Krazy issues: http://www.englishbreakfastnetwork.org/krazy/reports/kde-4.x/kdepim/kjots/index.html
• Bugs: here
• Api docs: http://api.kde.org/4.1-api/kdepim-apidocs/kjots/html/index.html
• Rich text processing in qt
• Qt textedit example
• QTreeWidget
• QTextEdit
• Get help on Template:KDEML or #kontact on IRC.
• Porting KJots to KDE4 pillars

Documentation

• User documentation (Has not been significantly updated since 2004): http://docs.kde.org/stable/en/kdepim/kjots/index.html
• Template:UserbaseLink

Artwork

• Redesign the 'browser view' used to show static content (books). Currently it's very boring.

Redesign for 4.2

For KDE 4.2, KJots will undergo several changes to integrate more with some pillars of KDE- Akonadi, Nepomuk, and Plasma.

This will involve changes in how user data is stored and represented.

Current state in 4.1

Currently, KJots books and pages are subclasses of QAbstractModelItem (see http://websvn.kde.org/trunk/KDE/kdepim/kjots/kjotsentry.h?view=markup) Those classes are responsible for saving and loading data etc. Data is saved to .book files in the AppData directory. These .books files contain top-level books including any nested books.

The books are organized in a bookshelf, which is a QTreeWidget (http://websvn.kde.org/trunk/KDE/kdepim/kjots/bookshelf.h?view=markup).

Current plan for 4.2

The plan is to create some new representations of these objects to integrate with akonadi and nepomuk. This will allow multiple plasmoids to allow interaction with multiple or the same books. Additionally, nepomuk will give the possiblility to represent pages in a heirarchy of tags.

• http://thread.gmane.org/gmane.comp.kde.nepomuk/147
• http://thread.gmane.org/gmane.comp.kde.devel.pim/22743
• http://mail.kde.org/pipermail/plasma-devel/2008-September/001256.html

Plasmoid

Plasmoids would have a root index set as the root of the bookshelf, or rooted in one book or tag collection. For example, if you have a structure like:

• Book 1
  • Page 1
  • Page 2
  • Page 3
  • Sub-Book 1
    • Page 1
    • Page 2
• Book 2
  • Page 1
  • Page 2

Then it will be possible to show a plasmoid which displays only Book1 (including Sub-Book1), only Book2, only Sub-Book1, or all books in the bookshelf. Additionally, it will be possible to show only pages with the same tag.

Drag and drop between plasmoids will be possible as well as dragging books from the kjots application or kjots plasmoids onto the plasma workspace to create a new kjots plasmoid rooted at that book.

Mimetypes

The above drag and drop behaviour requires that a mimetype be registered for kjots books. Additionally, akonadi requires that kjots books and pages have mimetypes set to facilitate item retrieval. The mimetypes application/x-app-kde-kjots-book and application/x-app-kde-kjots-page will be used for these features.

Books and Pages

For akonadi support, KJotsBooks and KJotsPages wil be represented by simple structs and books will serialized/deserialized with a Akonadi::ItemSerializerPlugin. This will allow syncronization of pages being displayed in different plasmoids and the kjots application.

There are two options for what to serialize. The current state could be preserved, and top-level books would be Akonadi::Items and would be serialized. The payload would be the pages and nested books within the top-level book.

Alternatively, the system could be changed to represent each book and page as a distinct file. Each page would be a Akonadi::Item and could be serialized/deserialized individually. The payload would be the page content. Books would be Akonadi::Collection objects.

For tagging, nepomuk requires that either books/pages be saved in individual files, or custom book and page classes exist (or both). An ontology will be defined which describes how books and pages relate to each other, and tag capable classes will be generated from that.

I'm not sure if the same class can be used for serialization/deserialization and nepomuk tags. I will probably need AkonadiNoteBook, AkonadiNotePage, and NepomukNoteBook, NepomukNotePage.

Bookshelf

The kjots bookshelf will be replaced with an Akonadi::CollectionModel. Each book in the application will be a collection (which can be nested). Page data will be retrieved with the Akonadi::CollectionModel::Roles::CollectionRole. An akonadi resource will be used to retrieve the collections, add/remove/modifiy items etc.

Using nepomuk types, a proxy model can represent the tags on a particular page, so that pages can be grouped by tag on the left tree. Dragging items around on the tree would change the tags on the item.