Changes

Jump to: navigation, search

Addons development

6,801 bytes added, 22:02, 9 August 2017
→‎Localization
{{man warn|Warning:|This page documents the API, methods, and best practices for developing a 3rd[[Third-party addon Addons|Third-party Addon]] for Gramps 34.2 and later . For 4.1.x and earlier, see [[Addons development old]]. }}
Addons for Gramps can extend the program in many different ways. You can add any of the following [httphttps://svngithub.code.sf.netcom/pgramps-project/gramps/codeblob/trunkmaster/gramps/gen/plug/_pluginreg.py types] of addons:
#Report
# Package your addon
# List and document your addon
# Support it through the issue tracker
# Maintain the code as Gramps continues to evolve
We'll now look at each of these steps in detail.
Note that this wiki expects that addons are developed under Linux; while it is possible to do so under Windows, some of the steps will vary and the process has not been fully debugged, so user beware.
== Develop your addon ==
The [http://svngithub.code.sf.net/pcom/gramps-project/addons/code/ gramps-source addons-source] subversion git repository has the following structure:
* /addons-source** /''IndividualNameOfAddon1''** /''IndividualNameOfAddon2''** ... The [http://github.com/gramps-project/addonsaddons] git repository has the following structure: ** /trunkaddons*** /contribgramps42
*** /download
*** /brancheslistings*** /gramps{{stable_branch}}gramps50*** /gramps32download**** /contriblistings The '''addon-source''' repository holds the source code for the addons with branches holding the version for different gramps. If you are working on an addon for gramps for gramps42, be sure to use the gramps42 git branch, as the default is master branch (currently gramsp 5.x). Example commands are shown below. Once you have your addon working in one branch, (say gramps42), then you will also want to copy it to the other branch (master), after you have tested it to work properly and edited the '.gpr.py' file appropriately. === Get a local copy of Gramps and its addons === These steps show how to download the addon sources. # Get an https://github.com/join account if you don't already have one.# Request GIT write access for the https://github.com/gramps-project/addons-source project by emailing the [[Contact#Mailing_lists|gramps-devel mailing list]]See also [[Brief_introduction_to_Git|git introduction]] for instructions on installing git and getting basic settings configured. Also https://help.github.com/articles/generating-an-ssh-key/ will help with setting up credentials for GitHub.To fully build and advertise a new addon will require local copies of the three repositories, the 'addons-source', 'addons' and the main Gramps source 'gramps'. This wiki assumes that the three git repositories local locations are all to be put into the users' home directory and named with the repository names. The three directories '''must''' be named as shown, and in the same base directory in order for the make.py script to work properly, however they don't have to be located directory in the users home directory. From your home directory;  git clone [email protected]:gramps-project/addons-source.git addons-source git clone [email protected]:gramps-project/addons.git addons git clone [email protected]:gramps-project/gramps.git gramps or if you do not have a Github account:  git clone https://github.com/gramps-project/addons-source.git addons-source git clone https://github.com/gramps-project/addons.git addons**** git clone https://github.com/gramps-project/gramps.git gramps This will create a copy of the addons-source tree in your home directory at "~/downloadaddons-source", and the other trees at their respective locations as well. To switch to a local copy of the gramps42 branch:
The contrib subdirectories hold the source code for the cd addons for a particular version. If you are working on a addon for gramps{{stable_branch}} then you should be working in gramps-addons/branches/gramps{{stable_branch}}/contrib. If you are working in gramps/trunk then you should use grampssource git checkout -addonsb gramps42 origin/trunkmaintenance/contrib.gramps42
==== Setup the addon development tools====These steps show how or to download and work with in the addon development tools.master branch:
{{man tip| 1=Tip |2=To use make.py as shown throughout this document, you may have to use:<br /> cd addons-source<pre>GRAMPSPATH=/path/to/gramps python make.py ...</pre> <br /> if the default ("../.. git checkout -b gramps42 origin/..") is not correct.}}master
# Checkout === Other pre-requisites ==={{man warn|These instructions, the gramps-addons files from make.py script etc.|are designed to operate in a Linux environment. {{man menu|They won't work on Windows without modifications.}}}}* Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then you must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is possible that the [https:normal invocation of <code>python</code> starts up Python 2.x, and that to start up Python 3.x requires invoking with <code>python3</code> or <code>python3.4</sourceforgecode> etc.net You can test the version by <code>python –version</projectscode> or <code>python3 –version</gramps-code>. If this is so, replace any usage of 'python' in the examples below with the appropriate invocation.* The make.py used in construction of the addons/ grampsrequires that the LANGUAGE environment variable be set to 'en_US.UTF-8'. * The make.py used in construction of the addons] projectrequires that the GRAMPSPATH environment variable be set to your path to the Gramps source tree.* intltool must be installed;:<code>sudo apt-get install intltool</code> ## cd into gramps trunk, for For example:### cd ~if your home directory is '/grampshome/trunk## Checkout gramps-addons:name' and you use the suggested path names, use### svn co https:<code>GRAMPSPATH=/home/name/svngramps LANGUAGE='en_US.UTF-8' python3 make.py .code.sf.net</pcode>to replace the <code>./gramps-addonsmake.py</code gramps-addons> in the examples below.## Change to trunk or branches/gramps{{stable_branch}} directory:### cd gramps-addons/branches/gramps{{stable_branch}}/contrib=== Create your addon subdirectory ===# * Make a new project directory in grampsaddons-addon/branches/gramps{{stable_branch}}/contribsource:## : <code>mkdir NewProjectName# Initialize the addon:## .</make.py init NewProjectNamecode>
===Follow the development API for your tool===
Create your NewProjectName.py and NewProjectName.gpr.py files.
 
Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a Plugin]] specifically.
=== Test your addon as you develop ===
To test your addon as you develop it it is suggested that you replace insert your NewProjectName plugin into your Gramps user plugin directory with a link to your addon development directory, like so:
cd ~/.gramps/gramps{{stable_branch}}gramps42/ mv plugins/* /wherever/trunk/gramps-addons/branches/gramps{{stable_branch}}/contrib/ rm -rf plugins ln -s ~/wherever/trunk/grampsaddons-addonssource/branches/gramps{{stable_branch}}/contrib pluginsNewProjectName NewProjectName
Your installed Gramps will search this folder (and subdirectories) for .grpgpr.py files, and add them to the plugin list.
If you have code that you want to share between addons, you don't need to do anything special. Currently, Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.
=== Commit your changes ===
To commit your changes so that others can see your addon source.
To * Remove the files that should not be added to GitHub:: <code>./make.py gramps42 clean NewProjectName</code>* Add the project to the repository:: <code>git add NewProjectName</code>* Commit it with an appropriate message: <code>git commit your changes so that others can use your -m "A message describing what this addon, follow these steps:is"</code>
# Get an http://sourceforge.net account if Before committing additional edits to your addon, you don't already have one.# Request SVN write access for the gramps-addon project by emailing one of the admins of the project (listed under the gramps-addon title next to the group icon) from http://sourceforge.net/projects/gramps-addons/# Remove the files that should not be added to SVN:## ./make.py clean NewProjectName# Add the project to the repository:## svn add NewProjectName## svn commit -m "A message describing what this addon is"
Before making additional edits * to make sure that outside changes do not affect your addon, commit: <code>git pull --rebase</code>* only the files you changed shouldbe in this list: <code>git status</code>* Commit it with an appropriate message:<code>git commit -m "A message describing the changes"</code>
# svn updateIf you have been given 'push' rights to GitHub 'gramps-project/addons-source', and when you are sure you are done and want to publish to the repository:# svn status# svn * to make sure that outside changes do not affect your commit : <code>git pull --m "A message describing rebase</code>: <code>git push origin gramps42</code> Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the changes"plugin manager.
=== Config ===
config.save()
This will create the file "grampletname.ini" and put in the same directory as the addon. If the settings config file already exists, it remains intact.
In the addon, you can then:
For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.
Note that these instructions will only work for Python strings, if you have a glade file, it will not get translated.
For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:
==== For Gramps 3: ====
from TransUtils import get_addon_translator
_ = get_addon_translator(__file__).gettext
 
==== For Gramps 4: ====
from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext
# lngettext
# sgettext
 
Gramps 3 also provides:
 
# ugettext
# ungettext
These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.
<pre>
register(PTYPE,
gramps_target_version = "34.42",
version = "1.0.0",
ATTR = value,
</pre>
[https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L76 PTYPE ] is TOOL, GRAMPLET, REPORT, QUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC. 
ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and '''version'''. '''gramps_target_version ''' should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. '''version ''' is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.
Here is a sample Tool GPR file:
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '34.42',
status = STABLE,
fname = 'AttachSourceTool.py',
</pre>
You can see examples of the kinds of addons [httphttps://svngithub.code.sf.net/pcom/gramps/code/trunk-project/gramps/plugins/ here] (for example, see [httphttps://svn.code.sfgithub.net/pcom/gramps/code/trunk-project/gramps/plugins/drawreport/drawplugins.gpr.py trunk/gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation [httphttps://svn.code.sfgithub.net/pcom/gramps/code/trunk-project/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.
Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.
Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.
 
The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin]] specifically.
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '34.42',
status = STABLE,
fname = 'library.py',
Runs when plugin is registered.
"""
print ("Hello World!")
</pre>
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '35.40',
data = ["a", "b", "c"],
)
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '35.40',
fname = "stylesheet.py",
load_on_reg = True,
def filters(namespace):
print ("Ok...", plugin.category, namespace, uistate)
# return a Filter object here
return filters
== Get translators to translate your addon into multiple languages ==
# * Initialize and update the template.pot for your addon:## : <code>cd ~/addons-source</code>: <code>./make.py gramps42 init NewProjectName</code>* You should edit the header of template.pot with your information, so it gets copied to individual language files.# * Initialize a language for your addon (say French, fr):## : <code>./make.py gramps42 init NewProjectName fr</code># * Update it from gramps and other addons:## : <code>./make.py gramps42 update NewProjectName fr</code># * Edit contribthe translations file manually:: <code>/NewProjectName/po/fr-local.po</code># * Compile the language:## : <code>./make.py gramps42 compile NewProjectName</code># * Add or update your local language file, and commit changes:## svn : <code>git add NewProjectName/po/fr-local.po</code>## svn : <code>git commit NewProjectName/po/fr-local.po -m "Added fr po file"</code>* If you have been given 'push' rights to GitHub 'gramps-project/addons-source', then;: <code>git push origin gramps42</code>
== Package your addon ==
To create a downloadable package:
: <code>./make.py gramps42 build NewProjectName</code> python or: <code>./make.py gramps50 build NewProjectName</code> for the master branch.
That Note that the  This will automatically include the following files in your build and copy : * *.py* *.glade* *.xml* *.txt* locale/*/LC_MESSAGES/*.mo Starting with Gramp 5.0, if you have additional files beyond those listed above, you should create a MANIFEST file in the root of your addon folder listing the files (or pattern) one per line, like this sample MANIFEST file:  <pre>README.mdextra_dir/*help_files/docs/help.html</pre> {{man note|Note:|Running the command '''make.py xxx build''' will increment the third number in your dotted version number of all addons in the gpr.py file. Consider this number to be a "build number".}} This will leave your 'addons-source' with untracked changes according to git. You should delete the 'NewProjectName/locale' directory. The updated 'NewProjectName/NewProjectName.gpr.py ' is ready to add and commit the next time you make other changes.: <code>rm –rf –v 'NewProjectName/locale'</code> Then add the package to GitHub:  <pre> cd '~/addons' git add gramps42/download/NewProjectName.addon.tgz git commit -m "Added new plugin: NewProjectName"</pre>or (for the master branch);<pre> cd '~/addons' git add gramps50/download/NewProjectName.addon.tgz git commit -m " Added new plugin: NewProjectName"</pre>
NOTE: Running the '''make.py build''' will increment the third number in your dotted version number of all addons in the gpr.py file. Consider this number to be a "build number".
== List your addon in the Gramps Plugin Manager==
''New for Gramps 3.4'': You need to then make your addon available in listings of various languages.
'''{{man warn|Gramps needs to have been built|Make sure you have already built gramps34 gramps42 or trunk'master. Change to the appropriate git branch in your gramps directory, and run 'python3 setup.py build' See [[Linux:Build_from_source]]}}
To create a listing:
python : <code>cd '~/gramps-addons'</code> or wherever you have built your addon: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps42 listing NewProjectName</code>or (for the master branch);: <code>cd '~/gramps-addons'</code> or wherever you have built your addon: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps50 listingNewProjectName</code>
That will create a series of files in the <tt>../listings/ </tt> directory.
Then add the package updated listing to SVNGitHub:
<pre> cd '~/addons' svn git add ..gramps42/downloadlistings/* git commit -m "Added new plugin to listings: NewProjectName.addon.tgz .."</pre>or (for the master branch);<pre> cd '~/addons' git add gramps50/listings/* cd .. svn git commit -m "Message describing changesAdded new plugin to listings: NewProjectName"</pre>
== List and document your addon on the wiki==
Document the addon in the wiki using the name '''"{{man menu|Addon:NewProjectName"'''}}. Edit [[4.2_Addons]] or [[5.0_Addons]] and describe your addon.
Edit [[Plugins3.4]] or [[Plugins4.0]] and describe your addon. You can point to the addon.tgz in SVN GitHub as the downloadable file.
== Miscellaneous commands ==
To build and compile translations for all projects to their download/Addon.addon.tgz files:
python : <code>python3 make.py gramps42 build all</code>
To compile translations for all projects :
python : <code>python3 make.py gramps42 compile all</code>
== Support it through issue tracker ==
Visit httphttps://www.gramps-project.org/bugs/view_all_bug_page.php and become a user. Suggest to check it regularly.
== Maintain the code as Gramps continues to evolve ==
 
Remember that Gramps addons exist for many reasons and there are many
Gramps developers that do support addons in various ways (translations,
triage, keeping in sync with master, download infrastructure, etc).
 
Some reasons why the addons exist; they provide:
* A quick way for anyone to share their work; the Gramps-project has never denied adding a addon.
* A method to continuously update and develop a stand-alone component, often before being officially accepted.
* A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
* A place for experimental components to live.
= Resources =
* [[Brief_introduction_to_Git|Git introduction]]
;Gramps Addons site for Gramps 4.2 and newer* https://sourceforgegithub.netcom/pgramps-project/addons-source - Source code (Git)* https://github.com/gramps-project/addons/ - Gramps Addons site downloadable .tgz files
[[Category:Developers/General]]
[[Category:Reports]]
[[Category:Gramplets]]
[[Category:Addons]]
Prculley
266
edits
Retrieved from "https://gramps-project.org/wiki/index.php/Special:MobileDiff/46593...64539"

Navigation menu