@lobodeguerra/hrjson v1.0.18

HRJSON

HTML Representation Javascript Object Notation is a convention of representing HTML on a JSON string.

Purpose

HRJSON has the purpose of representing HTML in a JSON structure. Content marketing based websites, like newsletters or blogs, have evolved to a point in which much of their structure is saved onto the database, instead of on files, and on the other hand, content management today involves dynamic layouts that can quickly evolve over time in correspondance with the marketing efforts.

In order to better store complex HTML structures, there is a need for an identical representation of thus structures, on a JSON format, that can separate the layout representation from the way the HTML structure got built.

Simple workflow for visual editors: transform the DOM, then save it

Focus your UI on manipulating the Document HTML, then use javascript to get the HTML Object, transform it to HRJSON and save it to your DB. Retrieve the JSON, parse it and render it through javascript.

Yes. It supports inline styling.

Simplicity and design thinking

HTML is a powerful language to layout complex structures, although not the most efficient in terms of traversing it or parsing it. When saving HTML to a database, escaping such data tends to break layouts, and give developers awful regex parsing challenges. Migrations are another point of impact, in which rich content migrated from one site to another break because of problems at escaping data to save it on the database.

Even something as simple as content created with a rich text editor like tinymce, can get distorted in the way of getting stored, retrieved, parsed and displayed. Building a rich editor on top of HTML5 is a great idea, since HTML5 is so powerful to create rich content; so I came up with a solution as simple as making a JSON representation of the rich contents, that are gracefully created through DOM manipulation and HTML tags, to avoid escaping problems.

The problem has never been using HTML to create rich content, but rather using the wrong text representation to store it on the database. That being said, it is obvious that there's need for a better way to represent and store complex structures, that is identical to HTML, but designed for a different purpose: representation and storing, instead of representation and browser interpretation.

Identical representation

HTML builds layouts by nesting tags in an XML based syntax. Each tag consists of:

1. Name
2. Attributes
3. Children

An identical representation can be done with a JSON object. That is HRJSON, a standarized HTML representation on JSON.

The simplest tag with the simplest representation, for example a <span></span> , only a tag name, with no attributes and no children, can be represented with this HRJSON string:

{"tag":"span","atts":{},"children":[]}

Complex blocks can be easily represented by replicating this atomic structure, like so:

<div>
	<p>This is an example page. It’s different from a blog post because it will stay in one place and will show up in your site navigation (in most themes). Most people start with an About page that introduces them to potential site visitors. It might say something like this:</p>
	<blockquote class="wp-block-quote">
		<p>Hi there! I’m a bike messenger by day, aspiring actor by night, and this is my website. I live in Los Angeles, have a great dog named Jack, and I like piña coladas. (And gettin’ caught in the rain.)</p>
	</blockquote>
	<p>…or something like this:</p>
	<blockquote class="wp-block-quote">
		<p>The XYZ Doohickey Company was founded in 1971, and has been providing quality doohickeys to the public ever since. Located in Gotham City, XYZ employs over 2,000 people and does all kinds of awesome things for the Gotham community.</p>
	</blockquote>
	<p><a href="https://cms.lobodeguerra.test/wp-admin/">your dashboard</a></p>
</div>

Would be represent with a HRJSON string like this:

{
	"tag":"div",
	"atts":{

	},
	"children":[
		{
			"tag":"p",
			"atts":{

			},
			"children":"This is an example page. It’s different from a blog post because it will stay in one place and will show up in your site navigation (in most themes). Most people start with an About page that introduces them to potential site visitors. It might say something like this:"
		},
		{
			"tag":"blockquote",
			"atts":{
				"class":"wp-block-quote"
			},
			"children":[
				{
					"tag":"p",
					"atts":{

					},
					"children":"Hi there! I’m a bike messenger by day, aspiring actor by night, and this is my website. I live in Los Angeles, have a great dog named Jack, and I like piña coladas. (And gettin’ caught in the rain.)"
				}
			]
		},
		{
			"tag":"p",
			"atts":{

			},
			"children":"…or something like this:"
		},
		{
			"tag":"blockquote",
			"atts":{
				"class":"wp-block-quote"
			},
			"children":[
				{
					"tag":"p",
					"atts":{

					},
					"children":"The XYZ Doohickey Company was founded in 1971, and has been providing quality doohickeys to the public ever since. Located in Gotham City, XYZ employs over 2,000 people and does all kinds of awesome things for the Gotham community."
				}
			]
		},
		{
			"tag":"p",
			"atts":{

			},
			"children":[
				{
					"tag":"a",
					"atts":{
						"href":"https://cms.lobodeguerra.test/wp-admin/"
					},
					"children":"your dashboard"
				}
			]
		}
	]
}

Facades

The HRJSON constant provided in this package, provides facades for the following models:

HTMLString

toHTMLObject

Transforms a HTML String into a HTML Object.

