Quick Views - Revision history

Patsyblefebre: /* Analysis: accessing the data */ now

2013-02-01T03:39:11Z

‎Analysis: accessing the data: now

Patsyblefebre: /* Code */ -

2013-02-01T03:34:22Z

‎Code: -

Patsyblefebre: -

2013-02-01T03:32:21Z

Patsyblefebre: /* Notes */ programmer

2013-02-01T03:29:37Z

‎Notes: programmer

Patsyblefebre: -

2013-02-01T03:28:17Z

Patsyblefebre: move image

2013-02-01T03:27:52Z

move image

Patsyblefebre: Quick Views (previously called ''Quick reports'')

2013-02-01T03:26:16Z

Quick Views (previously called ''Quick reports'')

Patsyblefebre: Gramps

2013-02-01T03:25:18Z

Gramps

Dsblank: /* Analysis: accessing the data */

2013-01-16T12:37:14Z

‎Analysis: accessing the data

Dsblank at 12:36, 16 January 2013

2013-01-16T12:36:16Z

@@ Line 134: / Line 134: @@
 ===Analysis: accessing the data===
+Now that your plugin runs, you need to open the database, start the document, access data, and write it out. We do this using the [[Simple Access API|Simple Database API]]. So,
-ow that your plugin runs, you need to open the database, start the document, access data, and write it out. We do this using the [[Simple Access API|Simple Database API]]. So,
 <pre>

@@ Line 20: / Line 20: @@
 ==Example 1==
 ===Code===
-[[File:GrampsQuickViewReport-40.png|thumb|right|400px|Quick Report context menu on Person View]]
+[[File:GrampsQuickViewReport-40.png|thumb|right|400px|Quick View context menu on Person View]]
-[[File:Siblings quick report result.png|thumb|right|200px|Quick Report example result]]
+[[File:Siblings quick report result.png|thumb|right|200px|Quick View Report example result output]]
 How better than to learn something than using an example?

@@ Line 8: / Line 8: @@
 Many users want to produce a report quickly for their specific needs, but are hindered by the fact they do not want to learn python fully, nor the intricacies of a complicated program like Gramps.
-For them, starting in Gramps 3.0 a new tool has been constructed: the quick reports. These reports are short textual reports that the user can register with Gramps, so they automatically appear in the context menu's.
+For them, starting in Gramps 3.0 a new tool has been constructed: the Quick Views. These reports are short textual reports that the user can register with Gramps, so they automatically appear in the context menu's.
-Accompanying this, a [[Simple Access API|simple database access]] and simple document interface has been constructed, so as to hide as much complexity as possible.
-{{-}}
+Accompanying this, a [[Simple Access API|simple database access]] and simple document interface has been constructed, so as to hide as much complexity as possible.
 ==Where to store my quick report==

@@ Line 189: / Line 189: @@
 ==Notes==
-The possibilities are enormous. If you are an experienced hacker, there is no need to limit yourself to the simple database API. Also, if you make a real report, you can at the same time register a quick report with default settings.
+The possibilities are enormous. If you are an experienced programmer, there is no need to limit yourself to the simple database API. Also, if you make a real report, you can at the same time register a quick report with default settings.
 [[Category:Developers/General]]

@@ Line 4: / Line 4: @@
 [[Image:GrampsQuickViewReportEdit-40.png|thumb|right|400px|Quick View context menu on Person Editor]]
-{{-}}
 ==Introduction==
 Many users want to produce a report quickly for their specific needs, but are hindered by the fact they do not want to learn python fully, nor the intricacies of a complicated program like Gramps.

← Older revision		Revision as of 03:26, 1 February 2013
Line 1:		Line 1:
−	Quick reports are reports that are available in the context menu's of person, family, ...	+	Quick Views (previously called ''Quick reports'') are reports that are available in the context menu's of person, family, ...

	They are easy to make by users, even with limited coding knowledge.		They are easy to make by users, even with limited coding knowledge.

@@ Line 5: / Line 5: @@
 ==Introduction==
 [[Image:GrampsQuickViewReportEdit-40.png|thumb|right|400px|Quick Report context menu on Person Editor]]
-Many users want to produce a report quickly for their specific needs, but are hindered by the fact they do not want to learn python fully, nor the intricacies of a complicated program like GRAMPS.
+Many users want to produce a report quickly for their specific needs, but are hindered by the fact they do not want to learn python fully, nor the intricacies of a complicated program like Gramps.
-For them, starting in GRAMPS 3.0 a new tool has been constructed: the quick reports. These reports are short textual reports that the user can register with GRAMPS, so they automatically appear in the context menu's.
+For them, starting in Gramps 3.0 a new tool has been constructed: the quick reports. These reports are short textual reports that the user can register with Gramps, so they automatically appear in the context menu's.
 Accompanying this, a [[Simple Access API|simple database access]] and simple document interface has been constructed, so as to hide as much complexity as possible.
@@ Line 13: / Line 13: @@
 ==Where to store my quick report==
-A quick report is one single file. You can store it in your plugins directory. Go into your home folder and go to the hidden directory '''.gramps'''. In this directory you will find the '''plugins''' directory. Just add your plugin there, and it will appear within GRAMPS.
+A quick report is one single file. You can store it in your plugins directory. Go into your home folder and go to the hidden directory '''.gramps'''. In this directory you will find the '''plugins''' directory. Just add your plugin there, and it will appear within Gramps.
 For the terminal users, you can get there as follows:
@@ Line 110: / Line 110: @@
 ===Analysis: registering the report===
