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 (NarrWeb) is a very popular Gramps report among Gramps users
- NarrWeb perhaps has more reported bugs and issues than any other component of Gramps
- NarrWeb should give a complete and accurate rendering in a web browser, which has many complexities
- The size and complexity of the NarrWeb code has grown considerably since its initial version
- People consistently want NarrWeb to do even more
- NarrWeb is now monolithic and has many interacting, brittle parts
- There are needs for new features (such as object linking from notes) that require changes in NarrWeb
- There is a need for a way of connecting other web reports (such as WebCal) onto NarrWeb
- 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:
- Break NarrWeb into manageable parts, each of which can be tested, refined, and replaced
- Move the complex, standard parts into a core that doesn't change as much, separate from more dynamic code
- Move to a two-pass, component driven process
- Reuse the Report plugin infrastructure for sub-components
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:
- Person List
- Place List
- Family List
- Note List
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.
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.
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.