Sparational NPM

Create robust HTML pages with CSS support, using only Javascript and JSON.

SPArational (spa-Ray-shun-al) is a Javascript engine that imports JSON and writes this to the DOM. This is a browser-level package designed to be sent by an HTTP node server.

This README is a work in progress.

var sparational = require("sparational");

sparational.http.createServer(function (req, res) {
	res.writeHead(200, {'Content-Type': 'text/html'});
	//res.end($mainPage);
	res.end('<!DOCTYPE html><html lang="en"><html><head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<link rel="shortcut icon" href="' + $siteBase + '/favicon.ico" type="image/x-icon">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<script >' + sparational.sparationalCode + '</script><script>site='+JSON.stringify($siteJSON)+';
	$classes='+JSON.stringify($classes)+';$style='+JSON.stringify($style)+';$header='+JSON.stringify($header)+';
	$nav='+JSON.stringify($nav)+';$footer='+JSON.stringify($footer)+';cje("body",site);</script>
	</head><body></body></html>');
}).listen(PORT);

Installation

This is a Node.js module available through the npm registry.

Before installing, download and install Node.js. Node.js 0.10 or higher is required.

Installation is done using the npm install command:

$ npm install sparational

Install guide is on the way.

Features

Single download is possible for most applications
- No need for separate HTML, CSS, and JS files
Faster applications
Focus on high performance
Works with 3rd party CSS and JS files
HTML to JSON converter available
Compatible with Express.js and other application servers.

Docs & Community

Website and Documentation - Github page is in the works.
IRC/Slack/Discord channel is in the works.

Security Issues

If you discover a security vulnerability in SPArational, please email me.

Quick Start

The quickest way to get started with SPArational is to utilize the HTML converter in the S3 page at the main site.

Philosophy

The goal of SPArational is to produce highly flexible HTML pages with full CSS support, using only Javascript and JSON. Originally this was to facilitate faster, lightweight Single Page Applications, and has expanded to rapid prototyping of demonstration sites.

Faster - Because the entire site is represented within a single JSON file, which can be delivered by the Node application, or called from a separate site (like S3). These can be more easily delivered in a single payload without multiple calls to multiple servers. Define multiple pages within your Single Page Application, and users can move between these pages with no network nor server calls needed.

Rapid prototyping - Because sites are represented entirely as JSON, they can more easily live inline with Javascript code, allowing demonstration sites to be modified for different projects with just a few variable changes.

Feel free to call external CSS and Javascript files to extend your site beyond the basics, or define & call styles and functions within the JSON data that generates the site. Or use a mix of inline and external site styles and functions.

FAQ

What is SPArational?

SPArational is a Javascript engine to convert JSON to HTML. You can manually create a JSON file of HTML elements, use the site builder, or use the site converter to turn an HTML page into JSON.
A small website frame is sent, with just enough HTML to define the HTML document.head and document.body, favicon, and mobile viewport. Testing showed these items wouldn't operate correctly if declared by the SPArational engine.

Page sections and wrappers. And errDiv.

Head Wrapper is a DIV for elements normally found in the Head of a webpage, such as external or inline Javascript and CSS files.
Nav Wrapper is for page tabs, links, and other information you want to display in the navigation bar.
Body Wrapper is for the main content of a page or tab.
Footer Wrapper is for footer elements at the bottom of each page, like ads, copyright, etc.
errDiv is a default Div for error display. This is normally located in the Footer Wrapper.

What is the DOM and how do you work with it?

DOM is the Document Object Model. That means "document" is a variable (aka an object) in the browser that contains the entire webpage.
Usually, web browsers parse HTML and write this to the "document" variable.
SPArational bypasses this and writes JSON to the "document" variable.

HTML is nested code?

Yes! Every item on a webpage is nested under the "document" variable - more specifically, the Head items are nested under document.head and the body (visible parts) are nested under document.body.

How do you use SPArational?

With great skill! Add the imported variable sparational.sparationalCode to the website frame between the tags of a script element.
There are basically 2 modes:
- Inline prototyping - Specify elements within the Node application, stringify, and pass with the website frame.
- Robust single page application - Specify elements in a separate JSON file, and host this on S3, CDN, or another high-performance hosting solution, to greatly reduce load on your server. Instead of building pages server-side and sending to the browser, SPArational offloads this work to the browser's processor.

How to use SPArational with (instead of) Express?

Express can send the website frame instead of Node.js's native HTTP server. Specify the website frame as either an inline string in the main Node module, or as an Express page.

List of functions and the purpose of each.

getBadPW()
- Generates an 8-character random string.
- Used for random DIV names, so unnamed DIVs can still be nested.
- Oddly, identical code returns a 16-character string when used in Node.
getKeys(obj)
- Takes an array object and returns a list of the items within.
- Used to populate menu with pages from the page main variable.
xhrRequest($verb,$location,$callback,$JSON,$file,$cached)
- Convenient way to read data from other sites, or locations such as S3.
- Function dynamically figures out the correct MIME type to use - usually "text/plain" but "application/json" for GET and PUT.
- Verb can be GET, PUT, or POST. Other verbs are possible.
- Location is the URI being accesed.
- Callback takes a callback function to provide output. Recommended use is (output) => previouslyScopedVariable = output;
- JSON is a switch, enter any value to parse JSON. "JSON" is the recommended value to use here.
- File is the file or data to be sent, when using PUT or POST verbs. Has no effect with GET.
- Cached is reserved for future use, as a switch to store the retrieved data, to allow other functions to continue to work in absense of a network connection.
writeElement($elementId,$source)
- Writes the Source string to the element with the specified elementId, regardless of element type.
- Overwrites exsiting value.
- Function dynamically figures out the correct attribute to add - usually "innerText" but "src" for images and "value" for text fields, images, and select-one elements.
- innerText is the text between the opening and closing tags of the element.
- Useful to dynamically update the text in a DIV.
readElement($elementId)
- Reads a string from the specified element.
- Function dynamically figures out the correct attribute to read - usually "innerText" but "value" for text fields, textareas, numbers, and select-one elements.
appendElement($elementId,$source)
- Like writeElement but doesn't overwrite the existing value.
toggleElement($divId)
- Toggles element visibility between "hidden" and "visible".
removeElement($divID)
- Deletes div.
addElement($elementParent,$innerText,$elementClass,$elementType,$elementStyle,$href,$onChange,$onClick,$contentEditable,$attributeType,$attributeAction,$elementId)
- Primary SPArational function to write JSON to the DOM - used heavily by function "cje".
- Returns elementId of the new element, which is useful for random elementIds (see below).
- elementParent is the parent element under which this element will be nested. Required.
- Can be "head", "body", or the elementId of another element on the page. If an elementId not on the page is specified, this element won't show on the page.
- innerText is usually the text between the opening and closing tags of the element. For input fields it's the value, and for images it's the title.
- elementClass takes CSS classes to be applied to the element. Use these when using inline CSS or a separate CSS file.
- elementType is the type of element - default is DIV but literally any element type (including those not in HTML spec) can be used.
- elementStyle takes styles to be applied to the element. Useful for applying a style to a single item, or if you don't want to use CSS but still want a stylized webpage.
- href takes as string a URI and turns the element into a link. Usually "src", but is "href" for A and LINK elements. LINK also adds rel of "stylesheet" and type of "text/css", to correctly load separate CSS files.
- onChange takes a function as string and adds this as the onchange action for the element. Recommend to define the function elsewhere in a page (such as the innerText of a Script type element) and only specify the function name here.
- onClick is the same as onChange but for the onclick action.
- contentEditable sets the contenteditable attribute to True.
- attributeType & attributeAction have to both be specified for any effect. Add any arbitrary attribute type and action. Useful for...
- elementId is the name of this element, for referencing elsewhere in the page, or for nesting. Will receive a random ID from getBadPW if blank.
rebuildElement($elementId)
- Copies elementId, type, and class onto a new element, then removes the specified element. Might be depreciated.
addMenuItem($elementParent,$innerText,$onclick,$class,$href)
- Adds items to the drop down menu. Wrapper for addElement. Might be depreciated.
- Since drop downs here are A elements nested under a P or LI element, this function creates both the P or LI element along with the A element.
- elementParent is the parent element under which the P or LI element will be nested.
- innerText will be the text displayed for the A element.
- onClick is the function executed when the A element is clicked. Usually this is "rbp" (see below).
- class takes CSS classes to apply to both the P or LI element and A element.
- href takes as string a URI and turns the A element into a link.
getElementType($elementId)
- Returns the element type from the specified elementId as a string. Removes "object HTML" and "Element" from the string before returning.
onlyUnique(value, index, self)
- Takes a list of items and returns a list of only unique items.
rbp($pageName)
- ReBuild Page
- Deletes head wrapper, Nav wrapper, body wrapper, and footer wrapper, then readds body and footer. If specified page exists, function adds page as body and executes any onload functions, otherwise gives 404 error in errDiv.
cje($parentElement,$jsonVar)
- Convert JSON to Element.
- Elements have to be specified under the "element" subvariable of the jsonVar.
- Primary function for adding elements in JSON to page by calling addElement.
rwjs($jsonVar)
- ReWrite JSon.
- Replaces items starting with $GilMain (or $spaRationalMain) with items from the specified location in the page.
- Commonly used to replace CSS and Style elements, allowing a variable to be used instead of writing out the full class or stylw.
- Example: "elementClass":"$GilMain.classes.SmallHidden" is replaced with "elementClass":"hidden-sm hidden-xs "
rwjs3($jsonVar)
- ReWrite JSon 3. (ReWrite JSon 2 was depreciated.)
- Replaces "$_" (this) with $GilMain (or $spaRationalMain), for "rwjs" to operate on those items. Needs to be run before "rwjs".

SPArational onload

On page load, the SPArational engine:
- Uses xhrRequest to load a JSON file from S3 or another storage location.
- Uses both "rewrite" functions to replace variables with their values.
- Adds elements in the Header Wrapper to document.head, and elements in the Nav Wrapper to document.body.
- Add each page to the Nav menu dropdown, with "rebuild page" for that page as the onclick.
- Performs "rebuild page" on the page listed as the Starting Page.

IPYNB?

The SPArational engine has limited support for writing Jupyter Notebook (IPYNB) markdown to the DOM.

How to extend this with your own code.

There are 2 ways to easily add your code to a site:
- Inline Prototyping - Add a Script type element under either the Header Wrapper or Body Wrapper, and add raw Javascript as the innerText.
- Robust single page application - Add a Script type element under the Header Wrapper, with the Href pointing to the URI of an external Javascript file, either on the same storage location as the JSON for your site, or from another location.

How to extend this with your own Styles.

There are 3 ways to easily add your Styles to a site:
- Inline Prototyping - Add a Style type element under either the Header Wrapper or Body Wrapper, and add raw Styles as the innerText.
- Native Style Declaration - Add raw Styles to any element as the elementStyle part of the element.
- Robust single page application - Add a Link type element under the Header Wrapper, with the Href pointing to the URI of an external CSS file, either on the same storage location as the JSON for your site, or from another location.

Example site with Express and Bootstrap. (Material?)