2010/11/23 Doug Blank <doug.blank@gmail.com>
I've been studying and hacking on NarrWeb for a while in an attempt to
understand the best way forward. I've just created a GEPS outlining
the proposed changes [1]. Comments welcomed here, or on the GEP.


[1] - http://www.gramps-project.org/wiki/index.php?title=GEPS_022:_Narrative_Website_Refactor

This page documents a proposal to refactor Narrative Website into more
manageable parts, and to create a more solid foundation going forward.

Narrative Website

1. Narrative Website (NarrWeb) is a very popular Gramps report among
Gramps users
2. NarrWeb perhaps has more reported bugs and issues than any other
component of Gramps
3. NarrWeb should give a complete and accurate rendering in a web
browser, which has many complexities
4. The size and complexity of the NarrWeb code has grown considerably
since its initial version
5. People consistently want NarrWeb to do even more
6. NarrWeb is now monolithic and has many interacting, brittle parts
7. There are needs for new features (such as object linking from
notes) that require changes in NarrWeb
8. There is a need for a way of connecting other web reports (such as
WebCal) onto NarrWeb
9. It would be good to create parts that can be re-used in Gramps Connect

Because of these issues, a refactor is proposed. The main goals are:

1. Break NarrWeb into manageable parts, each of which can be tested,
refined, and replaced
2. Move the complex, standard parts into a core that doesn't change as
much, separate from more dynamic code
3. Move to a two-pass, component driven process
4. Reuse the Report plugin infrastructure for sub-components

Proposal Details

The main goal of the refactor is to move each major part of NarrWeb
into its own Web Report that can be run as a stand-along webreport, or
as a sub-report of the refactored NarrWeb.

The refactored NarrWeb shall be referred to as WebSite, and can
incorporate any other Web Report into a comprehensive web site.

For example, all of the following would be independent Web Report plugins:

* Homepage
* Person List
* Place List
* Family List
* Download
* Note List
* Calendar

Because these reports can be run stand-alone (ie, not from WebSite)
they can be tested independently.

In addition, third-parties can create additional Web Reports that can
be included to be run stand-alone or as an integrated page from

Website will contain all of the common functions needed when reports
are run together. There may need to be a library for common functions
when reports are run standalone.

Users will select what sub web reports they wish to include. (It would
be very handy here to have "named settings" for creating different
kinds of websites. However, this is a Feature Request that others have
asked for for other plugins as well, and is not covered here.)

When as user selects a sub web report for inclusion, a Options Page
will appear. Users can then set the options for the sub web report.

Each sub report will be responsible for the following:

* Collect its own data (but stored in a common place)
* Handle its own options
* Create its own pages

Perhaps the same WebSite options will be necessary for each sub report
when running the sub report in stand-alone mode.

Other Issues

It has been noted that NarrWeb currently uses some non-standard
functions, and does not fully use the HTMLDoc Backend. These types of
issues will be more fully addressed after the refactor.

I think one of the main issues is the filename issue.
In my mind, the Website should hold a pool, and  the parts must link to that pool to do stuff. A first pass can be done to build up the pool, after which one after the other report can do it's stuff.

PersonLists part wants to write out a list page and individual people pages.  The pool registers this. Extra is that this part als registers requests for other pages, eg source or place pages that it would like to link to.
The MapPart is a plugin the user downloaded from gramps-addons that adds a map to indiv people with the event places. It registers with the pool, together with the css file shipped with it.

The Website after the first pass starts to write pages. First it sets up the header, then the PersonList adds it's div elements for the indiv person page, the Website then passes this to the MapPart plugin which adds it's div sections, after which the Website adds the required footer section.

Note that in above the indiv person part adds links to sources. For this, it checks the pool first if the source will actually be written out, so as to only do a link when the source is present.

So, in this scheme, the website pool holds the filenames that will actually be written.


Increase Visibility of Your 3D Game App & Earn a Chance To Win $500!
Tap into the largest installed PC base & get more eyes on your game by
optimizing for Intel(R) Graphics Technology. Get started today with the
Intel(R) Software Partner Program. Five $500 cash prizes are up for grabs.
Gramps-devel mailing list