Issue #78 - Cookbook Prototype

[taylonr]

Embedded tonicdev in an HTML page and started putting in examples from the Cookbook.

Added another top level nav item.

There are some examples, even in this prototype, that don't work as is. For example, Mess with the DOM needs a document, and Derivative of R.props for deep fields returns an error Cannot read property 'call' of undefined.

I wanted to get the PR up so the team can decide if they like having a top level menu item as well as using tonicdev, before I put more time in to implementing the remaining examples.

[CrossEye]

Thank you for a great start!

I think "Examples" might be a better name than "Cookbook" here. And I definitely think it should move before "GitHub" (although if we can, I'd love to move that over to the right.)

But there's a bigger concern in that I want to add a number of additional pages, and I don't think they can all get top-level real estate, and I'm not sure if there should simply be a single additional menu on the top for "More Info" that include this one, "Types", "Type Signatures", and other ones still to come. (The "Type Signatures" content is actually created; for now it's living in the wiki, but I believe it also should be promoted. "Types" still needs to be built.) I'd love to hear other ideas for this.

My biggest question right now, as I'm on a mobile device and haven't been able to actually download the code, is whether this is built manually or whether you're adding some automated process to convert from our Cookbook. While I would have no problem replacing the Cookbook with something new, I would like it to be something easy to contribute to, which probably means that maintaining a large HTML document would not be ideal. That doesn't mean it can't start that way, but we'd have to think about the future of it right away.

[davidchambers]

Very cool, @taylonr!

Could we fetch the examples by making an Ajax request to the wiki page, so that the website would stay up to date as the cookbook is edited?

[taylonr]

This example is built manually. Creating a bunch of tonic sections seems to slow down the page. It made me wonder if we don't do something like the docs and have a left hand nav of examples. When one is clicked, it could dynamically load the associated script into one tonic section.

That would (hopefully) allow it to be more performant, and also allow for easier extension later with examples.

I'll play around with it some and see what I can come up with.

[taylonr]

This iteration is ugly and needs some CSS styling love. Something I'm willing to do, but before I got that far I thought I'd push up the changes so people can play around with it and see if they like it.

I renamed Cookbook to Examples. For the time being, I've left it up on the top level. I figure that's easy enough to move around.

I also got rid of the manual examples. This seems to have helped the sluggishness, which makes sense. Now there is a single tonic instance on the page, instead of instance-per-example, which doesn't exactly scale.

The other thing I did was place a folder inside examples named code. The files in here are named using kebab-case. For example, there is a file named pick-list-values-by-index.js During the build process, these files are placed on the examples index.html page with an li per file. The text of the li is a capitalized version of the file name. So with our example, there's an li with the text Pick List Values By Index.

Inside the file is only the code snippet to be displayed inside tonic. So with our example, it's this:

let R = require('ramda');

// :: [Number] -> [a] -> [a]
var pickIndexes = R.compose(R.values, R.pickAll);
pickIndexes([0, 2], ['a', 'b', 'c']);

Below is how it looks now. An unstyled list of files. If you click on it, it will load the source from that file and place it into the tonic divider. The user can then click the run button (or update the code for what they want) and see the results.

In addition to the page being more performant, it also meets the other goal of allowing code samples to easily be added. As it stands, all that should need to happen is to add a single .js file inside examples/code with the new code snippet. The page can be rebuilt and it will include the new sample.

If y'all decide you want to pursue this process, I'll go back and make it look more presentable and add the remaining cookbook examples as code files. But I wanted to get it pushed up so when someone has a chance they can pull it down and play with it.

[buzzdecafe]

I renamed Cookbook to Examples.

I think cookbook is a better title. These are snippets that provide for possibly common problems that for one reason or another we elected not to include in the main lib. That sounds more cookbook; "Examples" I think of as demonstrating use of the library.

Now there is a single tonic instance on the page

Sounds like a good choice.

I won't be able to pull your repo until later this evening (earliest) but it looks to me like you are on the right track. Thanks for your work on this

[taylonr]

I'll keep playing with it some this week and see where I can get. I'm going to focus on implementation. I'll leave naming & placement up to the team.

And as for working on it, it's been my pleasure. I've never needed to customize make files before, and I learned more about handlebars, so it's been fun. Plus I get to give Ramda some love, which I'm all for.

[CrossEye]

This is great!

I really like the idea of keeping these in separate files. Perhaps your kebab-cased names are the best bet, but an alternative would be to put some YAML front matter in each one and use it in the build to create a JSON structure that is more flexible. I'm imagining starting with something like this:

---
title: Pick List Values By Index
tags:
  - Lists
  - Search
---
let R = require('ramda');

// :: [Number] -> [a] -> [a]
var pickIndexes = R.compose(R.values, R.pickAll);
pickIndexes([0, 2], ['a', 'b', 'c']);

But always allowing for the possibility of adding other tags later ("Section"?)

If this generated a JSON structure that had entries like

    {
        ...
        "pickByIndex": {"title": "Pick List Values By Index", "tags": ["Lists", "Search"]},
        ...
    }

then one can easily imagine various ways to enhance the Examples/Cookbook (ok, I guess I can live with that name, @buzzdecafe!) UI even if right now it's a simple list. Heck, unless the examples list grows huge, we could include the source code too (base64, perhaps) and avoid any AJAX calls at all. But none of that would have to happen right away.

Thanks again @taylonr! This is great stuff.

[taylonr]

I went back to Cookbook and I moved Github to the right, as someone said they liked it being separated from the other menu items.

I've added all the examples from the cookbook. Most of them work, a couple of them don't, and I'm not exactly sure why, but I cmd+c/cmd+v'd them so it shouldn't be a typo. A few of them I did know why they failed so I cleaned them up.

I liked the idea of having more metadata around the example. I had been trying to figure out how to do that without adding a separate file to fetch. So I took the yaml suggestion from @CrossEye and implemented it. The default fields I've got are:

• title
• name
• description
• source

I like the idea of tags, but wasn't sure how to tag the existing examples so I didn't add that right now.

I also updated the readme file so that it instructs folks how to add to the cookbook.

[taylonr]

Wanted to see if there's any feedback on this latest iteration.

[buzzdecafe]

apologies for the delay, i won't be able to look at this before the weekend.

[taylonr]

No worries

[CrossEye]

And I haven't looked at anything Ramda-related in a week. I might be able to look at this tomorrow, but it also might not be until the weekend. Thank you for your work on this, and for your patience.

[buzzdecafe]

Arg, how did this get dropped!!! apologies @taylonr -- are you interested in reviving this?

[CrossEye]

Wow, you're right. This was great stuff!

[taylonr]

I'm pretty swamped now with work and non-work projects. I don't have a problem if someone else wants to take this branch & run with it. I'm not sure when I'll be able to get back to it.

[buzzdecafe]

@taylonr I understand completely. My apologies for letting this slip.