| <!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> |
