The htmldbjs from htmldbjs

HTMLDB.js is a simple HTML data & template engine. HTMLDB.js is written in pure JavaScript so that it can be used with different backend and frontend frameworks.

This repository contains HTMLDB.js core library source code.

Installation

Installation HTMLDB is very simple. Just add src/htmldb.js or dist/htmldb.min.js in your HTML document. You don't need to initialize it with javascript. On the page load, HTMLDB automatically initializes itself.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My HTMLDB Page</title>
    <!--
    htmldb.min.js file location can change based on your directory structure.
    -->
    <script type="text/javascript" src="htmldb.min.js"></script>
  </head>
  <body>
  </body>
</html>

Usage

Firstly, create an HTMLDB table. HTMLDB tables are like database tables, they have columns and rows. In this case we have a table to list our friends.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My HTMLDB Page</title>

    <div id="friendsHTMLDB" class="htmldb-table" data-htmldb-read-url="friends/read"></div>

    <script type="text/javascript" src="htmldb.min.js"></script>
  </head>
  <body>
  </body>
</html>

In the above example, we use a container <div> element for storing server side data (e.g. friends) in HTML format. This <div> must have a unique id attribute. By using a special class name htmldb-table, we specify this <div> as an HTMLDB table. Additionally, we use special attributes starting with data-htmldb- to define properties of HTMLDB elements. In this case we use data-htmldb-read-url for specifying the source URL of HTMLDB table that friends data will be loaded.

Let's assume friends data (URL decoded) loaded from the server are as follows:

{
    "c": [
        "id", "firstname", "lastname"
    ],
    "r": [
        ["1", "Rachel", "Green"],
        ["2", "Phoebe", "Buffay"],
        ["3", "Monica", "Geller"],
        ["4", "Chandler", "Bing"],
        ["5", "Joey", "Tribbiani"],
        ["6", "Ross", "Geller"]
    ]
}

Let's list our friends with a template.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My HTMLDB Page</title>

    <div id="friendsHTMLDB" class="htmldb-table" data-htmldb-read-url="friends/read"></div>

    <table>
        <thead>
            <tr>
                <th>ID</th>
                <th>First Name</th>
                <th>Last Name</th>
            </tr>
        </thead>
        <tbody id="friendsList"></tbody>
    </table>

    <script type="text/html" id="friendsListTemplate" class="htmldb-template"
            data-htmldb-table="friendsHTMLDB" data-htmldb-template-target="friendsList">
        <tr data-row-id="{{id}}">
            <td>{{id}}</td>
            <td>{{firstname}}</td>
            <td>{{lastname}}</td>
        </tr>
    </script>

    <script type="text/javascript" src="htmldb.min.js"></script>
  </head>
  <body>
  </body>
</html>

In the example above, there is a <table> with an empty <tbody> element. This empty <tbody> element will contain list of friends after the page load with the specified template. <tbody> element has an id attribute with the value "friendsList".

Additionally, there is a <script> element with type="text/html" attribute. This <script> element contains list template with mustache text fields.

After loading page, this HTML will look like as the following:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My HTMLDB Page</title>

    <div id="friendsHTMLDB" class="htmldb-table" data-htmldb-read-url="friends/read">
        <!-- HTMLDB table runtime content -->
    </div>

    <table>
        <thead>
            <tr>
                <th>ID</th>
                <th>First Name</th>
                <th>Last Name</th>
            </tr>
        </thead>
        <tbody id="friendsList">
            <tr data-row-id="1">
                <td>1</td>
                <td>Rachel</td>
                <td>Green</td>
            </tr>
            <tr data-row-id="2">
                <td>2</td>
                <td>Phoebe</td>
                <td>Buffay</td>
            </tr>
            <tr data-row-id="3">
                <td>3</td>
                <td>Monica</td>
                <td>Geller</td>
            </tr>
            <tr data-row-id="4">
                <td>4</td>
                <td>Chandler</td>
                <td>Bing</td>
            </tr>
            <tr data-row-id="5">
                <td>5</td>
                <td>Joey</td>
                <td>Tribbiani</td>
            </tr>
            <tr data-row-id="6">
                <td>6</td>
                <td>Ross</td>
                <td>Geller</td>
            </tr>
        </tbody>
    </table>

    <script type="text/html" id="friendsListTemplate" class="htmldb-template"
            data-htmldb-table="friendsHTMLDB" data-htmldb-template-target="friendsList">
        <tr data-row-id="{{id}}">
            <td>{{id}}</td>
            <td>{{firstname}}</td>
            <td>{{lastname}}</td>
        </tr>
    </script>

    <script type="text/javascript" src="htmldb.min.js"></script>
  </head>
  <body>
  </body>
