makealive brings static html documents to life through controlled use of javascript.
Background
Websites built from user-generated content strive to provide simple and secure interfaces for data entry, but also seek to present rich and diverse content. These aims call for different approaches which have their pros and cons.
Markup
Simplifying data entry suggests using a markup language such as markdown.
| Pros | Cons |
|---|---|
| simple to read and write | primarily text-based |
| can be converted into styled html | static |
| converted html can be sanitized |
Javascript
Providing rich content calls for some programming, i.e. using javacsript.
| Pros | Cons |
|---|---|
| can perform calculations based on user input | user-generated code can be a security risk |
| can generate visual elements, e.g. through charts | requires coding skills from the users |
| open-ended | mixes code (how to present) with content (what to present) |
Strategy
makealive provides a 'bridge' between markup and scripting. It provides
a means for users to invoke pre-defined javascript functions.
Thus, the framework offers the advantages of javascript without the hassle
of coding from scratch.
The server-side setup involves loading the core package and a set of compatible conversion functions.
On the client side, a user creates content using html or markdown syntax. Data
meant to be converted/processed into a richer component is placed in a
JSON object enclosed within <pre><code> tags or backticks.
When the markup is converted to html, the data is transformed into a new object.
Example
Let's suppose we have an interest in the number 1271. And let’s suppose we have
a conversion function isprime that checks if a given number is prime and
displays an output message. We can write markdown as follows
```makealive isprime
{
"number": 1271
}
```
When the markdown is converted into html, the block is turned into the following new page element
{
"number": 1271
}
The conversion function thus transforms the JSON input into another representation. In this case, the new representation is a styled written message that reports on a computation.
The library page provides other conversion functions that are of practical use, including functions for common plots and charts.
Summary
makealive can be viewed as an extension of standard markdown. It provides
additional capabilities that enable users to generate interactive content
without explicitly writing executable code.
| Pros | Cons |
|---|---|
| interactive content without coding | content is constrained by the conversion functions (determined by site admins) |
| suitable for message boards or comment boxes | site admins must vet individual conversion functions |
| site admins can implement custom, domain-specific conversion functions | |
| extremely light |
To emphasize, in contrast to traditional 'plugins' that provide web developers
interesting features to add to a website core, makealive components can be
created by end-users.
Other documentation pages describe additional points regarding setup and usage.
Acknowledgements
makealive has been inspired collectively by all technologies that make the web
experience interactive through plugins and visualizations. Special mentions:
| d3.js | The d3 library provides great tools to manipulate web documents and build visualizations. However, d3 is a tool for web developers and is not directly accessible to end-users (e.g. on comment boards). One of the aims of makealive is to provide a means for end-users to create d3 content, too. |
| plotly.js | Plotly implements a diverse array of charts with a unified and well-documented interface. Like d3, plotly is a tool for web developers, not end-users. An application of makealive might be to provide a restricted set of plotly's features through sanitized content (e.g. through a wrapper for `Plotly.plot`.) |
| jsfiddle.net | Jsfiddle is a platform for testing code snippets, live. It is not in direct relation to makealive, but it is an example of a technology that enables users opportunities to create dynamic web components that work. |
Thanks to all, and to others.