38
edits
Changes
m
NOTE: to use make.py as shown throughout this document, you may have to use: GRAMPSPATH=/path/to/gramps python make.py ... if ==Follow the default ("../../..") is not correct.development API for your tool===
In At the top of the source file that defines the settingsof your addon, you would do this:
cm# load an existing file, if one: config.initload() # save it, it case it didn't exist: config.save()
cmconfig.save()
cm config = configconfigman.register_manager("system", use_config_path=True)
== List and document your addon ==
Edit [[Plugins3.4]] or [[Plugins4.0]] and describe your addon. You can point to the addon.tgz in SVN as the downloadable file.
Document the addon in the wiki using the name '''"Addon:NewProjectName"'''.
→Config
{{man warn|Warning:|This page documents the API, methods, and best practices for developing a 3rd-party addon for Gramps 3.2 and later }}
Addons for Gramps can extend the program in many different ways. You can add any of the following [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/plug/_pluginreg.py types ] of addons:
# Doc creatorReport# ExporterQuickreport# GrampletTool# Importer# Map serviceExporter#Doc creator# Plugin lib# QuickreportMap service# RelationshipsGramps View# ReportRelationships# ToolGramplet# ViewSidebar
Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:
== Develop your addon ==
The [http://svn.code.sf.net/p/gramps-addons /code/ gramps-addons] subversion repository has the following structure:
* /gramps-addons
The contrib subdirectories hold the source code for the 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 gramps-addons/trunk/contrib.
==== Setup the addon development tools====
These steps show how to download and work with the addon development tools.
{{man tip| 1=Tip |2=To use make.py as shown throughout this document, you may have to use:<br />
<pre>GRAMPSPATH=/path/to/gramps python make.py ...</pre> <br /> if the default ("../../..") is not correct.}}
# Checkout the gramps-addons files from the [https://sourceforge.net/projects/gramps-addons/ gramps-addons] project:
## ./make.py init NewProjectName
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 your Gramps user plugin directory with a link to your addon development directory, like so:
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 use your addon, follow these steps:
# Get an http://sourceforge.net account if 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 httpshttp://sourceforge.net/projectprojects/gramps-addons/memberlist.php?group_id=285429
# Remove the files that should not be added to SVN:
## ./make.py clean NewProjectName
Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.
from config import configas configman cm config = configconfigman.register_manager("view_placetreeview_0grampletname") cm# register the values to save: config.register("section.variable1option-name1", value1) cmconfig.register("section.variable2option-name2", value2)
...
This will create the file "view_placetreeview_0grampletname.ini" and put in the same directory as the addon. In If the addonconfig file already exists, you can then:it remains intact.
In the addon, you can then: x = cmconfig.get("section.variable1option-name1") cmconfig.set("section.variable1option-name1", 3)
and when this code is exiting, you might want to save the config. In a Gramplet that would be:
def on_save(self):
If your code is a system-level file, then you might want to save the config in the Gramps system folder:
This, however, would be rare; most .ini files would go into the plugins directory.
In other code that might use this config file, you would do this:
from config import configas configman cm config = configconfigman.get_manager("view_placetreeview_0grampletname") x = cmconfig.get("section.variable1option-name1")
=== Localization ===
'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")Where "rest" is the English string that we want to present and "remaining Remaining names" is a hint for translators which let them know that we mean "what's left" rather than "take a nap".
== Create a Gramps Plugin Registration file ==
</pre>
PTYPE is TOOL, GRAMPLET, REPORT, QUICKREPORTQUICKVIEW, 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.
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. '''Make sure you have already built gramps34 or trunk''' To do thatcreate a listing:
python make.py listing
cd ..
svn commit -m "Message describing changes"
== List and document your addon on the wiki==
Document the addon in the wiki using the name '''"Addon:NewProjectName"'''.
Edit [[Plugins3.4]] or [[Plugins4.0]] and describe your addon. You can point to the addon.tgz in SVN as the downloadable file.
== Miscellaneous commands ==
To build and compile translations for all projectsto their download/Addon.addon.tgz files:
python make.py build all
To compile translations for all projects to their download/Addon.addon.tgz files:
python make.py compile all
== Support it through issue tracker ==
= Resources =
* httphttps://gramps-addons.svn.sourceforge.net/viewvcp/gramps-addons/ - SVN browseGramps Addons site
[[Category:Developers/General]]
