Partially recast the router API to be a lot more intuitive. (#2469 )

* Recast the router API to be a lot more intuitive.

Fixes #2387
Fixes #2072
Fixes quite a few issues reported on Gitter.

For `m.route.Link`:

- More intuitive
- More accessible
- More ergonomic
- It can be disabled
- It can be cancelled
- It can be changed
- Oh, and you can use it isomorphically.

For `m.route.prefix`

- You can *read* it.
- You can write to it, of course.
- It's literally just setting a property.

For the router itself (and the rest of Mithril):

- You can now `require("mithril")` and all its submodules without a DOM
  at all. There is a catch: you can't instantiate any routes, you can't
  mount anything, and you can't invoke `m.render` in any capacity. You
  can only use `m.route.Link`, `m.route.prefix`, hyperscript stuff, and
  `mithril/stream`, and you can use `m.request` with `background: true`
  if you use a global XHR polyfill. (You can't use `m.request` without
  `background: true` except with a DOM to redraw with.) The goal here is
  to try to get out of the way for simple testing and to defer the
  inevitable `TypeError`s for the relevant DOM methods to runtime.

  The factory requires no arguments, and in terms of globals, you can
  just figure out based on what errors are thrown what globals to
  define. Their values don't matter - they just need to be set to
  *something*, even if it's just `null` or `undefined`, before Mithril
  executes.

Had to make quite a few other changes throughout the docs and tests to
update them accordingly. Oh, and that massive router overhaul enabled me
to do all this.

Also, slip in a few drive-by fixes to the mocks so they're a little
easier to work with and can accept more URLs. This was required for a
few of the tests.

* Update changelog + numbers, add forgotten bundle option

* Add PR numbers to changelog [skip ci]

* Allow continuing to the next match by returning `false`.

* Update numbers again

2019-07-12 15:29:37 -04:00

4.8 KiB

Raw Blame History

How to read signatures

Signature sections typically look like this:

vnode = m(selector, attributes, children)

Argument	Type	Required	Description
`selector`	`String	Object`	Yes
`attributes`	`Object`	No	HTML attributes or element properties
`children`	`Array	String	Number
returns	`Vnode`		A vnode

The signature line above the table indicates the general syntax of the method, showing the name of the method, the order of its arguments and a suggested variable name for its return value.

The Argument column in the table indicates which part of the signature is explained by the respective table row. The returns row displays information about the return value of the method.

The Type column indicates the expected type for the argument.

A pipe (|) indicates that an argument is valid if it has any of the listed types. For example, String|Object indicates that selector can be a string OR an object.

Angled brackets (< >) after an Array indicate the expected type for array items. For exampe, Array<String> indicates that the argument must be an array and that all items in that array must be strings. Angled brackets after an Object indicate a map. For example, Object<String,Component> indicates that the argument must be an object, whose keys are strings and values are components

Sometimes non-native types may appear to indicate that a specific object signature is required. For example, Vnode is an object that has a virtual DOM node structure.

The Required column indicates whether an argument is required or optional. If an argument is optional, you may set it to null or undefined, or omit it altogether, such that the next argument appears in its place.

Optional arguments

Function arguments surrounded by square brackets [ ] are optional. In the example below, url is an optional argument:

m.request([url,] options)

Splats

A splat argument means that if the argument is an array, you can omit the square brackets and have a variable number of arguments in the method instead.

In the example at the top, this means that m("div", {id: "foo"}, ["a", "b", "c"]) can also be written as m("div", {id: "foo"}, "a", "b", "c").

Splats are useful in some compile-to-js languages such as Coffeescript, and also allow helpful shorthands for some common use cases.

Function signatures

Functions are denoted with an arrow (->). The left side of the arrow indicates the types of the input arguments and the right side indicates the type for the return value.

For example, parseFloat has the signature String -> Number, i.e. it takes a string as input and returns a number as output.

Functions with multiple arguments are denoted with parenthesis: (String, Array) -> Number

Component signatures

Components are denoted via calls to m, but with the selector argument set to a constant named in the relevant prose:

vnode = m(m.route.Link, attributes, children)

Argument	Type	Required	Description
`attributes.href`	`Object`	Yes	The target route to navigate to.
`attributes.component`	`String	Object	Function`
`attributes.options`	`Object`	No	This sets the options passed to `m.route.set`.
`attributes`	`Object`	No	Other attributes to apply to the returned vnode may be passed.
`children`	`Array	String	Number
returns	`Vnode`		A vnode.

Children here, if specified, are assumed to be able to be written as splat arguments, unless otherwise specified in prose.

An element with no sensible children and/or attributes may elect to elide the relevant parameter entirely, so it might look closer to this:

vnode = m(Component, attributes)

Argument	Type	Required	Description
`attributes.href`	`Object`	Yes	The
`attributes`	`Object`	No	Other attributes to apply to the returned vnode
returns	`Vnode`		A vnode

4.8 KiB Raw Blame History