org-shell v7.0.0-8
Org-Shell
A shell for applications.
Routing using named query parameters
Serialization of resource state via updatable query parameters
Well-defined resource definitions, including loading data on/before page load
API
const h = require('react-hyperscript')
, { ORGShell, Link, Route } = require('org-shell')
, createStore = require('./store')
const resources = {
'': {
Component: () => (
h('div', [
h(Link('a'), {
route: new Route('hello', { name: 'Patrick }),
}, 'Home')
])
)
},
'hello': {
Component: (props) => (
h('p', `Hello, ${props.params.name}`)
)
}
}
const ApplicationContainer = props =>
h('div', [
h('header', 'Header'),
h('main', {}, props.children),
h('footer', 'Footer'),
])
const Application = ORGShell({
resources
}, ApplicationContainer)
ReactDOM.render(Application)
ORGShell(opts, Component)
The main piece of this library is the higher-order component ORGShell. It takes several options, two of which are required.
resources
(required): A map of resources (see below)NotFoundComponent
: A component to be rendered when a resource is not foundprocessOpts: { serializeValue, deserializeValue }
: Functions to serialize and deserialize values when translating to/from the page's addressextraArgs
: A value that should be passed to resources'onBeforeRoute
function
Definining resources
Resources are plain objects. The following keys are significant:
Component
(required): The React component that will be rendered for this resource. Several props are provided when this component is rendered:onBeforeRoute
: A function that will be executed (andawait
ed) before the route switches to the resource. This function will receive three arguments:params
: The static parameters passed to this resourceredirectTo
: A function that, when called, will redirect to a new routeextra
: The extra arguments passed to ORGShell initially
Route(resourceName, params, options)
A simple constructor to refer to a route within the application, along with (optionally) some static parameters, such as an item ID or similar.
Only meant to be used as an argument to components wrapped with Link
.
Link(Component)
A higher-order component to internally link between pages. Will provide an href property based on a route, and an onClick handler that intercepts clicks and calls pushState to change to a new resource. Takes one required prop, route
, which must be an instance of Route
.
Hooks
Several hooks are available to interact with your application.
useResource()
Provides information about the resource currently active in your application.
const { loading, resource, params, path } = useResource()
loading
: A boolean value indicating whether a resource'sonBeforeRoute
method has completedresource
: The definition of the resource defined when you initiated your applicationparams
: A key-value object of the query parameters present in the URLpath
: The path currently loaded in your application, without the resource options appearing in the hash
useOptions()
Provides the options currently passed to your active resource, as well as a function to update them. Unlike static parameters, changing the options will not cause the application to load a new resource.
const [ opts, updateOpts ] = useOptions()
opts
: A key-value object of dynamic options passed to the active resource. These options are persisted in the hash fragment of the URL. Each key-value pair is joined in the same way as multiple query parameters (e.g.k1=v1&k2=v2&k3=v3
), and the values of those pairs are run through thedeserializeValue
function passed when initializing your application. This allows, for instance, persisting JSON values as options in the URL.updateOpts(fn)
: A function to update the options passed to this resource. The function will be passed the current options and must return a key-value object representing the new options. These new options will be persisted in the URL after each value has been run through theserializeValue
function provided when creating the application.
useNavigation()
Provides a function to navigate the application to another resource.
const navigateTo = useNavigation()
navigateTo(route, pushState?)
: Make your application navigate to another internal resource. The first argument must be aRoute
object (see above). The second argument is a boolean value indicating how the browser will handle the navigation. If this argument istrue
, the new page will be inserted into the history using the browser'shistory.pushState
function. If the argument is omitted or passedfalse
, the browser will instead usehistory.replaceState
.
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago