curran / example-viewer

A presentation tool and programming sandbox for code examples.

example-viewer

A presentation tool for code examples. Built using Redux and D3.

Try it out!

The above link shows examples in d3-in-motion, a project containing examples only, that uses this example-viewer package for presentation.

Features:

• CTRL + Right/Left arrow keys to navigate between examples.
• Live code editing environment with instant feedback.
• Click on a number to get a slider.
• Click on hex colors to get a color picker.

For Authors

This tool is not only for presentation, but also for creation.

• CTRL + S will save the current example
• CTRL + I create (insert) a new example

For these to work, you'll need to start the server locally with

npm start

This server uses Express and Node.js to write the examples to the file system.

To create a new project that just contains the content, and uses this package via NPM, create a new project and run

npm init
npm install -S example-viewer

In your package.json file, you can set up the example viewer to be your startup script:

  "scripts": {
    "start": "example-viewer"
  }

Then when you run npm start in your project, the index.html from this package will be copied into the root of your project, and the server will be started so you can save files.

Once example of a project that depends on this module is d3-in-motion.

example-viewer's Issues

screenshot

Have the runner fill exactly half width, no matter what resolution

Add notification for left right motion

When changing to the previous or next example, the change that comes through in a video recording is pretty subtle, so the viewer needs to read the example number to tell whether the motion was forward or backwards.

It would be nice to add an indicator or animation to indicate which direction the change was.

Ideally, this could be an animated transition where the whole page "swipes" to the left or right, getting replaced with the new example. This might be tricky to implement.

Another option is to use the Notifier infrastructure to display arrows. It turns out there are Unicode characters for arrows.

→

←

For when you hit the last or first example in the module:

⇥

⇤

Fixed header

The header should be fixed, so it stays visible while scrolling through longer examples.

Present _babelrc as .babelrc

GitHub Pages does not expose dotfiles, so we need to work around this.

Test case: https://curran.github.io/d3-in-motion/#2/1/4

Indent as 2 spaces

When hitting tab, currently a tab character gets added.

There should be a CodeMirror setting somewhere to change the behavior to add 2 spaces instead.

Use two digit numbering scheme

Problem: "example-10" comes before "example-9" in alphanumeric sorting.

Solution: Use two digits - "example-09" comes before "example-10".

This should apply to the directory names for units, modules, and examples.

d3.format("02") Should do the trick.

Report 404 errors

Currently if an example is not found, the app fails silently and doesn't show anything.

Ideally the error should be reported to the user. Perhaps one good way is to use the existing Notifier infrastructure.

README templating

One needed feature is an index of all examples. Perhaps the best solution would be to inject the index into the README of the project that uses example-viewer.

Similar to https://github.com/curran/screencasts/tree/gh-pages/introToD3#list-of-examples

Guard edges for example sets

Currently it's possible to go out-of-bounds for examples (e.g. -1, or beyond the last example).

Going beyond the last example is a feature in a sense, as it can be used to create new examples. It may be better, though, to have new example creation be an explicit operation.

Ultimately what would be best is to wrap around from one unit to the next.

Guard against missing title in HTML

Add Build Step?

Once index.html gets to be more than 500 lines, I think it's time to adopt a build step and modularize.

Since the index.html is copied into client projects as the complete frontend, the build step should bundle all the modules and inline the bundle into index.html.

Tentatively thinking Rollup and Handlebars for this.

use unpkg everywhere

in index.html

Module Montage

Rather than quickly scrolling through the examples for a given module in the beginning of a video, it would be better to show a static screen with the images for all the examples. This would be easy to do once we have thumbnails and preview images #19

Use file listing format that magicSandbox expects

This would allow this code to go away:

// Transform into the format that magicSandbox expects.
// TODO make this the overall format? Seems better, more explicit.
const files = {};
Object.keys(loadedFiles).forEach(function (name){
  files[name] = {
    content : loadedFiles[name]
  };
});

It would also allow more fields on individual files, like "loaded", "fetching".

Eschew selection.each

It feels icky, especially given that in all cases so far, it's only iterating over a single datum and we always know that in advance.

Rather than

body.datum(state)
  .call(componentA)
  .call(componentB);

, what if we use this pattern instead:

body
  .call(componentA, state)
  .call(componentB, state);

Ideally we could avoid d3.select(this), which feels like it should not be necessary.

Delete example operation

It's often the case that I want to delete an example, and shift all the subsequent examples "to the left".

There should be a new operation for deleting an example, maybe triggered by CTRL + D.

When the operation happens:

• The server needs to
  • delete the directory of the current example
  • rename directories of all subsequent examples to one number less (e.g. example-05 -> example-04)
  • rebuild index.json
• The client needs to
  • Update the index (in Redux store) such that it matches the one on the server (so that arrow keys navigate to the correct examples, not using the stale numbering).

Support mobile devices

Support multiple files per example

• Render multiple editor instances
• Render file name for each editor instance
• Adopt parseCode.js to support loading data and external scripts in the Runner
• Modify save backend to support multiple files
• Modify initialization process to load multiple files

Prefetch

When fetching the current example, it would be nice to prefetch the next example in the background so we don't need to wait for it to load on navigation.

UX for new example creation

If we guard against going beyond the edge of a list of examples, we should add the operation of creating a new example, which is a copy of the current example, and save it.

Maybe this could be CTRL+N

Eliminate Flickering

Add SHIFT + Arrow

It turns out CTRL + Arrow conflicts with a Mac key binding.

Perhaps add SHIFT + Arrow as an alternative for Mac folks.

Preserve scroll position between examples

There'a a fear of switching to the next example to check what it is, because doing so may destroy the current scroll position, causing the scroll to jump around in the edited video.

Ideally, the scroll position would be preserved when navigating between examples. This can be accomplished by adding a large spacer to the bottom of the page.

Adopt d3-component

Automated thumbnail generation

It would be sweet to automatically generate thumbnails for each example, and use those in the README template index.

Create index.json

With a listing of files for each unit, module, example.

Paves the way for

• README templating #18
• Support multiple files per example #6
• Guard edges for example sets #16

Add screenshot of present state to README

Make default route configurable