Build an exporter for Timeline
==============================

In Timeline an Exporter is used to export data from a Timeline to a file. The Exporter transforms the
data into a format that is understood by another application such as a web browser or a spreadsheet
program.

To be able to install an Exporter into Timeline it must be built as a Plugin. That means it must
implement all the methods defined in the class PluginBase. To install the Exporter it is placed in the
directory timlinelib.plugin.plugins.exporters

Step 1 - Inherit from PluginBase
--------------------------------

Say that we want to build an Exporter that creates a file to be used by the fictitious application
EventViewer. The first thing to do is to create a module with a class definition like this::

    from timelinelib.plugin.pluginbase import PluginBase

    class ExportToEventViewerFile(PluginBase):
        pass

Step 2 - Implement base class methods
-------------------------------------

Next step is to implement the methods defined in the PluginBase class::

    from timelinelib.plugin.pluginbase import PluginBase
    from timelinelib.plugin.factory import EXPORTER

    class ExportToEventViewerFile(PluginBase):

        def displayname(self):
            return _("Export to EventViewer...")

        def service(self):
            return EXPORTER

        def run(timeline, parent=None)
            pass

Note that the displayname() returns a string surrounded by _(). The reason for this is to make it
possible to internationalize the text.

The service() returns the constant EXPORTER which makes Timeline understand to create a menu alternative
for the exporter under File -> Export.

Step 3 - Write the implementation
---------------------------------

The implementation is written in the run() method.
This method is passed a timeline object, from which information about the timeline data can be
retrieved. The parent argument is the gui object from which the run function is called. For exporters,
this is the mainframe window.
The following timeline methods are useful for retrieving timeline data::

    timeline.get_all_events() Return a list with all events in a timeline
    timeline.get_containers() Return a list with all container events in a timeline
    timeline.get_categories() Return a list with all categories in a timeline

Useful Event functions::

    event.get_timeperiod() Returns the start and end of the event
    event.get_text() Returns the event title
    event.get_category() Returns the category associated with the event
    event.get_fuzzy() Returns True if the event has a fuzzy period
    event.get_locked() Returns True if ther event period is locked
    event.get_ends_today() Returns True if the event ends today
    event.get_description() Returns the event description
    event.get_icon() Returns the link to the icon
    event.get_hyperlink() Returns string with semicolon separated hyperlinks.
    event.get_alert() Returns alert information
    event.get_progress() Return the percentage done
    event.is_container() Returns True if it is a container
    event.is_subevent() Returns True if the event is inside a container
    container.get_subevents() Returns the events associated with the container
    

Step 4 - Install the Exporter
-----------------------------

Put the module that contains the Exporter in the timleinelib.plugin.plugins.exporters
directory. That's it!  Sample code::

    from timelinelib.plugin.pluginbase import PluginBase
    from timelinelib.plugin.factory import EXPORTER

    FILE_DESCRIPTION = _("Event viewer files")
    FILE_EXTENSIONS = ["txt"]
    PLUGIN_DISPLAYNAME = _("Export to EventViewer...")

    class SampleExporter(PluginBase):

        def displayname(self):
            return PLUGIN_DISPLAYNAME

        def service(self):
            return EXPORTER

        def run(self, timeline, parent=None):
            path = self._get_save_path(self.parent, FILE_DESCRIPTION, FILE_EXTENSIONS)
            if path is not None:
                result = self._transform_data(timeline)
                self._save_result_to_file(result, path)

        def _transform_data(self, timeline):
            collector = []
            for event in timeline.get_all_events():
            collector.append(self._transform_event(event))
            return "".join(collector)

        def _transform_event(self, event):
            return "%s %s\n" % (event.get_text(), event.get_time_period().get_label())

The TimelineExporter
--------------------

This class uses an input dialog to collect the export format as well as what data to export.
At the moment, only export to CSV is implemented, but the idea is that this class can be extended
to export other file formats as well.

The code is found at::

    timelinelib.plugin.plugins.exporters.timelineexporter.py