tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-07-08 04:19:27 +02:00
Code Issues Projects Releases Wiki Activity

Merge pull request #5390 from open-sausages/pulls/4.0/update-routing-docs

Browse Source 
Update docs to include new client-side routing
This commit is contained in:
Ingo Schommer 2016-04-26 14:19:06 +12:00
commit e3e503fda1
1 changed files with 19 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md
View File

@ -204,26 +204,30 @@ to ensure they're loaded unless already present. A custom-built library called
`jQuery.ondemand` (located in `framework/thirdparty`) takes care of this transparently - `jQuery.ondemand` (located in `framework/thirdparty`) takes care of this transparently -
so as a developer just declare your dependencies through the [api:Requirements] API. so as a developer just declare your dependencies through the [api:Requirements] API.
## Ajax Loading and Browser History ## Client-side routing
SilverStripe uses the HTML5 browser history to modify the URL without a complete window refresh, SilverStripe uses the HTML5 browser history to modify the URL without a complete
and load its UI via Ajax by hooking into browser navigation events (through the [Page.js](https://github.com/visionmedia/page.js) wrapper `javascript/src/router`). window refresh. We use the [Page.js](https://github.com/visionmedia/page.js)
routing library and provide additional SilverStripe specific functionality via the
`admin/client/src/lib/Router.js` wrapper.
This technique has an impact on how any Ajax load needs to happen: The router is available on `window.ss.router` and provides the same API as
In order to support browser history (and change the URL state), described in the
a CMS developer needs to fire a navigation event rather than invoking the Ajax call directly. [Page.js docs](https://github.com/visionmedia/page.js/blob/master/Readme.md#api).
The main point of contact here is `$('.cms-container').loadPanel(<url>, <title>, <data>)` ### Registering routes
in `LeftAndMain.js`. The `data` object can contain additional state which is required
in case the same navigation event is fired again (e.g. when the user pressed the back button).
No callbacks are allowed in this style of Ajax loading, as all state needs Top level (CMS section) routes are registered automatically via the config system.
to be "repeatable". Any logic required to be exected after the Ajax call Additional routes can be registered like so `window.ss.router('admin/pages', callback)`.
should be placed in jQuery.entinwe `onmatch()` rules which apply to the newly created DOM structures. Once registered, routes can we called with `windw.ss.router.show('admin/pages')`.
See `$('.cms-container').handleStateChange()` in `LeftAndMain.js` for details.
Alternatively, form-related Ajax calls can be invoked through their own wrappers, Route callbacks are invoked with two arguments, `context` and `next`. The [context object](https://github.com/visionmedia/page.js/blob/master/Readme.md#context)
which don't cause history events and hence allow callbacks: `$('.cms-container').submitForm()`. can be used to pass state between route handlers and inspect the current
history state. The `next` function invokes the next matching route. If `next`
is called when there is no 'next' route, a page refresh will occur.
It's worth noting that routes are invoked in the order they were registered,
not by specificity.
## PJAX: Partial template replacement through Ajax ## PJAX: Partial template replacement through Ajax