-Let's analyse the above. We start at the bottom where the report is registered with '''register'''. This is the function GRAMPS will look for in your file. You need to give:
+Let's analyse the above. We start at the bottom where the report is registered with '''register'''. This is the function Gramps will look for in your file. You need to give:
-*{{man label|name}} = a unique name: a name GRAMPS identifies the plugin with, don't use spaces or strange symbols.
+*{{man label|name}} = a unique name: a name Gramps identifies the plugin with, don't use spaces or strange symbols.
 *{{man label|category}} = a special constant indicating where the report will be shown. You can use '''CATEGORY_QR_PERSON''' to see the report on person editor and view, or '''CATEGORY_QR_FAMILY''' to see the report on family editor or view.
-*{{man label|run_func}} = the function you create in this plugin and that GRAMPS will execute when the user selects your quick report in the menu
+*{{man label|run_func}} = the function you create in this plugin and that Gramps will execute when the user selects your quick report in the menu
 * {{man label|translated_name}} = the name of the report as it will appear in the menu
-* {{man label|status}} = is your report '''Stable''' or '''Unstable'''. Not used at the moment. On distributing GRAMPS we only include stable reports.
+* {{man label|status}} = is your report '''Stable''' or '''Unstable'''. Not used at the moment. On distributing Gramps we only include stable reports.
 *{{man label|description}} = a description of what your plugin does. This appears in a tooltip over the menu
 *{{man label|author_name}} = your name
@@ Line 184: / Line 184: @@
 ==Example 2==
-A second example can be found in the GRAMPS code. See [http://svn.code.sf.net/p/gramps/code/trunk/gramps/plugins/quickview/all_events.py all_events.py]. In this report, all events for a person are printed, and all events for a family. Two quick reports are hence registered, one for person, and one for family.
+A second example can be found in the Gramps code. See [http://svn.code.sf.net/p/gramps/code/trunk/gramps/plugins/quickview/all_events.py all_events.py]. In this report, all events for a person are printed, and all events for a family. Two quick reports are hence registered, one for person, and one for family.
 ==Notes==

@@ Line 176: / Line 176: @@
                       sdb.gender(child),
                       sdb.birth_date(child))
-                document.has_data = True
+            document.has_data = True
 stab.write(sdoc)
 </pre>

@@ Line 79: / Line 79: @@
              # only display if this child is not the active person
              if sdb.gid(child) != gid:
                  stab.row(child,
                          sdb.gender(child),
@@ Line 94: / Line 93: @@
 #------------------------------------------------------------------------
-register(
+register(QUICKREPORT,
-     name = 'a_unique_name_with_no_spaces',
+    id    = 'siblings',
      category = CATEGORY_QR_PERSON,
-     run_func = run,
+     runfunc = 'run'
-    translated_name = _("Siblings"),
-    status = _("Stable"),
-    description= _("Display a person's siblings."),
-    author_name="your name",
-    author_email="your email"
-−
 </pre>
@@ Line 119: / Line 121: @@
 ===Analysis: the run function===
 If the user clicks in the quick report menu on your report, the run function is executed with three parameters:
 <center>
-'''run_function(database, document, handle)'''
+'''run(database, document, person)'''
 </center>
-So, your report received from gramps the database on which to work, the document on which to write, and the handle (=unique identifier) of the object the user is on. For a person quick report, this is a person handle, for family, a family handle.
+So, your report received from gramps the database on which to work, the document on which to write, and the person of the object the user is on. For a person quick report, this is a person, for family, a family.
-−
 In this example, the function called is
@@ Line 132: / Line 134: @@
 ===Analysis: accessing the data===
-Now that your plugin runs, you need to open the database, start the document, access data, and write it out.
-We do this using the [[Simple Access API|Simple Database API]]. So,
+ow that your plugin runs, you need to open the database, start the document, access data, and write it out. We do this using the [[Simple Access API|Simple Database API]]. So,
 <pre>
 # setup the simple access functions
@@ Line 139: / Line 142: @@
 sdoc = SimpleDoc(document)
 </pre>
 prepares everything. Then we write a title on the document, an empty line under it, and a header, with the title, paragraph and header function:
 <pre>
 # display the title
 sdoc.title(_("Siblings of %s") % sdb.name(person))
 sdoc.paragraph("")
 </pre>
-As we will write a list, it is usefull to define the structure of your text one time, and reuse this. That is the '''__FMT''' constant, defined as
+Note that we use '''_''' for every string for translation, which comes from the line:
 <pre>
-__FMT = "%-30s\t%-10s\t%s"
+from gramps.gen.ggettext import gettext as _
 </pre>
 Everything is set up, now we write out the lines with all the siblings, leaving out the active person himself, as he is in the title field!
 <pre>
 # grab our current id, so we can filter the active person out
@@ Line 178: / Line 173: @@
          # only display if this child is not the active person
          if sdb.gid(child) != gid:
-             sdoc.paragraph(__FMT % (
+             stab.row(child,
-                    sdb.name(child),
+                     sdb.gender(child),
-                    sdb.gender(child),
+                     sdb.birth_date(child))
-                    sdb.birth_date(child)))
+                document.has_data = True
 </pre>
@@ Line 187: / Line 183: @@
 ==Example 2==
 A second example can be found in the GRAMPS code. See [http://svn.code.sf.net/p/gramps/code/trunk/gramps/plugins/quickview/all_events.py all_events.py]. In this report, all events for a person are printed, and all events for a family. Two quick reports are hence registered, one for person, and one for family.