From 0828e2cfb1e3eff61ae04a695b3d3a18e1480620 Mon Sep 17 00:00:00 2001 From: Wolfgang Meier Date: Sun, 20 Aug 2023 18:34:07 +0200 Subject: [PATCH] Document URL routing: small changes --- data/doc/documentation.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/data/doc/documentation.xml b/data/doc/documentation.xml index 80b6d4da..6dfc6513 100644 --- a/data/doc/documentation.xml +++ b/data/doc/documentation.xml @@ -3694,7 +3694,7 @@ declare function pmf:code($config as map(*), $node as element(), $class as xs:st
Adjusting the client-side URL handling With the two routes we set up for the documentation in the previous section, we cover the cases in which the entire page is loaded or reloaded by the browser, either by following a link, selecting a bookmark or pasting an URL into the location bar. However, TEI Publisher is a highly dynamic application and users can interact with the page without reloading it, e.g. by navigating to the next page of the document, selecting a toggle, clickling a link in the table of contents etc. Client-side interactions like this also need to be recorded and should be reflected in the URL, so users can copy or bookmark it. And the bookmarked link should later reconstitute the page in the state it was in when the bookmark was created. - All client-side web components in TEI Publisher therefore use a central state registry to track their state and reflect it in the URL. You can see this in action when you open any of the larger sample documents and navigate between its pages using the navigation buttons: the URL shown in the browser's location bar will change. For simple documents like Kant's Kritik, the current page displayed will be encoded in the root. If the divisions or pages to navigate by have an , this will be used instead and placed into the id parameter. The path to the TEI document is also tracked (it's the test/kant_rvernunft_1781.TEI-P5.xml part of the URL), though you won't see it change while navigating. + All client-side web components in TEI Publisher therefore use a central state registry to track their state and reflect it in the URL. You can see this in action when you open any of the larger sample documents and navigate between its pages using the navigation buttons: the URL shown in the browser's location bar will change. For simple documents like Kant's Kritik, the current page displayed will be encoded in the root parameter. If the divisions or pages to navigate by have an xml:id, this will be used instead and placed into the id parameter. The path to the TEI document is also tracked (it's the test/kant_rvernunft_1781.TEI-P5.xml part of the URL), though you won't see it change while navigating. For the documentation we deviate from this default pattern with the relative URL becoming documentation/{id}. We thus need to inform the client-side components about the change, so they know how to store their state into the URL. The central pb-page component provides two attributes for this: @@ -3710,8 +3710,8 @@ declare function pmf:code($config as map(*), $node as element(), $class as xs:st - The expression passed to url-template may reference any of the default parameters known to TEI Publisher components, in particular , , or . Additionally, any parameter supplied to a pb-view via the pb-param element can be referenced. Just have a look at the constructed URLs in the browser to see which parameters are being tracked for a specific page. Within TEI Publisher, URL templates will usually be rather simple. For the full syntax supported check the underlying javascript library. - To handle the URL for the documentation example, we set the URL template to documentation/:id?. This injects the parameter as part of the path, e.g. /documentation/api. The ? after the parameter indicates that it is optional. We also do not want the to the document to appear anywhere (it is always the same in the case), so we add it to . The resulting pb-page would thus look as follows: + The expression passed to url-template may reference any of the default parameters known to TEI Publisher components, in particular path, odd, view or id. Additionally, any parameter supplied to a pb-view via the pb-param element can be referenced. Just have a look at the constructed URLs in the browser to see which parameters are being tracked for a specific page. Within TEI Publisher, URL templates will usually be rather simple. For the full syntax supported check the underlying javascript library. + To handle the URL for the documentation example, we set the URL template to documentation/:id?. This injects the parameter as part of the path, e.g. /documentation/api. The ? after the parameter indicates that it is optional. We also do not want the path to the document to appear anywhere (it is always the same in the case), so we add it to url-ignore. The resulting pb-page would thus look as follows: ]]>