Difference between revisions of "Writing a plugin"

From Gramps
Jump to: navigation, search
(Write it)
(Share it)
(24 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
{{out of date|test it - instructions need updating}}
 
== Write it==
 
== Write it==
  
 
To get started writing a plugin, please see the following tutorials:
 
To get started writing a plugin, please see the following tutorials:
  
* [[Addons Development]] - for Gramps version 3.2
+
* [[Addons development]] - for Gramps version 3.2 and later
 
* [[Gramplets]]
 
* [[Gramplets]]
 
* [[Quick Views]]
 
* [[Quick Views]]
 
* [[Report-writing tutorial]]
 
* [[Report-writing tutorial]]
  
For more general GRAMPS development information, see:
+
For more general Gramps development information, see:
  
 
* [[Simple Access API]]
 
* [[Simple Access API]]
 
* [[Using database API]]
 
* [[Using database API]]
* [[Getting Started with GRAMPS development]]
+
* [[Getting started with Gramps development]]
 +
* [[Report_API|Report API]]
 +
* [[Report_Generation|Report Generation]]
 +
 
 +
== Test it ==
 +
 
 +
* See [[Unit_Test_Quickstart|Unit Test Quickstart]]
 +
* Check syntax issues with [[Programming_Guidelines#Pylint|Pylint]]
 +
 
 +
There is some samples of tests for localized [[Relationship_Calculator#Tests|Relationships calculators]] or [[Date_Handler#How_to_test_a_date_handler_for_your_locale|Date handlers]]:
 +
if __name__ == "__main__":
 +
    # Test function. Call it as follows from the command line (so as to find
 +
    #        imported modules):
 +
    #    export PYTHONPATH=/path/to/gramps/src
 +
    #    python src/plugins/rel/rel_it.py
 +
   
 +
    """TRANSLATORS, copy this if statement at the bottom of your
 +
        rel_xx.py module, and test your work with:
 +
        python src/plugins/rel/rel_xx.py
 +
    """
 +
    from Relationship import test
 +
    RC = RelationshipCalculator()
 +
    test(RC, True)
 +
 +
def _test(rc, onlybirth, inlawa, inlawb, printrelstr):
 +
    """ this is a generic test suite for the singular relationship
 +
            TRANSLATORS: do NOT translate, use __main__ !
 +
    """
 +
    import sys
 +
    import random
 +
    ...
 +
 
 +
cd /home/me/grampssvn
 +
export PYTHONPATH=/home/me/grampssvn/src
 +
python src/plugins/rel/rel_it.py
 +
 
 +
cd /home/me/grampssvn
 +
export PYTHONPATH=/home/me/grampssvn/src
 +
pylint src/plugins/rel/rel_it.py > /home/me/grampssvn/src/plugins/rel/it.txt
  
 
== Share it==
 
== Share it==
Have you written a plugin for GRAMPS you want to share with the world? Here's how you do it:  
+
Have you written a plugin for Gramps you want to share with the world? Here's how you do it:  
  
* Add the correct license. GRAMPS is GPLv2, you use the GRAMPS plugin system, so make sure you have the correct license at the top of your file. See [[Howto: Contribute to GRAMPS]]
+
* Add the correct license. Gramps is GPLv2, you use the Gramps plugin system, so make sure you have the correct license at the top of your file. See [[Howto: Contribute to Gramps]]
 
* Create a filename.tar.gz or filename.zip file of your plugin code
 
* Create a filename.tar.gz or filename.zip file of your plugin code
 
* Upload the code to this wiki
 
* Upload the code to this wiki
* Add an entry of your plugin to [[Plugins]]. See [[Plugin List Legend]] for meaning of columns. Please use these meanings and pay attention to details; this page is machine readable.
+
* Add an entry of your plugin to [[Plugins4.1]]. See [[Plugin list legend]] for meaning of columns. Please use these meanings and pay attention to details; this page is machine readable.
 
* Create a new wiki page, and refer to that page here, with a short description of what the plugin does
 
* Create a new wiki page, and refer to that page here, with a short description of what the plugin does
  
== Internationalize it (3.1 and prior) ==
+
== Internationalize it (3.2 and later) ==
 
 
This section describes a method of internationalizing your code for versions of Gramps 3.1 and earlier. The following section describes a new method for Gramps 3.2 and later.
 
 
 
There is a big possibility that you are not a native English speaker and want your report in your mother tongue. To enable others to use your report, and make it easy to include your report later in GRAMPS without large changes, do the following for text:
 
  
==== Translation function ====
+
'''The previous section describes a new method for Gramps 3.1 and earlier.'''
* Suppose you have a string Name, which you want for your own use in French, so Nom. Then write a translation function with the name _.
 
* For every string, pass it through your translation function: _("Name")
 
* Your translation function should then look like this:
 
  
mytranslation = {
+
This section describes a method of internationalizing your code for versions of Gramps 3.2 and later.  
    'Name' : "Nom"
 
    }
 
 
from gettext import gettext
 
import locale
 
lang = locale.getlocale()[0]
 
if lang:
 
    lang = lang.split('_')[0]
 
def _(string):
 
    if lang == 'fr':
 
        return mytranslation.get(string, gettext(string))
 
    else:
 
        return gettext(string)
 
  
Change here 'fr' by the language code of your language
+
Please see [[Addons development]] for complete details.
* If the report becomes part of GRAMPS, it will suffice to delete this code and replace it by
 
from gettext import gettext as _
 
* Note that you only need to include strings that are not yet a part of GRAMPS, as those will be translated automatically by the gettext routine
 
  
 
Also, have a look at [[Coding_for_translation#Tips_for_writing_a_translatable_report|Coding for translation]].
 
Also, have a look at [[Coding_for_translation#Tips_for_writing_a_translatable_report|Coding for translation]].
  
==== Pitfalls ====
+
==== Considerations ====
 
* We support right to left languages like Arabic, so never constructs text parts by concatenation of pieces. Always use full sentences/paragraphs with variable substitution, so that a right to left language can translate it correctly.
 
* We support right to left languages like Arabic, so never constructs text parts by concatenation of pieces. Always use full sentences/paragraphs with variable substitution, so that a right to left language can translate it correctly.
  
==== Template ====
+
[[Category:Developers/General]]
* There is a possible [[Media:additional.pot.gz|template]] which lists references. (see [http://www.gramps-project.org/bugs/view.php?id=2771 this issue].)
+
[[Category:Plugins]]
Translators may add references to their main translation.
+
[[Category:Developers/Tutorials]]
 
+
[[Category:Addons]]
== Internationalize it (3.2 and later) ==
 
 
 
This section describes a method of internationalizing your code for versions of Gramps 3.2 and later. The previous section describes a new method for Gramps 3.1 and earlier.
 
 
 
Please see [[Addons Development]] for complete details.
 
 
 
 
 
[[Category:Developers/General]] [[Category:Plugins]] [[Category:Developers/Tutorials]]
 

Revision as of 23:29, 7 July 2015

Gramps-notes.png This page's factual accuracy may be compromised due to out-of-date information. Please help improve the Gramps Wiki as a useful resource by updating it.

Write it

To get started writing a plugin, please see the following tutorials:

For more general Gramps development information, see:

Test it

There is some samples of tests for localized Relationships calculators or Date handlers:

if __name__ == "__main__":
   # Test function. Call it as follows from the command line (so as to find
   #        imported modules):
   #    export PYTHONPATH=/path/to/gramps/src 
   #    python src/plugins/rel/rel_it.py 
   
   """TRANSLATORS, copy this if statement at the bottom of your 
       rel_xx.py module, and test your work with:
       python src/plugins/rel/rel_xx.py
   """
   from Relationship import test
   RC = RelationshipCalculator()
   test(RC, True)

def _test(rc, onlybirth, inlawa, inlawb, printrelstr):
   """ this is a generic test suite for the singular relationship
           TRANSLATORS: do NOT translate, use __main__ !
   """
   import sys
   import random
   ...
cd /home/me/grampssvn
export PYTHONPATH=/home/me/grampssvn/src 
python src/plugins/rel/rel_it.py
cd /home/me/grampssvn
export PYTHONPATH=/home/me/grampssvn/src 
pylint src/plugins/rel/rel_it.py > /home/me/grampssvn/src/plugins/rel/it.txt

Share it

Have you written a plugin for Gramps you want to share with the world? Here's how you do it:

  • Add the correct license. Gramps is GPLv2, you use the Gramps plugin system, so make sure you have the correct license at the top of your file. See Howto: Contribute to Gramps
  • Create a filename.tar.gz or filename.zip file of your plugin code
  • Upload the code to this wiki
  • Add an entry of your plugin to Plugins4.1. See Plugin list legend for meaning of columns. Please use these meanings and pay attention to details; this page is machine readable.
  • Create a new wiki page, and refer to that page here, with a short description of what the plugin does

Internationalize it (3.2 and later)

The previous section describes a new method for Gramps 3.1 and earlier.

This section describes a method of internationalizing your code for versions of Gramps 3.2 and later.

Please see Addons development for complete details.

Also, have a look at Coding for translation.

Considerations

  • We support right to left languages like Arabic, so never constructs text parts by concatenation of pieces. Always use full sentences/paragraphs with variable substitution, so that a right to left language can translate it correctly.