diff options
Diffstat (limited to 'src/page/index.js')
| -rw-r--r-- | src/page/index.js | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/src/page/index.js b/src/page/index.js index f580cbe..fc0c646 100644 --- a/src/page/index.js +++ b/src/page/index.js @@ -17,6 +17,76 @@ // Usually this will simply mean returning the appropriate thingData array, // but it may also apply filter/map/etc if useful. // +// dataSteps {...} +// Object with key-to-functions matching a variety of steps described next. +// In general, the use of dataSteps is to separate data computations from +// actual page content generation, making explicit what data is carried +// from one step to the next, and letting the build/serve mode have a +// standardized guideline for deciding when to compute data at each step. +// +// Important notes on the usage of dataSteps: +// +// - Every dataStep function is provided a `data` object which stores +// values passed through to that step. To save data for a coming step, +// just mutate this object (set a key and value on it). +// +// - Some dataStep functions return values, but not all do. Some are just +// for computing data used by following steps. +// +// - Do not set any data properties to live wiki objects or arrays/objects +// including live wiki objects. All data passed between each step should +// be fully serializable in JSON or otherwise plain-text format. +// +// **NB: DATA WRITES ARE CURRENTLY DISABLED. All steps exclusively applicable +// to data writes will currently be skipped.** +// +// dataSteps.computePathsForTargets(data, target) +// Compute paths at which pages or files will be generated for the given +// target wiki object, returning {type, path} pairs. Data applied here, +// such as flags indicating which pages have content, will automatically +// be passed onto all further steps. +// +// dataSteps.computeDataCommonAcrossMixedWrites(data, target) +// Compute data which is useful in a mixed list of any path writes. +// This function should only be used when data is pertinent to more than +// one kind of write, ex. a variable which is useful for page writes but +// also exposed through a data write. Data applied here is passed onto +// all further steps. +// +// dataSteps.computeDataCommonAcrossPageWrites(data, target) +// Compute data which is useful across more than one page write. +// Use this function when data is pertinent to more than one page write, +// but isn't relevant outside of page writes. Data applied here is passed +// onto further steps for page writes. +// +// dataSteps.computeDataCommonAcrossDataWrites(data, target) +// Analagous to computeDataAcrossPages; for data writes. +// +// dataSteps.computeDataForPageWrite.[pathKey](data, target, pathArgs) +// Compute data which is useful for a single given page write. +// Note that dataSteps.computeDataForPage is an object; its keys are the +// possible path keys from computePathsForTargets() for page writes. +// Data applied here is passed onto the final write call for this page. +// +// dataSteps.computeDataForDataWrite.[pathKey](data, target, pathArgs) +// Analogous to computeDataForPageWrite; for data writes. +// +// dataSteps.computeContentForPageWrite.[pathKey](data, utils) +// Use data prepared in previous steps to compute and return the actual +// content for a given page write. The target wiki object is no longer +// accessible at this step, so all required data must be computed ahead. +// +// - The returned page object will be destructured for +// usage in generateDocumentHTML(), `src/write/page-template.js`. +// +// - The utils object is a set of bound functions handy for any page +// content. It is described in `src/write/bind-utilities.js`. +// +// dataSteps.compteContentForDataWrite.[pathKey](data, utils) +// Analogous to computeContentForDataWrite; for data writes. +// NB: When data writes are enabled, the utils object will be uniquely +// defined separate from what's provided to page writes. +// // write(thing, {wikiData}) // Provides descriptors for any page and data writes associated with the // given thing (which will be a value from the targets() array). This |