1. Inspiration
----------------------------------
I decided to create a new birthday reminder desktop applet because I just could not find
any birthday reminder software out there that would also support namedays.
In my part of Europe, nameday celebrations are equally important as birthdays
(sometimes even more, because unlike for birthdays, everyone knows when you celebrate
your nameday :)

To make the plasmoid usable for the rest of the world, the whole nameday stuff can be
turned completely off. This way you can use the plasmoid just like any other birthday
reminder that supports birthdays and anniversaries.

Internal logic of the plasmoid is inspired by the K Birthday Reminder, while for the
visualisation I learned many tricks by studying the Public Transport.


2. Features
----------------------------------
2.1 General
The plasmoid shows a sorted list of coming birthdays, namedays and anniversaries.
These events are shown in a table-like view, so you can easily select or reorder the
columns you want to see.

2.2 Contact data source
Contact information is taken from the selected Akonadi collection (e.g. Personal Contacts 
on the local computer, Gmail contacts, DAV groupware resource, etc.). 
Direct interface to KDE Address Book has been removed because the interface has been deprecated
in recent KDE releases and so its support may be removed anytime in the future.
Support for new data sources may be added in the future (CSV, Thunderbird, etc.) if demanded.

2.3 Contact filtering
Plasmoid allows to limit the set of contacts, for which the events are shown. Filtering options
(as well as data source itself) can be set individually for several instances of the plasmoid
(e.g. one plasmoid showing the family contacts, other plasmoid showing business contacts, etc.).

2.3.1 No filtering
By default, all contacts from the selected collection are taken into account (given that their
birthday, nameday and anniversary can be determined). 

2.3.2 Filtering by category
If you want to show only the contacts belonging to the selected Category (as shown in kaddressbook),
select the option "Filter by contact category" and type the category name (e.g. "Family") into the
"Match value" field.

2.3.3 Filtering by custom field (e.g. Gmail groups)
If you want to show only the contacts that have a particular value in one or more custom fields,
select the option "Filter by the custom field" or "Filter by multiple custom fields (prefix)" and 
type the custom field name or the prefix common for the group of fields. In the "Match value" input, 
type the value that must be matched by all contacts to be shown in the list.
Example (Gmail groups):
Akonadi googledata resource currently maps the Gmail groups into custom fields called
"Google-groupMembership_<group-number>", so you need to use a prefix "Google-groupMembership_".
Instead of the group name seen in the web interface (e.g. "My contacts"), the resorce currently
only reports the group Id, e.g. "http://www.google.com/m8/feeds/groups/name.surname%40gmail.com/base/6".
Type such id into the "Match value" field (you can see the values in kaddressbook under custom fields)
and find out which Id you need to use for the group you want to select.
Another Akonadi Google resource (libkgapi) combines all groups in a single custom field 
GCALENDAR-groupMembershipInfo. BirthdayList so far does not support filtering of contacts 
based on one particular group Id in this case.

2.4 Nameday options
2.4.1 Determining contact namedays
1. Defining a nameday date for every contact. Year will be ignored, contact's age is
shown based on his birthday. You can use the Anniversary field if you prefer namedays
over anniversaries, or you can define your own custom date field.
2. Looking up of your contact's given name in the country-specific nameday calendar. 
This option makes sense if the names are listed once per year and the your contacts have given names 
from your country's calendar
The options 1 and 2 can be combined; in case that the nameday date is defined for a particular
contact, it is always prefered over automatically generated nameday using the contact's given name.

2.4.2 Aggregation
Namedays can optionally be aggregated by name (one line standing for all contacts that
celebrate their nameday on the particular day) -> this is especially useful for frequently
used names such as Peter, etc. In such case, individual contacts can be 'unrolled' 
by double-clicking on the name entry. Names shown for aggregated nameday entries are taken
from the selectable country-specific nameday calendar.


3. Installation
----------------------------------
Unpack the tarball, go to its directory and execute
./install-birthdaylist.sh

If the build and installation succeeds, the plasmoid should show up in the add widgets
dialog. If not, please re-login to KDE or execute:
kquitapp plasma-desktop
kstart plasma-desktop

The plasmoid can be removed by executing
uninstall-birthdaylist.sh

To build the plasmoid, you will need development packages for KDE PIM, KDE4, Qt4 and cmake.
Exact package names are distribution-specific.


4. Troubleshooting
----------------------------------
4.1 Adding a custom nameday calendar
If you want to add a custom nameday calendar, create a new text file under the data engine
installation directory, e.g. /usr/share/apps/birthdaylist/namedaydefs/
with the name "namedays_<langcode>.txt, where <langcode> is replaced by your language.
The first line in this file contains a human-readable name for the language, remaining lines
contain name entries. Use already existing files to see the format. After the restart of plasma
you should see the new calendar.

4.2 KAddressBook
Since KDE 4.4 the preferred way to access to the old KDE Address Book is over the dedicated 
Akonadi resource. The plasmoid no longer supports the old interface since version 1.0. 
Please use Akonadi to read the KDE Address Book contacts.

4.3 Gmail contacts over Akonadi
To see your Gmail contacts, you need to install an additional package (e.g. libkgapi or akonadi-googledata).
These resources currently provide the names, birthdays and anniversaries for your contacts.
(custom date fields such as name days are not supported as of libkgapi v0.4.4).



5. Contributions
----------------------------------
Any feedback, ideas, suggestions or contributions are highly appreciated. Your support is
especially needed for internationalization and providing of additional nameday calendars.
