a tool to add new perspectives and layers of interactivity on top of existing code. Explore a live demo right here, learn more about the ideas behind Study Lenses right here
$ npm install$ npm run test-content
If you would like to this server with files from your computer that are not in
/test-content you will need to install it as a global dependency.
git clonethe repocd study-lensesinto reponpm install -g .- installing this repository as a global dependency will let you test your changes in realtime
npm run test-content
If everything looks good, and you see study-lenses running on your browser, you are good to go!
One last check: stop the tool by pressing Ctrl+C on the terminal.
Now visit any other folder through your terminal (e.g. cd to another folder)
and run either the study or lenses global command and check whether the study-lenses loads
the current directory's content in the browser.
This tool has a URL Parameter Interface, the student controls how they view and
study their code by modifying the URL parameters when requesting a resource. At
it's base, this is just a static server. requesting a path inside the folder you
have studyed will send the raw content. however ...
URL params can be used to modify the resource before it is sent. once you have a
directory open in your browser using $ study, navigate to a file and add
?hello-world to the end of the URL and refreshing. You can find the source
code for this lens in ./src/lenses/hello-world.
(This is a Lens. There is another type of URL parameter called an
Option that will be covered in more detail later.)
To see lenses in action, open the /test-content ($ npm run test-content)
directory as indicated in Getting Started and try pasting in these url
extensions and refreshing:
/README.md/README.md- no lens, the markdown source is returned as-is/README.md?hello-world- the markdown will be rendered into a textarea in an HTML file/README.md?hello-world=1234- the markdown will be rendered into a textarea in an HTML file, with the value 1234 passed as a query/README.md?render- the markdown will be rendered to HTML using marked, it will now be a web page/README.md?render&hello-world- like the previous hello-world, but with the rendered HTML code instead of the raw markdown
/messy-code/file.css/messy-code/file.css/messy-code/file.css?highlight/messy-code/file.css?format/messy-code/file.css?format&highlight/messy-code/file.css?hello-world/messy-code/file.css?format&hello-world
/languages/file.js/languages/file.js?highlight/languages/file.js?flowchart/languages/file.js?review/languages/file.js?study
There are a lot of different lenses, and they sometimes will compose in unhelpful or unexpected ways. it's also not very student-friendly to be adjusting params all the time. so ...
The server comes with a default lenses ?hyf that opens a directory as a
navigable folder structure. Each subdirectory and file is a link that opens with
a sane default lens so students won't need to understand how to use params or
read lens guides to get started. Here are a few of the defaults:
.htmlfiles will open without a lens, as a live website (studyis just an augmented static server.import/export, localfetchcalls, it all works! ).jsfiles open up in a monaco editor with configurable study options..jsonfiles open as colored and collapsible data- ...
Adding --help anywhere in your query (ie. /path/file.js?hyf&--help) will
send a guide to how you can use this tool including:
- the general idea
- a list of all lenses and links to their user guides
- a list of all options and links to their user guides
There are two types of plugins, head over to DOCS for full details. here's a quick summary:
lenses are functions that process the requested resource before the final HTTP response is generated. They exist to change the way a student sees or interacts with a given resource while in the browser. Lenses can be composed to create a variety of study experiences, some examples:
/file.jswill send the raw js code/file.js?formatwill format the code before sending it (in case the source file is messy)/file.js?format&highlightwill format the code, then render it into an HTML file using Prism (or other) for highlighted code in the browser
The most basic lens could just be a function that reverses the text stored in the file.
Options are inspired by cli conventions. Option arguments are passed the same way as lenses: as a URL parameter. They are similar to lenses but fall "outside" the normal control flow, they are filtered out of the params and evaluated before the resource is processed by lenses.
In contrast to lenses, an option can end the request/response cycle early if
indicated in their return value, ie. --help will send user documentation
regardless of where it is placed in the URL, what other lenses were requested,
or what the resource path is.
Options can also return hooks that are called at different points in the lens
pipeline process. Hooks cannot modify the content or HTTP response without
immediately ending the cycle. For example, the --debug option return hooks
that log each stage of the lens pipeline for diagnosis without modifying the
behavior of the pipeline (useful for lens developers and especially curious
students). More on this in the DOCS
besides local studying, this module should be equipped for deployment. it should probably support at least these ways:
- normal deployment on a server. (not a problem, should work as-is)
- deployment on a service like netlify functions or aws lambdas, configurable with github actions and npm scripts (i think this is possible because the server is stateless and just reads/modifies files from directory)
also, the docs
Head over to ./bin/index.js and follow the comments for a guided walk-through of the code base. Some files will contain a comment at the bottom indicating which files to read next. If nothing is mentioned, you can take abstractions at face value unless you're the curious type.