15,534
edits
Changes
→Resources
# Develop your addon
# Package your addon
# List and document your addon
# Support it through the issue tracker# Maintain the code as GRAMPS Gramps continues to evolve
We'll now look at each of these steps in detail.
== Develop your addon ==
===Gramps 4.1 and earlier===
The [http://svn.code.sf.net/p/gramps-addons/code/ gramps-addons] subversion repository has the following structure:
* /gramps-addons
** /trunk
*** /contrib
*** /download
** /branches
*** /gramps41
*** /gramps34
**** /contrib
**** /download
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.
===Gramps 4.2 and later===
The [http://github.com/gramps-project/addons-source addons-source] git repository has the following structure:
* /addons-source
The [http://github.com/gramps-project/addons addons] git repository has the following structure:
* /addons
** /gramps42
*** /download
*** /listings
** /gramps50
*** /download
*** /listings
addon-source holds the source code for the addons with branches holding the version for different gramps. If you are working on a addon for gramps for gramps42 or later then you should be working in addons-source.
==== Setup the addon development tools for Gramps 4.1 and earlier ====
These steps show how to download and work with the addon development tools.
===Follow the development API for your tool===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 add replace your Gramps user plugin directory with a link to your addon development directory from your GRAMPS user plugin directory, like so:
cd ~/.gramps/gramps41/ mv plugins/* /wherever/trunk/gramps-addons/branches/gramps41/contrib/ rm -rf plugins link ln -s /homewherever/username/grampstrunk/gramps-addons/branches/gramps41/contrib developmentplugins
=== Commit your changes ===To commit your changes so that others can use your addon, .====Gramps 4.1 and earlier====For Gramps 4.1 and earlier 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:
## <pre>./make.py clean NewProjectName</pre>
# Add the project to the repository:
## <pre>svn add NewProjectName</pre>## <pre>svn commit -m "A message describing what this addon is"</pre>
Before making additional edits to your addon, you should:
# <pre>svn update</pre># <pre>svn status</pre># <pre>svn commit -m "A message describing the changes"</pre> Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager. ====Gramps 4.2 and later====For Gramps 4.2 and later follow these steps:# 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]]. git clone [email protected]:gramps-project/addons-source.git addons-source or if you do not have a Github account: git clone https://github.com/gramps-project/addons-source.git addons-source To switch to a local copy of the gramps42 branch: git checkout -b gramps42 origin/maintenance/gramps42 === Config === 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. At the top of the source file of your addon, you would do this: from config import config as configman config = configman.register_manager("grampletname") # register the values to save: config.register("section.option-name1", value1) config.register("section.option-name2", value2) ... # load an existing file, if one: config.load() # save it, it case it didn't exist: config.save() This will create the file "grampletname.ini" and put in the same directory as the addon. If the config file already exists, it remains intact. In the addon, you can then: x = config.get("section.option-name1") config.set("section.option-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): config.save() If your code is a system-level file, then you might want to save the config in the Gramps system folder: config = configman.register_manager("system", use_config_path=True) 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 config as configman config = configman.get_manager("grampletname") x = config.get("section.option-name1") === Localization === 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. 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 Then you can use the standard "_()" function to translate phrases in your addon. You can use one of a few different types of translation functions: # gettext# lgettext# ngettext# 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. See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3. '''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 names" is a hint for translators.
== Create a Gramps Plugin Registration file ==
== Get translators to translate your addon into multiple languages ==
== Package your addon ==
To create a downloadable package: python make.py build NewProjectName This will automatically include the following files in your build: * *.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 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".}} Then add the package to SVN: svn add ../download/NewProjectName .addon.tgz cd .. svn commit -m "Message describing changes" == 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 or gramps41 or master}} To create a listing:
That will create a series of files in the <tt>../listings/</tt> directory. Then add the updated listing to SVN: svn add ../listings/* cd .. svn commit -m "Message describing changes" == List and document your addon on the wiki== Document the addon in the wiki using the name {{man menu|Addon:NewProjectName}}. Edit [[3Plugins3.4]] or [[4.2 Third-party Plugins1_Addons]] and describe your addon. You can point to the addon.tgz in SVN or GIT as the downloadable file. == Miscellaneous commands == To build and compile translations for all projects to their download/Addon.addon.tgz files: python make.py build all To compile translations for all projects : python make.py compile all
== Support it through issue tracker ==
Visit https://gramps-project.org/bugs/view_all_bug_page.php and become a user. Suggest to check it regularly. == Maintain the code as GRAMPS Gramps continues to evolve == Remember that Gramps addons exist for many reasons and there are manyGramps 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://github.com/gramps-project/addons-source - Source code (Git)
* https://github.com/gramps-project/addons - downloadable .tgz files
;Gramps Addons site for Gramps 3.2 to Gramps 4.1.
* https://sourceforge.net/p/gramps-addons/ - Source code (SVN) and downloadable .tgz files