%META:TOPICINFO{author="TWikiContributor" date="1495793747" format="1.1" version="$Rev$"}%
---+!! !EmbeddedJSPlugin Table API

This page describes the usage of EJS Table API of [[EmbeddedJSPlugin]]. See also [[EmbeddedJSPluginAPI][EJS API List]].

<!--
   * Set EJS = off
-->

%TOC%

---++ parseTable

<verbatim>
parseTable(
    "| *A* | *B* |\n" +
    "| 1 | 2 |\n" +
    "| 3 | 4 |\n"
);
/*
Returns: {
    fields: ['A', 'B'],
    rows: [
        {A: 1, B: 2},
        {A: 3, B: 4}
    ],
}
*/
</verbatim>

<verbatim>
parseTable(
    "| 1 | 2 |\n" +
    "| 3 | 4 |\n",
    {header: false}
);
/*
Returns: [
    [1, 2],
    [3, 4]
]
*/
</verbatim>

<verbatim>
parseTable(
    "| *A* | *B* |\n" +
    "| 1 | 2 |\n" +
    "| 3 | 4 |\n",
    {header: true, fields: ['Foo', 'Bar']}
);
/*
Returns: {
    fields: ['Foo', 'Bar'],
    rows: [
        {Foo: 1, Bar: 2},
        {Foo: 3, Bar: 4}
    ],
}
*/
</verbatim>

<verbatim>
parseTable(
    "| 1 | 2 |\n" +
    "| 3 | 4 |\n",
    {header: false, fields: ['Foo', 'Bar']}
);
/*
Returns: {
    fields: ['Foo', 'Bar'],
    rows: [
        {Foo: 1, Bar: 2},
        {Foo: 3, Bar: 4}
    ],
}
*/
</verbatim>

<verbatim>
parseTable(
    "| *A* | *B* |\n" +
    "| 1 | 2 |\n" +
    "| 3 | 4 |\n",
    {fields: ['Foo', 'Bar']}
    function (row) {
        println(formatText("---++ Foo: $Foo", row));
        println(formatText("Bar: $Bar", row));
    }
);
/*
Prints:
---++ Foo: 1
Bar: 2
---++ Foo: 3
Bar: 4
*/
</verbatim>

---++ formatTable

<verbatim>
formatTable({
    fields: ['A', 'B'],
    rows: [
        {A: 1, B: 2},
        {A: 3, B: 4}
    ]
});
/*
Returns:
| *A* | *B* |
| 1 | 2 |
| 3 | 4 |
*/
</verbatim>

<verbatim>
formatTable({
    fields: ['A', 'B'],
    rows: [
        {A: 1, B: 2},
        {A: 3, B: 4}
    ]
}, {header: false});
/*
Returns:
| 1 | 2 |
| 3 | 4 |
*/
</verbatim>

<verbatim>
formatTable([
    [1, 2],
    [3, 4]
]);
/*
Returns:
| 1 | 2 |
| 3 | 4 |
*/
</verbatim>

<verbatim>
formatTable({
    fields: ['Foo', 'Bar'],
    rows: [
        {Foo: 1, Bar: 2},
        {Foo: 3, Bar: 4}
    ]
}, function (row) {
    row.Bar = '%RED%' + row.Bar + '%ENDCOLOR%';
    return row;
});
/*
Returns:
| *Foo* | *Bar* |
| 1 | %RED%2%ENDCOLOR% |
| 3 | %RED%4%ENDCOLOR% |
*/
</verbatim>

---++ Special Characters

The EmbeddedJSPlugin Table API treats the following character sequences in the special ways:

| *Sequence* | *Descrpition* |
| %<nop>VBAR% | The vertical bar (<code>%VBAR%</code>) |
| \0 | Null byte |
| \n | Line feed |
| \r | Carriage return |
| \t | Tab |
| \b | Backspace |
| \f | Form feed |
| \v | Vertical tab |
| \\ | Backslash literal (<code>\</code>) |

When formatting and parsing a table, it escapes and unescapes these sequences in addition to HTML entities. (=escapeTable()= and =unescapeTable()=)

<verbatim>
// Topic name: TestTable
| &lt;%VBAR%gt;\n |
<!-- Note: \n is encoded as a backslash followed by n -->

// EJS Code
var table = parseTable(readTopic("TestTable"), {header: false});
table[0][0] == "<|>\n"; // Note: \n is the actual line break
formatTable(table); // returns the same text as TestTable
</verbatim>
