mirror of
https://github.com/warmcat/libwebsockets.git
synced 2025-03-16 00:00:07 +01:00
171 lines
12 KiB
HTML
171 lines
12 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||
|
|
<meta name="generator" content="Doxygen 1.8.12"/>
|
||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
|
|
<title>libwebsockets: Notes about generic-table</title>
|
||
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="jquery.js"></script>
|
||
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
||
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="resize.js"></script>
|
||
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
||
|
|
<script type="text/javascript" src="navtree.js"></script>
|
||
|
|
<script type="text/javascript">
|
||
|
|
$(document).ready(initResizable);
|
||
|
|
</script>
|
||
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
|
|
<div id="titlearea">
|
||
|
|
<table cellspacing="0" cellpadding="0">
|
||
|
|
<tbody>
|
||
|
|
<tr style="height: 56px;">
|
||
|
|
<td id="projectlogo"><img alt="Logo" src="libwebsockets.org-logo.png"/></td>
|
||
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
||
|
|
<div id="projectname">libwebsockets
|
||
|
|
</div>
|
||
|
|
<div id="projectbrief">Lightweight C library for HTML5 websockets</div>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<!-- end header part -->
|
||
|
|
<!-- Generated by Doxygen 1.8.12 -->
|
||
|
|
<script type="text/javascript" src="menudata.js"></script>
|
||
|
|
<script type="text/javascript" src="menu.js"></script>
|
||
|
|
<script type="text/javascript">
|
||
|
|
$(function() {
|
||
|
|
initMenu('',false,false,'search.php','Search');
|
||
|
|
});
|
||
|
|
</script>
|
||
|
|
<div id="main-nav"></div>
|
||
|
|
</div><!-- top -->
|
||
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
|
|
<div id="nav-tree">
|
||
|
|
<div id="nav-tree-contents">
|
||
|
|
<div id="nav-sync" class="sync"></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
||
|
|
class="ui-resizable-handle">
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<script type="text/javascript">
|
||
|
|
$(document).ready(function(){initNavTree('md_README_8generic-table.html','');});
|
||
|
|
</script>
|
||
|
|
<div id="doc-content">
|
||
|
|
<div class="header">
|
||
|
|
<div class="headertitle">
|
||
|
|
<div class="title">Notes about generic-table </div> </div>
|
||
|
|
</div><!--header-->
|
||
|
|
<div class="contents">
|
||
|
|
<div class="textblock"><h1><a class="anchor" id="gtint"></a>
|
||
|
|
What is generic-table?</h1>
|
||
|
|
<p>Generic-table is a JSON schema and client-side JS file that makes it easy to display live, table structured HTML over a ws link.</p>
|
||
|
|
<p>An example plugin and index.html using it are provided, but lwsgt itself doesn't have its own plugin, it's just a JSON schema and client-side JS that other plugins can use to simplify displaying live, table-based data without having to reinvent the wheel each time.</p>
|
||
|
|
<p>The ws protocol sends JSON describing the table, and then JSON updating the table contents when it chooses, the brower table is updated automatically, live.</p>
|
||
|
|
<div class="image">
|
||
|
|
<img src="lwsgt-overview.png" alt="lwsgt-overview.png"/>
|
||
|
|
</div>
|
||
|
|
<ul>
|
||
|
|
<li>Example protocol plugin (displays directory contents): <a href="https://github.com/warmcat/libwebsockets/tree/master/plugins/generic-table/protocol_table_dirlisting.c">https://github.com/warmcat/libwebsockets/tree/master/plugins/generic-table/protocol_table_dirlisting.c</a></li>
|
||
|
|
<li>Example HTML: <a href="https://github.com/warmcat/libwebsockets/tree/master/plugins/generic-table/assets/index.html">https://github.com/warmcat/libwebsockets/tree/master/plugins/generic-table/assets/index.html</a></li>
|
||
|
|
<li>lwsgt.js (client-side table rendering / ws link management): <a href="https://github.com/warmcat/libwebsockets/tree/master/plugins/generic-table/assets/lwsgt.js">https://github.com/warmcat/libwebsockets/tree/master/plugins/generic-table/assets/lwsgt.js</a></li>
|
||
|
|
</ul>
|
||
|
|
<h1><a class="anchor" id="gteb"></a>
|
||
|
|
Enabling for build</h1>
|
||
|
|
<p>Enable the demo plugin at CMake with -DLWS_WITH_PLUGINS=1</p>
|
||
|
|
<h1><a class="anchor" id="gtinth"></a>
|
||
|
|
Integrating with your html</h1>
|
||
|
|
<ul>
|
||
|
|
<li>In your HEAD section, include lwsgt.js</li>
|
||
|
|
</ul>
|
||
|
|
<div class="fragment"><div class="line"><script src="lwsgt.js"></script></div></div><!-- fragment --><ul>
|
||
|
|
<li>Also in your HEAD section, style the lwsgt CSS, eg</li>
|
||
|
|
</ul>
|
||
|
|
<div class="fragment"><div class="line"><style></div><div class="line">.lwsgt_title { font-size: 24; text-align:center }</div><div class="line">.lwsgt_breadcrumbs { font-size: 18; text-align:left }</div><div class="line">.lwsgt_table { font-size: 14; padding:12px; margin: 12px; align:center }</div><div class="line">.lwsgt_hdr { font-size: 18; text-align:center;</div><div class="line"> background-color: rgba(40, 40, 40, 0.8); color: white }</div><div class="line">.lwsgt_tr { padding: 10px }</div><div class="line">.lwsgt_td { padding: 3px }</div><div class="line"></style></div></div><!-- fragment --><p>You can skip this but the result will be less beautiful until some CSS is provided.</p>
|
||
|
|
<ul>
|
||
|
|
<li>In your body section, declare a div with an id (can be whatever you want)</li>
|
||
|
|
</ul>
|
||
|
|
<div class="fragment"><div class="line"><tr><td><div id="lwsgt1" class="group1"></div></td></tr></div></div><!-- fragment --><p>lwsgt JS will put its content there.</p>
|
||
|
|
<ul>
|
||
|
|
<li>Finally in a <script> at the end of your page, instantiate lwsgt and provide a custom callback for clickable links</li>
|
||
|
|
</ul>
|
||
|
|
<div class="fragment"><div class="line"><script></div><div class="line">var v1 = new lwsgt_initial("Dir listing demo",</div><div class="line"> "protocol-lws-table-dirlisting",</div><div class="line"> "lwsgt1", "lwsgt_dir_click", "v1");</div><div class="line"></div><div class="line">function lwsgt_dir_click(gt, u, col, row)</div><div class="line">{</div><div class="line"> if (u[0] == '=') { /* change directory */</div><div class="line"> window[gt].lwsgt_ws.send(u.substring(1, u.length));</div><div class="line"> return;</div><div class="line"> }</div><div class="line"> var win = window.open(u, '_blank');</div><div class="line"> win.focus();</div><div class="line">}</div><div class="line"></div><div class="line"></script></div></div><!-- fragment --><p>In the callback, you can recover the ws object by <code>window[gt].lwsgt_ws</code>.</p>
|
||
|
|
<h1><a class="anchor" id="gtc"></a>
|
||
|
|
Lwsgt constructor</h1>
|
||
|
|
<p>To instantiate the ws link and lwsgt instance, your HTML must call a lwsgt constructor for each region on the page managed by lwsgt.</p>
|
||
|
|
<p><code>var myvar = new lwsgt_initial(title, ws_protocol, div_id, click_cb, myvar);</code></p>
|
||
|
|
<p>All of the arguments are strings.</p>
|
||
|
|
<table class="doxtable">
|
||
|
|
<tr>
|
||
|
|
<th>Parameter </th><th>Description </th></tr>
|
||
|
|
<tr>
|
||
|
|
<td>title </td><td>Title string to go above the table </td></tr>
|
||
|
|
<tr>
|
||
|
|
<td>ws_protocol </td><td>Protocol name string to use when making ws connection </td></tr>
|
||
|
|
<tr>
|
||
|
|
<td>div_id </td><td>HTML id of div to fill with content </td></tr>
|
||
|
|
<tr>
|
||
|
|
<td>click_cb </td><td>Callback function name string to handle clickable links </td></tr>
|
||
|
|
<tr>
|
||
|
|
<td>myvar </td><td>Name of var used to hold this instantiation globally </td></tr>
|
||
|
|
</table>
|
||
|
|
<p>Note "myvar" is needed so it can be passed to the click handling callback.</p>
|
||
|
|
<h1><a class="anchor" id="gtclick"></a>
|
||
|
|
Lwsgt click handling function</h1>
|
||
|
|
<p>When a clickable link produced by lwsgt is clicked, the function named in the click_cb parameter to lwsgt_initial is called.</p>
|
||
|
|
<p>That function is expected to take four parameters, eg</p>
|
||
|
|
<p><code>function lwsgt_dir_click(gt, u, col, row)</code></p>
|
||
|
|
<table class="doxtable">
|
||
|
|
<tr>
|
||
|
|
<th>Parameter </th><th>Description </th></tr>
|
||
|
|
<tr>
|
||
|
|
<td>gt </td><td>Name of global var holding this lwsgt context (ie, myvar) </td></tr>
|
||
|
|
<tr>
|
||
|
|
<td>u </td><td>Link "url" string </td></tr>
|
||
|
|
<tr>
|
||
|
|
<td>col </td><td>Table column number link is from </td></tr>
|
||
|
|
<tr>
|
||
|
|
<td>row </td><td>Table row number link is from </td></tr>
|
||
|
|
</table>
|
||
|
|
<h1><a class="anchor" id="gtgj"></a>
|
||
|
|
Generic-table JSON</h1>
|
||
|
|
<h3>Column layout</h3>
|
||
|
|
<p>When the ws connection is established, the protocol should send a JSON message describing the table columns. For example</p>
|
||
|
|
<div class="fragment"><div class="line">"cols": [</div><div class="line"> { "name": "Date" },</div><div class="line"> { "name": "Size", "align": "right" },</div><div class="line"> { "name": "Icon" },</div><div class="line"> { "name": "Name", "href": "uri"},</div><div class="line"> { "name": "uri", "hide": "1" }</div><div class="line"> ]</div><div class="line">}</div></div><!-- fragment --><ul>
|
||
|
|
<li>This describes 5 columns</li>
|
||
|
|
<li>Only four columns (not "uri") should be visible</li>
|
||
|
|
<li>"Name" should be presented as a clickable link using "uri" as the destination, when a "uri" field is presented.</li>
|
||
|
|
<li>"Size" field should be presented aligned to the right</li>
|
||
|
|
</ul>
|
||
|
|
<h3>Breadcrumbs</h3>
|
||
|
|
<p>When a view is hierarchical, it's useful to provide a "path" with links back in the "path", known as "breadcrumbs".</p>
|
||
|
|
<p>Elements before the last one should provide a "url" member as well as the displayable name, which is used to create the link destination.</p>
|
||
|
|
<p>The last element, being the current displayed page should not have a url member and be displayed without link style.</p>
|
||
|
|
<div class="fragment"><div class="line">"breadcrumbs":[{"name":"top", "url": "/" }, {"name":"mydir"}]</div></div><!-- fragment --><h3>Table data</h3>
|
||
|
|
<p>The actual file data consists of an array of rows, containing the columns mentioned in the original "cols" section.</p>
|
||
|
|
<div class="fragment"><div class="line">"data":[</div><div class="line"> {</div><div class="line"> "Icon":" ",</div><div class="line"> "Date":"2015-Feb-06 03:08:35 +0000",</div><div class="line"> "Size":"1406",</div><div class="line"> "uri":"./serve//favicon.ico",</div><div class="line"> "Name":"favicon.ico"</div><div class="line"> }</div><div class="line">]</div></div><!-- fragment --><h1><a class="anchor" id="gtdirl"></a>
|
||
|
|
Setting up protocol-lws-table-dirlisting</h1>
|
||
|
|
<p>The example protocol needs two mounts, one to provide the index.html, js and the protocol itself</p>
|
||
|
|
<div class="fragment"><div class="line">{</div><div class="line"> "mountpoint": "/dirtest",</div><div class="line"> "origin": "file:///usr/share/libwebsockets-test-server/generic-table",</div><div class="line"> "origin": "callback://protocol-lws-table-dirlisting",</div><div class="line"> "default": "index.html",</div><div class="line"> "pmo": [{</div><div class="line"> "dir": "/usr/share/libwebsockets-test-server"</div><div class="line"> }]</div><div class="line">},</div></div><!-- fragment --><p>The protocol wants a per-mount option (PMO) to tell it the base directory it is serving from, named "dir".</p>
|
||
|
|
<p>The other mount is there to simply serve items that get clicked on from the table in a secure way</p>
|
||
|
|
<div class="fragment"><div class="line">{</div><div class="line"> "mountpoint": "/dirtest/serve",</div><div class="line"> "origin": "file:///usr/share/libwebsockets-test-server",</div><div class="line"> "default": "index.html"</div><div class="line">},</div></div><!-- fragment --><p>This last bit is not related to using lwsgt itself. </p>
|
||
|
|
</div></div><!-- contents -->
|
||
|
|
</div><!-- doc-content -->
|
||
|
|
<!-- start footer part -->
|
||
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
|
|
<ul>
|
||
|
|
<li class="footer">Generated by
|
||
|
|
<a href="http://www.doxygen.org/index.html">
|
||
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|