Make docs site downloadable / set up a template-based SPA option

[bob2517]

Add a button to download a zip containing a searchable docs site. All the files are statically generated anyway so it's not going to be much work to implement. Make an auto-generated JavaScript file that runs with the offline website grunt that contains the map of keywords and the search functionality. In the config, instead of using ajax, run the function instead. Just use a global window variable for storing the search object, or local storage, and the function can just return straight html to render..

[bob2517]

Could have an archive of older versions. Starting with the latest one on release. That way I don't have to maintain multiple versions live and it can stay simple. People worried about version changes can just download the matching archive zip.

Give it it's own page in the downloads section of the docs site.

[bob2517]

I'm going to set up a simple repo on github for downloadable versions of the docs. I think that's probably the most sensible way to do it. That way if the docs site disappears for any reason then there's still a stable place to get at the docs. I'm not going to put the whole docs on github as browseable online files, as it's going to be double work for me and not practical for my one-man setup. It's obviously also completely pointless as the docs site is faster anyway and people can just go there for online browsing.

[bob2517]

With the switch over to Action CSS in mind, I'm going to put it under the main action css org area and just have separate dirs on there for Active CSS and later on, Action CSS. Something like that.

[bob2517]

Or not. May just use an active CSS repo and put things there and do a new repo containing the old active css files. I dunno. Doesn't matter particularly at this point.

[bob2517]

Hmmm... from the look of it I might have to build an non-fancy version of the docs site for offline use due to limitations put on browsers for using local files. It would have been nice to be able to use ajax for local files, but I can see why it's been turned off in the browser. The search box would have to be fully JS, but then I was going to do that anyway. Will try a few things out. An alternative could be something using appcache and the filesystem API maybe. [edit] appcache was deprecated in 2016. Awesome.

[bob2517]

All the config needs to be inline. It's a good job I built inline ACSS into the core... I can see why people don't do this sort of thing much - like have app-like functionality for standalone offline websites that aren't annoyingly tied into a live system. A live system is no good for me - the whole point of this is to have a completely separate system for archive purposes. So that when Charlton Heston comes back, he can dust off the sand and open up the offline system. The code editor's going to be interesting. Thinking aloud, I could give the code editor an option to take in an inline template HTML tag containing all the files to edits in one place, and split that up into HTML, CSS and ACSS. Any extra JS I can just include in the ACSS for the code editor. Would actually be quite easy. Extract any style tags, extract any acss-style tags, and the remainder is the HTML. That would be a neat thing to do and a bit radical - a fully-functional standalone offline code editor. Wouldn't have to rely on potentially deprecating functionality from the browser either.

There's a fair amount of setup work to do to auto-generate the docs site offline for this to work. So now I've worked out what to do, I'm going to get that sorted out. And from that I can iron out the tweakage at a code generation level until it all works.

Currently I have in place auto-generation for the local database and php-driven admin area and the live static files. Just need to add in the generation of the offline system alongside that. And then make sure to remember to test the flow whenever I put a new release live...

This is probably going to take over a week to sort out, but it'll be a neat feature. Any serious language should really have downloadable docs as a given, and not have to rely on a live website to try and find ancient version code syntax. It's like the old days, when you'd have a manual on your desk for the language you were writing in, sort of.

[bob2517]

Now unsure if I can use github to store zip files. Need to check it out and will come up with an alternative plan if not. Worst case scenario I'll use my live server, but I'd rather not.

[bob2517]

Was thinking - how big would data take up for a docs search box? It shouldn't be more than 20kb, just for keywords and descriptions. If I can get the offline search box working, I could make the live site fully static and cacheable. [edit] - yes, someone has done this before - awesome - https://davidwalsh.name/adding-search-to-your-site-with-javascript. Also check out https://lunrjs.com/, but might be worth rolling own and putting into core as a tool - dunno, bit early to say.

[bob2517]

Ok - back on this at last! Target: end of the weekend, or thereabouts.

[bob2517]

As I can't run ajax commands locally, I'm looking at putting each page into a template tag and just converting the whole site into one file, and then on nav, hiding and showing template contents depending on the page. HTML files aren't that big. At worst, the overall file size of the whole site is going to be 250kb - I actually have no idea, but it shouldn't be more than that and probably less. Template tag inner stuff won't render, so page load should be fast enough. But nav would be very quick. Other stuff like css and images can be in different places. But all the HTML and example's code editor ACSS can just be in template tags and rendered when needed. Hmmm... need to check that ACSS in template tags doesn't currently load into current config. It shouldn't do, but will run into it shortly if there is a problem.

[edit] the offline docs is going to be around 1mb + examples. But it will load the whole thing only once due to the SPAness of it, so it's not a big deal.

[bob2517]

Switching to doing a grunt ACSS minifier for this to try and keep the size as low as possible. Would be good to get it done anyway, but I actually have a reason to do it now.

[bob2517]

