Difference between revisions of "Date Handler"
m (→How to write a date handler) |
m (→How to write a date handler) |
||
Line 13: | Line 13: | ||
==How to write a date handler== | ==How to write a date handler== | ||
The framework for date handler plugins is in place. Here are the rules the language-specific plugins must obey to be compatible with the framework: | The framework for date handler plugins is in place. Here are the rules the language-specific plugins must obey to be compatible with the framework: | ||
− | + | ||
− | + | * The plugin must define '''two''' classes: one for parsing and one for displaying dates. | |
+ | |||
+ | * The parser class must derive from the [http://www.gramps-project.org/devdoc/api/2.2/private/DateHandler._DateParser.DateParser-class.html DateParser] class: | ||
from _DateParser import DateParser | from _DateParser import DateParser | ||
class MyDateParser(DateParser): | class MyDateParser(DateParser): | ||
... | ... | ||
:The parser class must provide <code>parse()</code> method. In fact, since the base class already defines such method, it is most likely that you will only need to re-define class constants and, maybe, the <code>init_string()</code> method. | :The parser class must provide <code>parse()</code> method. In fact, since the base class already defines such method, it is most likely that you will only need to re-define class constants and, maybe, the <code>init_string()</code> method. | ||
− | + | ||
+ | * The displayer class must derive from the [http://www.gramps-project.org/devdoc/api/2.2/private/DateHandler._DateDisplay.DateDisplay-class.html DateDisplay] class: | ||
from _DateDisplay import DateDisplay | from _DateDisplay import DateDisplay | ||
class MyDateParser(DateDisplay): | class MyDateParser(DateDisplay): | ||
... | ... | ||
:The displaer class mus provide <code>display()</code> method. Again, the base class already provides such method, but you may need to redefine it for your language, it is not that hard. | :The displaer class mus provide <code>display()</code> method. Again, the base class already provides such method, but you may need to redefine it for your language, it is not that hard. | ||
− | + | ||
+ | * The plugin must register itself as the date handler. This is done by inserting the following code at the end of your <code>_Date_xx.py</code> file: | ||
from _DateHandler import register_datehandler | from _DateHandler import register_datehandler | ||
register_datehandler(('xx_XX','xx','xxxxx','xx_YY'), | register_datehandler(('xx_XX','xx','xxxxx','xx_YY'), |
Revision as of 01:57, 12 July 2007
This article provides the rationale and requirements for the Date Handler plugin for GRAMPS, and it's localisation.
Why have different date handlers?
Different cultures and regions tend to have specific and different convetionts for parsing and displaying dates. For example, the month and day order is different between most european coutries and the US. Also, each language has its own set of acceptable modifier and qualifiers for the date: things like "from X to Y" or "between X and Y" may have different word order. Same with "around", "calculated", "estimated", plus the calendar names. See the Date Handler page for details on why and how to create such a plugin.
By providing date handlers, several problems are resolved.
- Dates entered by users of that language in almost any form can be parsed by GRAMPS.
- The displayed dates will look clear and correct to the users.
- Translators do not have to worry about translating regular expressions like
(from|before|between)
.
How to write a date handler
The framework for date handler plugins is in place. Here are the rules the language-specific plugins must obey to be compatible with the framework:
- The plugin must define two classes: one for parsing and one for displaying dates.
- The parser class must derive from the DateParser class:
from _DateParser import DateParser class MyDateParser(DateParser): ...
- The parser class must provide
parse()
method. In fact, since the base class already defines such method, it is most likely that you will only need to re-define class constants and, maybe, theinit_string()
method.
- The displayer class must derive from the DateDisplay class:
from _DateDisplay import DateDisplay class MyDateParser(DateDisplay): ...
- The displaer class mus provide
display()
method. Again, the base class already provides such method, but you may need to redefine it for your language, it is not that hard.
- The plugin must register itself as the date handler. This is done by inserting the following code at the end of your
_Date_xx.py
file:
from _DateHandler import register_datehandler register_datehandler(('xx_XX','xx','xxxxx','xx_YY'), MyDateParser,MyDateDisplay)
- where
MyDateParser
andMyDateDisplay
are the classes defined for parsing and displaying, and the items in quotes are language identifiers that may possibly be associated with your language. For example, different systems useru
,RU
,ru_RU
,koi8r
,ru_koi8r
,russian
,Russian
,ru_RU.koi8r
, etc. to identify the Russian language.
That's it for the requirements. The example date handling plugins can be found in _Date_xx.py
under the src/DateHandler
directory.