</html>

Backend Integration

It is easy to integrate HTMLDB with your favorite backend framework. HTMLDB requests data in JSON format and uses an inner form to post data to the server.

Request Format

A typical HTMLDB request is a JSON string with the following format:

{
    "c": [
        "id", "column0", "column1", "column2", "columnName"
    ],
    "r": [
        ["1", "This is column0 value", "Column 1 Value", "Column 2 Value", "Last column value"],
        ["2", "This is column0 value", "Column 1 Value", "Column 2 Value", "Last column value"],
        ["3", "This is column0 value", "Column 1 Value", "Column 2 Value", "Last column value"]
    ]
}

Please note that data loaded from the server must be URL encoded. Raw data from the server will be as follows:


%7B%22c%22%3A%5B%22id%22%2C%22column0%22%2C%22column1%22%2C%22column2%22%2C%22columnName%22%5D%2C%22r%22%3A%5B%5B%221%22%2C%22This%20is%20column0%20value%22%2C%22Column%201%20Value%22%2C%22Column%202%20Value%22%2C%22Last%20column%20value%22%5D%2C%5B%222%22%2C%22This%20is%20column0%20value%22%2C%22Column%201%20Value%22%2C%22Column%202%20Value%22%2C%22Last%20column%20value%22%5D%2C%5B%223%22%2C%22This%20is%20column0%20value%22%2C%22Column%201%20Value%22%2C%22Column%202%20Value%22%2C%22Last%20column%20value%22%5D%5D%7D

HTMLDB uses decodeURIComponent function to decode URL encoded data.

Response Format

HTMLDB uses an inner HTML form element to post data to the server with the following format:

htmldb_action0: inserted
htmldb_row0_id: 1
htmldb_row0_column0: column0 new value  
htmldb_row0_column1: column1 new value
htmldb_row0_column2: column2 new value
htmldb_row0_columnName: columnName new value

The above example shows single-row post parameters. For posting multiple rows the following format is used:

htmldb_action0: inserted
htmldb_row0_id: 1
htmldb_row0_column0: column0 new value  
htmldb_row0_column1: column1 new value
htmldb_row0_column2: column2 new value
htmldb_row0_columnName: columnName new value
htmldb_action1: inserted
htmldb_row1_id: 2
htmldb_row1_column0: column0 new value  
htmldb_row1_column1: column1 new value
htmldb_row1_column2: column2 new value
htmldb_row1_columnName: columnName new value
htmldb_action2: inserted
htmldb_row2_id: 3
htmldb_row2_column0: column0 new value  
htmldb_row2_column1: column1 new value
htmldb_row2_column2: column2 new value
htmldb_row2_columnName: columnName new value

Elements

Element Name	Description
`htmldb-button-add`	An action button is used for adding a new record to the specified table. When `htmldb-button-add` button is clicked related forms are reset.
`htmldb-button-edit`	An action button is used for editing a specific record. When `htmldb-button-edit` button is clicked `htmldb-table` element's active id is set to the specified record. Additionally, all related form fields are populated with the values of the record.
`htmldb-button-refresh`	An action button is used for refreshing all `htmldb-table` elements.
`htmldb-button-save`	An action button is used for saving current values of the specified form.
`htmldb-button-sort`	An action button is used for updating the sorting preferences.
`htmldb-checkbox-group`	A container element for checkbox inputs. `htmldb-checkbox-group` makes it possible to select/update/delete multiple records.
`htmldb-checkbox`	A checkbox input item in `htmldb-checkbox-group`, that enables to select/update/delete multiple records.
`htmldb-error`	A container element for the errors.
`htmldb-field`	An input element, that holds the current values of the `htmldb-form` fields.
`htmldb-form`	A container for the `htmldb-field` elements, that automatically updated by `htmldb-table`.
`htmldb-input-save`	A standalone input that automatically update the specific `htmldb-table` record.
`htmldb-message`	A container element for the messages.
`htmldb-pagination`	A container element for easily navigating among the pages of `htmldb-table` element.
`htmldb-section`	A container for the elements, that automatically rendered by the related `htmldb-table`.
`htmldb-select`	A select element that automatically populated with the related `htmldb-table`.
`htmldb-table`	Data source element that retrieves and stores data from the server. Also, it validates and posts data to the server.
`htmldb-table-validation`	A container element for conditions validated locally before writing a record to `htmldb-table` element.
`htmldb-template`	A container element for the templates, that are automatically rendered by related `htmldb-table`.
`htmldb-toggle`	A special container for the form fields that automatically displayed or hided for a certain condition.

