Difference between revisions of "Writing a plugin"

From Gramps
Jump to: navigation, search
m (Considerations)
 
(28 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 +
{{languages|Writing a plugin}}
 +
{{man tip|Writing a plugin|for Gramps version 3.2 and earlier}}
 +
{{stub}}<!--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 Github (Fork https://github.com/gramps-project/addons-source ) and submit a Pull Request.
* Add an entry of your plugin to [[Plugins3.2]]. 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 [[Third-party Addons]]. See [[Addon 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.2 and later) ==
 
== 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.
+
'''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.
 
Please see [[Addons development]] for complete details.
Line 31: Line 74:
 
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.
+
* Gramps supports right to left (RTL) languages such as Arabic. So never construct text strings by concatenation of parts. Always use full sentences/paragraphs with variable substitution, so that a RTL language can translate it correctly.
 
 
  
[[Category:Developers/General]] [[Category:Plugins]] [[Category:Developers/Tutorials]]
+
[[Category:Developers/General]]
 +
[[Category:Developers/Tutorials]]
 +
[[Category:Plugins]]
 +
[[Category:Addons]]

Latest revision as of 15:02, 15 December 2023

Tango-Dialog-information.png
Writing a plugin

for Gramps version 3.2 and earlier

Gramps-notes.png

This article's content is incomplete or a placeholder stub.
Please update or expand this section.


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 Github (Fork https://github.com/gramps-project/addons-source ) and submit a Pull Request.
  • Add an entry of your plugin to Third-party Addons. See Addon 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

  • Gramps supports right to left (RTL) languages such as Arabic. So never construct text strings by concatenation of parts. Always use full sentences/paragraphs with variable substitution, so that a RTL language can translate it correctly.