v3.0 High Level Design Documentation
Last updated: 2013-06-25
This product is a pure javascript fan-made application for downloading entries from offical compendium of D&D 4th edition, store them locally, and provide a mean to browse and search saved entries.
The aim is to provide important capabilities that is lacked by the official compendium, such as offline access, advanced search, multiple entry display. It is also hoped that this unofficial counterpart will provide a better user experience both on desktop and mobile devices.
For copyright and trademark reasons, the product name must not contains the name of the TRPG system it is designed for, and must not contain copyrighted materials, including images and styles used in the offical site. To comply with AGPL license, the deliverable should comes in source code and with full license.
- Can completely run offline once entries has been reterived or copied from other source.
- Both program and data can be copied/transfered easily across machines, e.g. from PC to phone.
- Scalable (low memory and cpu footprint) for 25k+ entries, ideally should run on low end smartphones.
- Single file deliverable for easy deployment and update.
- Cross platforms, both desktops and mobiles (min. 320x480).
- Intuitive, elegance, and impressive.
- Support multiple languages, starting with English and Chinese.
The main deliverable is an HTML+JavaScript based client application, but need to connect to server to reterive data entries.
Since all modern browsers has strict limit on cross original request and local file output, they can only be done by ActiveX and Java. Thus at this moment the data update only works on a PC.
For other activities, it is targeted to be very cross-platform, including Windows, Linux, Mac OS, Android, and iOS.
For easy deployment, the deliverable doesn't come with or depends on any data folder. This means images and applets must be embeded
For easy transfer of program state, all local data is stored in '(name of deliverable)_files' folder, so that windows will copy it together with the program.
For a balance between ease of development and platform support, the application use ECMAScript version 5 strict mode and does not support IE 8 and older browsers.
- First run
- Need a very quick intro and pointer to download page.
- Download / Update
- url: ?update
- Need to guide users step by step carefully.
- Can direct user to help screen while download is in progress.
- Expected to run on PC so can use more ram and cpu.
- Search / List entries
- url: ?list.(category.name)
- url: ?namesearch.(category.name)=(term)
- url: ?fullsearch.(category.name)=(term)
- url: ?advsearch.(category.name)=(term)&(field1)=(term1)&(field2)=(term2)
- Simple, intuitive, but with access to advanced features.
- Should be light weight and suitable for mobile use.
- View Entries
- url: ?view=(category1.name).(id1),(category2.name).(id2)
- Either single entry in a result list.
- Should support nice print outs, perhaps multi-columns.
- Config
- url: ?config
- Access to system configuration.
- Help
- url: ?help
- Guide on search and features.
- License
- url: ?license
- View script license
- View Source
- url: view-source:
- View script source
Considering the independency of these actions, the application use a page layout design, where each 'page' fills whole screen and focus on one task. The layout is responsive so that the same page may shows differently on different devices.
Future versions may support more advanced views for desktop, such as 'list and content' for view entries use case.
The code is separated into a few main parts.
- Binders
- build.xml - Ant build that compiles deliverable.
- html/html_template.html - Main deliverable's skeleton code.
- html/config.js - Default application config.
- UI
- html/action_*.html - Various pages, one html for each action.
- html/images.html - Most images are embeded here, to keep other code small.
- html/style_*.css - CSS styles.
- html/code_gui.js - Common UI logic, such as page switching.
- html/lang_*.js - l10n resources, including small images if necessary. Fallback language is English.
- Logic
- html/data_model.js - Contains data model, including index and listing.
- html/data_update.js - Handle data update logic, including a remote data model.
- html/data_search.js - Handle search logic.
- html/data_writer.js - Handles actual writing of data, so that model doesn't need to concern save format.
- html/data_reader.js - Handles actual reading of data, so that model doesn't need to concern save format or backward compatibility.
- Helpers
- html/sparrow.js - Self developed lightweight js library, including helpers and l10n system.
- java/Proxy.java - Java applet code for COR and file IO.
- cert/keystore.jks - For signing applet.
As explained in 2.1, all data is optional and resides in a data folder.
Because of browser limit on local AJAX, all JS data are in JSONP format except that the padding function is pre-determined and fixed. All JS data must contain version string so that future code can maintain backward compatibility.
Although category names may be displayed localised (cat.title), the actual name is always the one returned from server.
- catalog.js - List categories and total # entries of each.
- (Category name)/_raw.js - Main raw listing of a category's entries, used only for reindex. [JSONP]
- (Category name)/_listing.js - Processed listing of a category's entries, with parsed info. [JSONP]
- (Category name)/_index.js - Text index of all entries in a category. [JSONP]
- (Category name)/xxxxYYYY.js - Individual data content. File name is based on id. [JSONP]
- config.js - Contains user's preference. [JSONP]
- app.manifest - web application manifest.
- cache.manifest - cache manifest, need to be updated by data writer.