Enable multiple zips per tutorial page

[kodikos]

What it does

This adds the ability to specify multiple file sets of files in the tutorials repo for insertion into zip files that can be offered up from a single page. It also addresses accessibility by allowing the individual files to be accessed via links, but makes it clear which bundle they are in.

How it does it

The link is now an anchor that points to a location at the top of the page that has a list of links to the files to include in a zip. The list is hidden when JS is enabled and zips can be generated. The JS adds an event to all links whose href starts with #download-. The JS reads the file list next to the corresponding anchor and builds the zip.

How to do it

Some changes are required to the file list. Firstly, to add a level that contains an identifier for the zip name that also forms the anchor name used in the link. Secondly, that level is a key/value pair to overcome limitations with liquid's variable handling (weird associative array support). E.g.

files:
  - zipname: example1
    files: 
    - files/index.html
    - files/jquery.js
  - zipname: example2
    files:
    - files/script.js
    - files/style.css

[kodikos]

This is still a WIP, I know it needs some tidying. Just offering it up as an RFC.

[octopusinvitro]

The name attribute is obsolete in a tags (not in form elements, though).
You can use id="download-{{zip.zipname}}" instead.

Also, I personally wouldn't use an a element here, but a heading, so that there is an indication that this is a different section from what is strictly the tutorial copy. So something like, either:

<h2 class="tutorial-filelist__heading" id="download-{{zip.zipname}}">Files for {{zip.zipname}}</h2>

or maybe:

<section>
  <h1 class="tutorial-filelist__heading" id="download-{{zip.zipname}}">Files for {{zip.zipname}}</h1>
</section>

Or even:

<section>
  <h1>Download the tutorial files!</h1>

  <p class="tutorial-filelist__heading" id="download-{{zip.zipname}}">Files for {{zip.zipname}}</p>
  <!-- Files here... -->
  <p class="tutorial-filelist__heading" id="download-{{zip.zipname}}">Files for {{zip.zipname}}</p>
  <!-- Files here... -->
</section>

where zip.zipname is the corresponding name.

[octopusinvitro]

Skimmed over it and made some tiny comments, I'm running out of time now but will come back to it to review it properly and more thoroughly at some point during this week or next weekend.

Thank you for working on it! 👍

[kodikos]

Great, thanks for having a look :) I'm already into taking on most of your suggestions. As I say, this is bit of a WIP - was looking to make sure the proof of concept was good before putting more effort on final touches to make it prod ready (hence not wanting to PR it because then it gets full review treatment).
Btw, that also means you should run the gulp task, as I don't think the dl bundle is up to date!

[octopusinvitro]

Sorry I've been busy starting a new job and moving to a new city and couldn't find the time to review this properly.

I ran Jekyll and if I click a download link after I have already pressed another one, it adds the files of the previous zip to the current one, in the same zip. May be a bug that can be solved once you have finished polishing.

I tried to reason about the ui class and found it a bit confusing. I think it would be good for both you and your reviewers to maybe split this PR in two, one to add accessibility, and another to add multi-zip downloads. That way we can handle the separation of concerns better.

Nevertheless, I believe the code can still be simplified a bit. Thinking about the tutorial creators, I would replace:

files:
  - zipname: example1
    files:
    - files/index.html
    - files/jquery.js
  - zipname: example2
    files:
    - files/script.js
    - files/style.css

and the folder structure:

lesson3/
  files/
    // all the files mixed
  tutorial.md

with something simpler like:

files:
  - example1:
    - index.html
    - jquery.js
  - example2:
    - script.js
    - style.css

So that we can have a folder structure like:

lesson3/
  example1/
    // files for example1
  example2/
    // files for example2
  tutorial.ms

Having all the files for different tutorials mixed in the same folder doesn't seem like a good idea. For example, it's very common that they all have an index.html file. Having them in separate folders would also make it easier to drop folders in there for every new example. In the page template, in liquid, you can access a hash key with [0] and a hash value with [1]. That would simplify things a bit.

I also think removing the a tag and placing an id="download-etc" in the ul directly may simplify accessing the element and the code in the UI.

As I said, I think it would be desirable to break this PR into two different concerns to make it easier to reason about the code.

Again, thank you for working on it.