16,602
edits
Changes
m
See Current code is now in trunk [http://gramps.svn1791082.sourceforgen4.netnabble.com/viewvc/gramps/branches/geps/gepGEPS023-merged-023into-largetrunk-sources/ SVN] and[http://gramps.svn.sourceforgetd4157519.net/viewvc/gramps/branches/geps/gep-023-large-sources/?view=tar tarballhtml Dec 05, 2011].
Current code is now in trunk [httpFinished://grampsGramps 3.1791082.n4.nabble.com/GEPS023-merged-into-trunk-td4157519.html Dec 05, 2011] 4
no edit summary
Proposed changes for enhancing GRAMPS by enhancing the mechanism for storing data from ‘large’ sources.
== User story (Problem that needs to be solved) ==
==== Issues ====
* Count at bottom right corner of window in citation tree view is incorrect. ''done'' fixed by change to allow filtering of secondary objects [{{Code Commit}}18706]* Add ID code for citations to the preferences dialog. ''done'' [http://gramps.svn.sourceforge.net/viewvc/gramps?view=revision&revision=18714{{Code Commit}}9cfdeaa8abc99dacf0e76bfa0d2973c1fcb23270]* Checks and warnings on 'Save' and 'Cancel' in EditCitation are not quite right. ''done '' [http://gramps.svn.sourceforge.net/viewvc/gramps?view=revision&revision=18549{{Code Commit}}a4df3034b6924da592d6a543b228fb0c5897aeb0]
==== Deferred ====
* '''src/plugins/import/ImportCsv.py''' Needs to be updated for citations ''done '' [http://gramps.svn.sourceforge.net/viewvc/gramps?view=revision&revision=18539{{Code Commit}}30501a9c5b05f83904abbcedaf14953b222b513a]* '''src/plugins/export/ExportCsv.py''' Needs to be updated for citations ''done '' [http://gramps.svn.sourceforge.net/viewvc/gramps?view=revision&revision=18539{{Code Commit}}30501a9c5b05f83904abbcedaf14953b222b513a]* '''src/plugins/import/ImportGeneWeb.py''' Needs changing for citations, but I can't do this as I don't have access to the application : ''done'' [http://gramps.svn.sourceforge.net/viewvc/gramps?view=revision&revision=18526{{Code Commit}}4e18e93ec02abbdb88920674e980964049c8cc6d]* '''src/plugins/export/ExportGeneWeb.py''' Needs changing for citations, but I can't do this as I don't have access to the application : ''done'' [http://gramps.svn.sourceforge.net/viewvc/gramps?view=revision&revision=18526{{Code Commit}}4e18e93ec02abbdb88920674e980964049c8cc6d]
* '''src/plugins/import/ImportProGen.py''' Needs changing for citations, but I can't do this as I don't have access to the application
* '''src/plugins/tool/TestCaseGenerator.py''' Needs to be updated for citations ''done'' [{{Code Commit}}975f4dc1180ccdc3e0e2d1fd36a8a6794653b0bc]* '''src/plugins/tool/Check.py''' This has been changed so that it runs, but it needs further enhancement to specifically check citation data ''done'' [{{Code Commit}}975f4dc1180ccdc3e0e2d1fd36a8a6794653b0bc]* '''src/webapp/grampsdb/models.py''' ??''done'' [{{Code Commit}}5892d0b586e7aa8e31b7933799a4baceddfa8d34]* '''src/webapp/grampsdb/libdjango.py''' ??''done'' [{{Code Commit}}5892d0b586e7aa8e31b7933799a4baceddfa8d34]* '''src/webapp/grampsdb/utils.py''' moved to src/webapp/utils.py?? ''done'' [{{Code Commit}}d97ece24a662595cec9ad3688c3dc5a79f3ae6c2]
* '''SimpleAccess, SimpleDoc and SimpleTable''' Needs to be changed for citations, but I am not yet sure how to test these.
* '''po/POTFILES.in and POTFILES.skip''' New files that need translation to be added [http://www.gramps-project.org/bugs/view.php?id=5395#c21977]
==== Queries ====
* The icon for citation might need to be changed to more closely meet the Tango guidelines. [http://www.gramps-project.org/wiki/index.php?title=GRAMPS_icon_set][http://gramps-project.org/2008/01/30-artwork/][http://gramps.svn.sourceforge.net/viewvcp/gramps/branchessource/maintenanceci/gramps-2.2.1/gramps22tree/src/images/sources.svg] ''done'' [{{Code Commit}}a689ac140d0fcf167a050dfd583ede2ca91a1b50]
* Should the default views be changed (e.g. remove the separate source and citation views and provide flat and tree presentations as separate presentations within a single view. Also, should there be a flat sources view).
* In the citationtreeview you can't filter on citation criteria (e.g. confidence) - This is because of the way the views work, the 'Source view' (or citationtreeview) is based on Sources only, so sorting, searching and filtering are just based on sources. If you want to filter the citations, then you have to use the citations view, and the citations filter in that view. ''done'' Improve treebasemodel to allow filtering of secondary object nodes. [{{Code Commit}}809c3bb833e6e94687c72a4aa82e3dbe5ebae19a]
* '''src/gen/proxy/refernced.py''' I have updated this for citations, but it does not appear to be used, so I have not tested it
* '''src/plugins/export/ExportFtree.py''' Not changed for citations because it does not appear to be used
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>
== Completion of the change ==
Although GEPS 023 'only' introduced one new object, it was a major change because it had ramifications throughout all of the Gramps code.
Here are some figures:
* The gep-023-large-sources branch was created on 1 Jul 2011.
* The branch was merged back into trunk on 4 Dec 2011.
* So it took almost 5 months to implement the change.
* 159 files were changed by the time the branch was merged back.
* There were 13,485 lines of u-diff.
I would like to thank Nick Hall for the enormous help and
encouragement I have received from him, especially in implementing the
tree model for two different primary objects which is largely his
code. Without his help, this enhancement would not have been possible.
Also thanks for help, testing and support from Michiel Nauta (advice
on upgrade transactions), John Ralls (fixes to some make files),
Jérôme Rapinat (fixes to translation files etc.), Benny Malengier
(advice on upgrade), Brian Matherly (svn admin), Rob Healey, Gary
Burton, Doug Blank and Cedric Scott and everyone else whose names I
may have missed.
== 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:
{{Code Commit}}6ee1af893fbe805a4c67d672d5175f78fcdc6596
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:
{{Code Commit}}e4383f0b46b5be1258e5f7e2caef2c4c48fa39b9
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 ==
=== Bug tracker ===
*{{bug|1022}}: Sources dialog hangs for 2 minutes after opening- This was closed unable to reproduce 2 Feb 2011 *{{bug|2918}}: Add Gedcom Source Citation Fields*{{bug|2924}}: Implement GEDCOM EVENT_TYPE_CITED_FROM and ROLE_IN_EVENT- This was closed as a duplicate of 2918 on 22 Jan 2011*{{bug|4491}}: (Feature request): Matching source and quality level- This was closed resolved fixed 28 Jan 2011
*{{bug|4913}}: (Feature request): Additional Event Filters
[[Category:GEPS|S]]
[[Category:Developers/Design]]
