Permalinks in static output

[lbod]

@wkeese I know we've discussed this over email but I'd like to firm up the requirement. Permalinks in the dynamic runtime (node.js) are easy to manage, however when spidering static markup, permalinks won't work unless more work is done.

One option is to use a rewrite rule in apache (or whatever server is used) something like /api/dojo/parser > 301 redirect to /staticapi.html?module=dojo/parser. api.js could then use the qry parms to request the correct content pane href to load

Another option, though not great, would be adding config to switch off permalinks for static generated markup

[wkeese]

Yes, a 301 would work. I was thinking of a silent redirect (standard RewriteRule in apache), but either way is OK.

We should probably also have rewrite rules for the old php URLs that don't work anymore, i.e. index.php?...

[lbod]

So you mean an internal rewrite? I'm not sure internal rewrites could achieve anything here but I'll have a look as it's been a whilst since I did any proper apache admin. It probably needs a bit of path finding first

[wkeese]

Right, I meant internal rewrite.

I meant a simple rule that when there's no extension specified, tack on .html unconditionally, without any "path finding". I know apache has feature to try various options until it finds a match (ex: index.html, index.php) but I don't think we need that in this case?

[lbod]

Ah that was a different discussion.

I mean from the pov if you request a permalink /api/dojo/parser, node express routing intercepts that and serves the index/layout file with tabcontainer etc (also worth noting I differentiate requests for permalinks by testing if it's an xhr request). However if running static code under apache and clicking a permalink /api/dojo/parser, apache currently will serve the module html only (no tabcontainer etc)

[wkeese]

It sounds like you put your module HTML files in a place that conflicts with the permalinks. ISTM the module HML should be accessible through a different URL, for example /api/moduleHTML/dojo/parser.

/api/dojo/parser should always return the index/layout file with tabcontainer etc. and you shouldn't have to do checks about whether it's an XHR request or not.

[lbod]

I don't think I'm being clear on this There's another issue I need to address re URL's which I think you're alluding to but that's a different issue, this is purely about static docs.

If viewing using statically generated docs > how does client side code interpret default URL link behaviour e.g. load a new location e.g. /api/moduleHTML/dojo/parser (like what the PHP viewer does, a full page refresh) and load the index file plus it's module URL?

It needs JS to href load the module content pane when the page loads (like what the PHP viewer does), however I've made permalink URL loading SEO friendly, it includes the content pane HTML declaratively when the page is loaded via a permalink I'd like to keep that but it makes it more complex running statically w/o the app server. AFAICT I need to dynamically branch when it's static generated code, permalinks should maybe only point to something like api/index?initialModule=dojo/parser, reload the page but JS intercepts and does an href load (the current PHP viewer behaviour)

[wkeese]

running statically w/o the app server

I see, you are talking about:

1. running without Node or Apache
2. keeping the same UI as today
3. being SEO friendly

I suggest that /api/1.8/dijit/CalendarLite.html be:

<script>
    location.replace(location.origin + "/index.html?page=dijit/CalendarLite&v=1.8");
</script>
<h1 class="jsdoc-title constructorIcon36">dijit/CalendarLite ...
...

When a user navigates to /api/1.8/dijit/CalendarLite, it will do a client-side redirect to the index.html page, but when CalendarLite.html is loaded by Google or programatically by XHR, the <script> tag will be ignored.

[lbod]

Yes that's it but I think you'd only do something like that (though not using meta redirects) if it was static generated code only. There needs to be a switch (config.static==true ?) that tells JADE to generate different code in any case.

It could just be a case of something like

- if (config.static == true) // assuming JADE is generating code
      // or it could be added to dojoConfig via JADE instead so JS would check instead of -if (config.static)
      on(".jsdoc-permalink", "click", function (ev) {
         location.href = // split the URL into /index?module="1.8/dijit/CalendarLite"
      }

[wkeese]

I think you'd only do something like that (though not using meta redirects) if it was static generated code only.

When running via app.js, the code seems unnecessary but harmless. So, ISTM it doesn't matter if it's there or not.

There needs to be a switch (config.static==true ?) that tells JADE to generate different code in any case.

OK, but the flag should be automatically set depending on whether the user ran app.js or spider.js.

on(".jsdoc-permalink", ...)

Huh? What if the user types in a URL like http://dojotoolkit.org/api/1.8/dijit/Dialog.html directly in the address bar?

[lbod]

Huh? What if the user types in a URL like http://dojotoolkit.org/api/1.8/dijit/Dialog.html directly in the address bar?

Right, what I was suggesting is that for permalinks in static generated markup, JS binds to the permalink click and reloads the URL /index?module="1.8/dijit/CalendarLite" rather than the module markup/js having to do a meta redirect back to the index file. It's a client side page reload, IMO apache would be better doing that

Of course that means permalinks for static code would be different....

I don't mind either way but a meta redirect just seems like extra overhead and the user would see a reload of the page.

[wkeese]

I see, it's an optimization. And, I note that it's similar to the code we already have for clicking links to other modules:

// Setup listener so when you click on links to other modules, it opens a new tab rather than refreshing the
// whole page
on(context, on.selector("a.jsdoc-link", "click"), function(evt){
    ...

The problem with both your suggestion and my suggestion is: How does a user copy the permalink? Personally I always click the "Permalink" button and then copy the address from the URL bar. That would not be possible.

[lbod]

Exactly, TBH I'm not sure it even matters for static docs though (depends if those users really want it)

However, if the on(context, on.selector("a.jsdoc-link", "click"), function(evt){ just does a location.href to the index.html?module="1.8/dijit/CalendarLite" then it'll be shown in the address bar so users can still copy it, it would be a different URL pattern from "rest" like URL's though

But that's what I mean about apache (or nginx etc) doing a 301 redirect to the same qry param URL index.html?module="1.8/dijit/CalendarLite", it just hides it a bit more e.g. the client can still request /api/1.8/dijit/CalendarLite but get's a 301 redirect to index.html?module="1.8/dijit/CalendarLite". I'm maybe making more of this than is warranted but it's good to get it right first time

[lbod]

@wkeese I guess this is closed now after the changes we've both made over time? e.g. the ?qs=module

It works both in static html and node so I'm happy with that

[wkeese]

OK, sounds good.