import { HRJSON } from '@lobodeguerra/hrjson';
const htmlString = `
<div>
    <p style="margin-bottom: 20px; background-color: #FFF; background-image: url(https://placehold.it/800x600);">This is an example page. It’s different from a blog post because it will stay in one place and will show up in your site navigation (in most themes). Most people start with an About page that introduces them to potential site visitors. It might say something like this:</p>
    <blockquote class="wp-block-quote">
        <p>Hi there! I’m a bike messenger by day, aspiring actor by night, and this is my website. I live in Los Angeles, have a great dog named Jack, and I like piña coladas. (And gettin’ caught in the rain.)</p>
    </blockquote>
    <p>…or something like this:</p>
    <blockquote class="wp-block-quote">
        <p>The XYZ Doohickey Company was founded in 1971, and has been providing quality doohickeys to the public ever since. Located in Gotham City, XYZ employs over 2,000 people and does all kinds of awesome things for the Gotham community.</p>
    </blockquote>
    <p><a href="https://cms.lobodeguerra.test/wp-admin/">your dashboard</a></p>
</div>
`;
const htmlObject = HRJSON.HTMLString.toHTMLObject(htmlString);

HRJSONString

toHRJSONObject

Transforms a HRJSON String into a HRJSON Object.

const hrjsonString = `
{
   "tag":"div",
   "atts":{

   },
   "children":[
      {
         "tag":"div",
         "atts":{

         },
         "children":[
            {
               "tag":"p",
               "atts":{
                  "style":"margin-bottom: 20px; background-color: #FFF; background-image: url(https://placehold.it/800x600);"
               },
               "children":"This is an example page. It’s different from a blog post because it will stay in one place and will show up in your site navigation (in most themes). Most people start with an About page that introduces them to potential site visitors. It might say something like this:"
            },
            {
               "tag":"blockquote",
               "atts":{
                  "class":"wp-block-quote"
               },
               "children":[
                  {
                     "tag":"p",
                     "atts":{

                     },
                     "children":"Hi there! I’m a bike messenger by day, aspiring actor by night, and this is my website. I live in Los Angeles, have a great dog named Jack, and I like piña coladas. (And gettin’ caught in the rain.)"
                  }
               ]
            },
            {
               "tag":"p",
               "atts":{

               },
               "children":"…or something like this:"
            },
            {
               "tag":"blockquote",
               "atts":{
                  "class":"wp-block-quote"
               },
               "children":[
                  {
                     "tag":"p",
                     "atts":{

                     },
                     "children":"The XYZ Doohickey Company was founded in 1971, and has been providing quality doohickeys to the public ever since. Located in Gotham City, XYZ employs over 2,000 people and does all kinds of awesome things for the Gotham community."
                  }
               ]
            },
            {
               "tag":"p",
               "atts":{

               },
               "children":[
                  {
                     "tag":"a",
                     "atts":{
                        "href":"https://cms.lobodeguerra.test/wp-admin/"
                     },
                     "children":"your dashboard"
                  }
               ]
            }
         ]
      }
   ]
}
`;
const hrjsonObject = HRJSON.HRJSONString.toHRJSONObject(hrjsonString);

HTMLObject

toHTMLString

Transforms a HTML Object into a HTML String

const element = document.getElementById('element');
const htmlString = HRJSON.HTMLObject.toHTMLString(element);

toHRJSONObject

Transforms a HTML Object into a HRJSON Object

const element = document.getElementById('element');
const hrjsonObject = HRJSON.HTMLObject.toHRJSON(element);

HRJSONObject

toHRJSONString

Transforms a HRJSON Object into a HRJSON String

const hrjsonString = HRJSON.HRJSONObject.toHRJSONString(hrjsonObject);

toHTMLObject

Transforms a HRJSON Object into a HTML Object

const htmlObject = HRJSON.HRJONSObject.toHTMLObject(hrjsonObject);

Installation

Install the module as a dependency on your project by running

npm i --save-dev @lobodeguerra/hrjson

Include the HRJSON constant at the top of your JS file with:

import { HRJSON } from '@lobodeguerra/hrjson';

Example

import { HRJSON } from '@lobodeguerra/hrjson';

const htmlString = `
    <p style="margin-bottom: 20px; background-color: #FFF; background-image: url(https://placehold.it/800x600);">This is an example page. It’s different from a blog post because it will stay in one place and will show up in your site navigation (in most themes). Most people start with an About page that introduces them to potential site visitors. It might say something like this:</p>
    <blockquote class="wp-block-quote">
        <p>Hi there! I’m a bike messenger by day, aspiring actor by night, and this is my website. I live in Los Angeles, have a great dog named Jack, and I like piña coladas. (And gettin’ caught in the rain.)</p>
    </blockquote>
    <p>…or something like this:</p>
    <blockquote class="wp-block-quote">
        <p>The XYZ Doohickey Company was founded in 1971, and has been providing quality doohickeys to the public ever since. Located in Gotham City, XYZ employs over 2,000 people and does all kinds of awesome things for the Gotham community.</p>
    </blockquote>
    <p><a href="https://cms.lobodeguerra.test/wp-admin/">your dashboard</a></p>
`;

const example = document.getElementById('example');
if (example) {
    const HRJSONObjectTest = HRJSON.HTMLObject.toHRJSONObject(HRJSON.HTMLString.toHTMLObject(htmlString));
    example.innerHTML = HRJSON.HTMLObject.toHTMLString(HRJSON.HRJSONObject.toHTMLObject(HRJSONObjectTest));
}