Actually I don't want the minifier for what I need to do, but I'll do a version of it anyway - probably keep it a private repo until I'm happy it's going to do something useful.

[bob2517]

Update on this issue: It works as an template-based (rather than ajax) single-file SPA offline, but in order to replicate the live site exactly it still needs the following:

1. Code editor support - possible core fix indicated but upgrade needed to editor - DONE;
2. "Double-hash" support, like another hash within the new SPA image modal documentation beyond the file name hash - core fix - DONE;
3. Fix the case of inline ACSS not working when all the templates are loaded but it works on the first page - DONE;
4. Offline search - do this as a custom ACSS command - DONE;
5. (optional) Get the support form working offline, always going via temporary local storage until network connection so that submittance can be callback verified (would need the proposed PWA upgrades to work properly, so this is optional and will probably not happen for the 2.5.1 release). Technically the support form isn't needed for an archival docs site, nor is it in fact a PWA as it needs to be fully standalone, but this may/may not be a good place to test new functionality that would be used for a PWA.

[bob2517]

Implementing multi-hash support instead of double-hash support. It's just as easy and a bit cleaner to add more functionality rather than less for this. This will need documenting.

[bob2517]

Multi-level hash support is now done offline. Will probably commit tomorrow - just want to spend a day with it to make sure all good. I needed this for the offline docs site, which has pages like this:

file:///K:/random-stuff/acss-offline/index.html#/manual/spa-image-modal.html#horse

Note the double-hashness.

All pages in the standalone offline docs use the file index.html and all inner pages are based on hash links which open and close template contents based on @pages, automatically for offline files that use #/, so it works like an SPA without changing anything - the first hash is always taken to be the "page" reference in this scenario. But also needed to have another hash for the modal popup to open and for the modal to popup when the page is refreshed, like any good SPA.

But multi-dimensional hashes are now supported which makes this more flexible, so more than two hashes can be added. As long as triggers are in \@pages per the other upgrade for 2.5.1 then it works.

For that there are two new commands:

add-hash: "#myHash" "set a new title";         /* add-hash adds a hash if it isn't already there. */
remove-hash: "#myHash" "set an old title";     /* remove-hash remove a hash that is found. */

But this still works and does a similar thing without needing to use the add-hash/remove-hash commands if there's only ever one hash:

url-change: "#myHash" "set a new title";    /* replaces any hash(es) with #myHash */
url-change: "" "set an old title";          /* removes all hash links */

[bob2517]

Note for tomorrow: Test manual a tags.

[bob2517]

Fixed point 3 above now: "Fix the case of inline ACSS not working when all the templates are loaded but it works on the first page."

It was due to the fact I was inserting template content into the page from within a custom command and not the render command. That was due to a limitation in the syntax for rendering templates. But of course it doesn't go through the core and so doesn't get correctly escaped, etc. like it would on a regular ajax load.

I've added a new command into the core, load-as-ajax, which loads HTML based on a selector and treats it like an ajax response. That makes converting a live site to a standalone site a bit easier if you are switching techniques to a template-based SPA as the config structure can stay exactly the same, and only a few commands would need altering:

load-as-ajax: template[data-ref="{@href}"];

Then afterLoadAsAjax works the same as afterAjax. Works ok per tests, so marking that as done. Onto the offline search facility next! Will be back onto that at the weekend so have time to work out how best to do that.

[bob2517]

Docs to do for the new command. May change the name of the command before it gets committed...

[bob2517]

Offline search is done. It's actually more accurate than the MySQL fulltext search that I do on the live site so I should probably revisit that and work out what's going on with that. The technique I've used for this is, from the template that contains the page, I put each page section text into an array along with data from attributes in order to be able to show the search link for that page, then I just did a custom command when searching which splits each page by the search results to get a count of the appearing search term (there is probably a better way - will look at that), then put into another array of final results if it's there, and then finally sort the last array by number of appearances in descending order, then use the live site component loop to display the results as I used the same array format at the ajax result on the live site. Works a little bit faster than the live site.

I could have used a more pure CSS version of searching by using the attributes, but I didn't want to bloat the DOM any more than it is already and wanted "number of appearances" search results anyway.

I could further work on this to prioritise by page name, but it works quite well and there probably isn't much point.

[bob2517]

It's pretty much done now. Just some more tests to do. The ajax command example doesn't work, but then you can't have ajax commands from a "file://" location, so there's not much I can do about that.

[bob2517]

Oh yeah - need to do the link to be able to download it as a zip. Will work on that tomorrow.

Then I think it's just a case of updating the docs and 2.5.1 can get released. There's a few more stability fixes that I need to fix for this one, which is good.

[bob2517]

I've set up a private repo (until release) that will contain the docs site in SPA form. Each core release will get a corresponding docs release which will get tagged as a specific release so it's easy to download. I've set up a docs download page on the docs website which will give direct download links to the specific zipped release on GitHub.

So marking this as done now. Just the docs site to update and that should be it for 2.5.1.