rackt_history.javascript.txt

                                  ┏━━━━━━━━━━━━━━━━━━━┓
                                  ┃   RACKT_HISTORY   ┃
                                  ┗━━━━━━━━━━━━━━━━━━━┛

RACKT-HISTORY ==>                              ##Version 1.17.0
                                               ##Abstracts WINDOW.location|history:
                                               ##  - for legacy browsers
                                               ##  - for environment without DOM (e.g. unit testing, native apps)

                                  ┌──────────┐
                                  │   BASE   │
                                  └──────────┘

RACKTHISTORY.createHistory([CONF])->RHISTORY   ##Base function. CONF must provide:
                                               ##  - go(INT)
                                               ##  - getCurrentLocation()->RLOCATION
                                               ##Below are children of RACKTHISTORY.createHistory, that uses different implementations.

RACKTHISTORY.createBrowserHistory([CONF])      ##Uses WINDOW.location|history and WINDOW.onpopstate
RACKTHISTORY.createHashHistory([CONF])         ##Uses WINDOW.location.hash and WINDOW.onhashchange
                                               ##For legacy browsers.
RACKTHISTORY.createMemoryHistory([CONF])       ##Keeps state in memory. 
                                               ##Works without DOM (e.g. unit testing, native apps)
                                               ##CONF:
                                               ##  - entries 'PATH'[_ARR]: initial history

ENHANCER(RACKTHISTORY.createHistory)           ##Returns createHistory but with some extra features

                                  ┌─────────────┐
                                  │   HISTORY   │
                                  └─────────────┘

RHISTORY.push|replace(RLOCATION|'URL')         ##Adds history entry
                                               ##Do not do anything if same location
RHISTORY.go(INT)                               ##
RHISTORY.goBack|Forward()                      ##

RHISTORY.listen(FUNC(RLOCATION))->unlisten()   ##Fired on location change
RHISTORY.listenBefore(FUNC(RLCTON))->unlisten()##Fired before location change
                                               ##Return false to prevent change
                                               ##Return STR to fire CONF.getUserConfirmation(STR, FUNC(BOOL)) 
                                               ##(def for DOMHistory: FUNC(WINDOW.confirm(STR)))
RHISTORY.listenBeforeUnload                    ##Wrapper around WINDOW.onbeforeunload
(FUNC()->STR)->unlisten()                      ##Must use ENHANCER RACKTHISTORY.useBeforeUnload

                                  ┌──────────────┐
                                  │   LOCATION   │
                                  └──────────────┘

RHISTORY.createPath|Href(RLOCATION)->URL       ##
RHISTORY.createLocation
('URL'[, STATE])->RLOCATION                    ##

RLOCATION.key                                  ##ID
RLOCATION.pathname                             ##'PATH'
RLOCATION.search                               ##'?...'
RLOCATION.query                                ##Like RLOCATION.search but as OBJ
                                               ##Must use ENHANCER RACKTHISTORY.useQueries
                                               ##Can specify CONF:
                                               ##  - parseQueryString(STR)->OBJ
                                               ##  - stringifyQuery(OBJ)->STR
                                               ##Def use QUERY-STRING module, which is simple (no nesting)
RLOCATION.hash                                 ##'#...'
                                               ##To get scrolling behavior, must use ENHANCER from SCROLL-BEHAVIOR (0.3.0) among:
                                               ##  - useScrollToTop: always to top
                                               ##  - useSimpleScroll: to top on new location, to hash on back. Does not always work well
                                               ##  - useStandardScroll: to hash, by listening to scroll changes.
RLOCATION.action                               ##'PUSH|REPLACE|POP'
RLOCATION.state                                ##VAL (JSON serializable)

CONF.basename                                  ##Specify a base URL (def: <base href>)
                                               ##Must use ENHANCER RACKTHISTORY.useBasename
RLOCATION.basename                             ##RLOCATION.pathname does not include it