README inadequately describes how HTTP requests map to pipeline templates / scripts

[filmaj]

After reading the README in this repo, I am confused how the pipelines we've put together in the devsite repo github.com/adobe/developer.adobe.com map to what is described in the README. We seem to be using completely different approaches. This is leading to confusion.

One point of confusion: there seems to be a magical invocation of pipelines based on filename, selector and extension. For example, in the devsite we have a html.htl and html.pre.js, and those are magically invoked on every HTTP request (presumably asking for text/html content). Can we explain this in the README? At a minimum the *.pre.js filename convention should be explained as it is currently not mentioned.

A specific further example of confusion: in the devsite, we use a dispatch mechanism on our 'global' HTML HTL template that sets a dispatch URL which esi:includes specific custom pages in our main html.htl template. This is how we're currently handling using vastly different templates for different non-ordinary sections of the site. But how is it that esi:includeing a index.default.html magically invokes default_html.htl? Could we please document this? The reason I ask is that we added another specially-templated page (the Open page) and we're finding that dispatching to index.open.html does NOT trigger the open_html.htl template...

[trieloff]

Hi Fil, the dispatching logic is handled in helix-publish or helix-simulator, but the basic idea is that you have to consider the request extension (the last part after the dot in the URL), everything after the first dot after the last slash in the URL, but before the extension).

URL	Extension	Selector	Action Name	Template Name	Pre JS
/foo.html	html		/html	html.*	html.pre.js
/foo.baz.html	html	baz	/baz_html	baz_html.*	baz_html.pre.js

Your open_html.htl not getting picked up is a bug (in publish, or simulator, or both).

[filmaj]

OK I will file my esi:include / dispatch weirdness as a separate issue in simulator (since ive only gotten so far as local dev with this)

[trieloff]

It would also be good to know if the issue happens when you access index.open.html directly (without ESI)

[tripodsan]

The reason I ask is that we added another specially-templated page (the Open page) and we're finding that dispatching to index.open.html does NOT trigger the open_html.htl template...

@filmaj is this still a problem?

[filmaj]

No, but the above table that @trieloff posted is valuable documentation. Could we put that in docs somewhere? Given this repo's README is pretty prominent on the main project-helix.io site, this README may be the right spot for it.

[bdelacretaz]

...the above table that @trieloff posted is valuable documentation...

Peanut gallery comment: from experience with Sling, the details about such things are best documented by readable automated tests - tables in docs tend to get out of sync with the code.

I'm not familiar enough with the JavaScript space to suggest how to write such readable tests for npm - in the Java world, https://github.com/intuit/karate does a great job with data-driven tests

Happy to discuss this next week at the Hackathon if desired, as part of the work on docs.

[filmaj]

I like that @bdelacretaz. The only caveat to that that I would add is that helix has a lot of tests, across many different packages, so then that becomes an exercise in discoverability.

There is no replacement for good usage documentation.

[bdelacretaz]

that becomes an exercise in discoverability....

I'm not saying you don't need docs, but those can stay at the "general principles" level and then link to the tests for The Absolute Truth.

And maybe also add "documentation tags" to the tests so that they can be discovered from a tags page, like https://sling.apache.org/tags/pipes.html which would list both documentation pages and tests.

[kptdobe]

Closed during backlog grooming session during hackathon. Reopen if needed or open a new one.