manual
389
edits
Changes
Add guide to how to modify add-ons etc
Don't understand me wrong, I take testing of my own code very seriously, but I didn't yet see anybody proposing a unit test system for the Gramps codebase that is sufficiently developer friendly so that anybody actually runs them.
</blockquote>
== Changes needed ==
This section provides a guide to the changes that are need to other code (for example add-ons) to interface with citations.
The user interface has been designed on the principle that Aunt Martha
should not need to know or even be aware that citations have changed.
Hence she will see a Source navigation with similar information to the
current view. There will be a disclosure triangle, but she can ignore
that. When she wants to add a source to a person or event, she clicks
on the add or add existing button, and gets a similar choice of source
as at present. (Again she can ignore the disclosure triangles). The
editor that appears is then very similar to the existing editor. Only
if a user particularly wants to share citations between objects do
they need to be aware of the change. The change is also intended to be
entirely compatible with GEDCOM.
Simple access to, and updating of, citations or sources does not
involve very extensive changes to existing code. The database changes,
the various editors, filters and proxies etc. have involved more
extensive changes.
The Citation primary object corresponds pretty closely to the
SourceRef secondary object. Data in the SourceRef is mapped to the
Citation. A Citation has the additional possibility of having media
objects attached (which is not possible with SourceRefs). A Citation
points to exactly one Source (the code may assume that here is always
a source object present).
The 'shape' of existing objects is unchanged. The change is that
SourceBase is replaced by CitationBase.
For creating data, where you previously created a SourceRef, you now
create a Citation object, and set_reference_handle() to point to the
Source object. There is a difference that you then have to do a
db.add_citation(citation, transaction). You then do an
obj.add_citation(citation_handle) instead of an
obj.add_source_reference(sourcerefobj) to add the SourceRef/Citation
to the object.
An example of the changes is:
http://gramps.svn.sourceforge.net/viewvc/gramps/branches/geps/gep-023-large-sources/src/plugins/lib/libgedcom.py?r1=18405&r2=18415
As far as data access is concerned, you do obj.get_citation_list()
instead of obj.get_source_references() to get a list of Citation
handles/SourceRefs respectively. With the citation, you then need to
do a db.get_citation_from_handle(citation_handle). Having got the
object, you do get_reference_handle() to get the source object handle.
An example of the changes is:
http://gramps.svn.sourceforge.net/viewvc/gramps/branches/geps/gep-023-large-sources/src/plugins/export/ExportGedcom.py?r1=18405&r2=18408
Note 1. The names of the functions and the return values are mostly
chosen to match the way notes are attached to objects, so
obj.add_citation(citation_handle) corresponds with add_note - both
taking handles as parameters, and obj.get_citation_list() corresponds
with get_note_list() - both returning handles.
Note 2. I am aware of PEP 8 and pylint and have followed them for new
code. However, where I have just been modifying existing code, or have
largely copied some existing code, I have retained the style of the
existing code, for example in terms of code layout, naming conventions
and the number of parameters or methods in a class. This may result in
a lowered pylint score.
[N.B. This is only a guide, no guarantee!]
== Links ==