Global Variables

HTMLDB provides some critical information in global variables. This global variables can be used in mustache templates.

`$URL`

$URL global variable holds the URL address of the current page. You can access URL parameters with $URL.parameter notation. Additionally $URL accepts integer parameter indices e.g. $URL.1 or $URL.-1. $URL.1 gives the first URL parameter value. $URL.-1 gives the last URL parameter value.

Using Other Table Fields and Element Variables in Mustache Templates

In some cases, it is required to use other table fields and/or element variables (e.g. current page index, page count, checked record count, etc.) in mustache templates. htmldb-table fields are accessible using {{TableName.FieldName}} notation, and also htmldb-pagination, htmldb-checkbox-group variables using {{ElementID.VariableName}} in mustache templates. HTMLDB uses active records of the htmldb-table instances while parsing mustache templates.

<form id="myForm"
        name="myForm"
        method="post"
        class="htmldb-form"
        data-htmldb-table="myTable">

    <input id="company_id"
            name="company_id"
            type="hidden"
            value=""
            class="htmldb-field"
            data-htmldb-field="company_id"
            data-htmldb-reset-value="{{companyTable.id}}">

    <input id="name"
            name="name"
            type="text"
            value=""
            class="htmldb-field"
            data-htmldb-field="company_name">

</form>

<div id="companyTable"
        class="htmldb-table"
        data-htmldb-read-url="company/read"
        data-htmldb-validate-url="company/validate"
        data-htmldb-write-url="company/write"></div>

<div id="myFirstTable"
        class="htmldb-table"
        data-htmldb-read-url="myfirsttable/read"
        data-htmldb-validate-url="myfirsttable/validate"
        data-htmldb-write-url="myfirsttable/write"></div>

In the example above, there is a form and two htmldb-table instances called companyTable and myFirstTable respectively. Also, the form has two inputs. The first input is a hidden input that holds predefined company_id value from companyTable. In this case, data-htmldb-reset-value attribute must be specified with the value {{companyTable.id}}. So, company_id input value will be automatically reset to the id value of the active record in companyTable instance.

Using Javascript Functions and Variables in Mustache Templates

Using Javascript variables and functions in mustache templates can be a time-saver. It is very easy to use global Javascript functions and variables in HTMLDB mustache templates.

<form id="myForm"
        name="myForm"
        method="post"
        class="htmldb-form"
        data-htmldb-table="myTable">

    <input id="company_guid"
            name="company_guid"
            type="hidden"
            value=""
            class="htmldb-field"
            data-htmldb-field="company_guid"
            data-htmldb-reset-value="{{:generateCompanyGUID();}}">

    <input id="company_calculated_field"
            name="company_calculated_field"
            type="hidden"
            value=""
            class="htmldb-field"
            data-htmldb-field="company_calculated_field"
            data-htmldb-reset-value="{{:2+3;}}">

    <input id="company_special_field"
            name="company_calculated_field"
            type="hidden"
            value=""
            class="htmldb-field"
            data-htmldb-field="company_calculated_field"
            data-htmldb-reset-value="{{:Math.sin(Math.PI / 2);}}">

Methods

HTMLDB provides methods for accessing HTMLDB elements using JavaScript. You can click the following link to view HTMLDB methods.

List of HTMLDB Methods

Contributing

Please use the issue tracker to report any bugs/typos or requests.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

Aykut Aydınlı - @aykutaydinli

License

This project is licensed under the MIT License - see the LICENSE file for details

htmldbjs / htmldbjs Goto Github PK

htmldbjs's Introduction

Installation

Usage

Backend Integration

Request Format

Response Format

Elements

Global Variables

$URL

Using Other Table Fields and Element Variables in Mustache Templates

Using Javascript Functions and Variables in Mustache Templates

Methods

Contributing

Versioning

Authors

License

htmldbjs's People

Contributors

Stargazers

Watchers

Recommend Projects

Recommend Topics

Recommend Org

`$URL`