extra/webapps/fjsc/www/termlib/faq.html

   1 <HTML>
   2 <HEAD>
   3         <TITLE>mass:werk termlib faq</TITLE>
   4
   5 <STYLE TYPE="text/css">
   6 body,p,a,td {
   7         font-family: courier,fixed,swiss,sans-serif;
   8         font-size: 12px;
   9         color: #cccccc;
  10 }
  11 .lh13 {
  12         line-height: 13px;
  13 }
  14 .lh15 {
  15         line-height: 15px;
  16 }
  17 pre {
  18         font-family: courier,fixed,swiss,sans-serif;
  19         color: #ccffaa;
  20         font-size: 12px;
  21         line-height: 15px;
  22 }
  23 .prop {
  24         font-family: courier,fixed,swiss,sans-serif;
  25         color: #bbee99;
  26         font-size: 12px;
  27         line-height: 15px;
  28 }
  29 h1 {
  30         font-family: courier,fixed,swiss,sans-serif;
  31         font-size: 16px;
  32         color: #cccccc;
  33 }
  34 b.quest {
  35         font-family: courier,fixed,swiss,sans-serif;
  36         font-size: 14px;
  37         font-weight: bold;
  38         color: #bbee99;
  39 }
  40 a,a:link,a:visited {
  41         text-decoration: none;
  42         color: #77dd11;
  43 }
  44 a:hover {
  45         text-decoration: underline;
  46         color: #77dd11;
  47 }
  48 a:active {
  49         text-decoration: underline;
  50         color: #dddddd;
  51 }
  52
  53 @media print {
  54         body { background-color: #ffffff; }
  55         body,p,a,td {
  56                 font-family: courier,fixed,swiss,sans-serif;
  57                 font-size: 12px;
  58                 color: #000000;
  59         }
  60         .lh13 {
  61                 line-height: 13px;
  62         }
  63         .lh15 {
  64                 line-height: 15px;
  65         }
  66         pre,.prop {
  67                 font-family: courier,fixed,swiss,sans-serif;
  68                 font-size: 12px;
  69                 color: #000000;
  70                 line-height: 15px;
  71         }
  72         h1 {
  73                 font-family: courier,fixed,swiss,sans-serif;
  74                 font-size: 16px;
  75                 color: #000000;
  76         }
  77         b.quest {
  78                 font-family: courier,fixed,swiss,sans-serif;
  79                 font-size: 14px;
  80                 font-weight: bold;
  81                 color: #000000;
  82         }
  83         a,a:link,a:visited {
  84                 text-decoration: none;
  85                 color: #000000;
  86         }
  87         a:hover {
  88                 text-decoration: underline;
  89                 color: #000000;
  90         }
  91         a:active {
  92                 text-decoration: underline;
  93                 color: #000000;
  94         }
  95 }
  96 </STYLE>
  97 </HEAD>
  98
  99
 100 <BODY BGCOLOR="#222222" LINK="#77dd11" TEXT="#cccccc" ALINK="#dddddd" VLINK="#77dd11"
 101 TOPMARGIN="0" BOTTOMMARGIN="0" LEFTMARGIN="0" RIGHTMARGIN="0" MARGINHEIGHT="0" MARGINWIDTH="0"><A NAME="top"></A>
 102
 103 <TABLE BORDER="0" CELLSPACING="20" CELLPADDING="0" ALIGN="center">
 104 <TR>
 105         <TD NOWRAP><A HREF="index.html">termlib.js home</A></TD>
 106         <TD>|</TD>
 107         <TD NOWRAP><A HREF="multiterm_test.html">multiple terminal test</A></TD>
 108         <TD>|</TD>
 109         <TD NOWRAP><A HREF="parser_sample.html">sample parser</A></TD>
 110         <TD>|</TD>
 111         <TD NOWRAP>faq</TD>
 112         <TD>|</TD>
 113         <TD NOWRAP><A HREF="readme.txt" TITLE="readme.txt (text/plain)">documentation</A></TD>
 114 </TR>
 115 </TABLE>
 116
 117 <TABLE BORDER="0" CELLSPACING="20" CELLPADDING="0" WIDTH="700" ALIGN="center">
 118         <TR><TD>
 119                 <H1>frequently asked questions</H1>
 120         </TD></TR>
 121         <TR><TD CLASS="lh13">
 122 &nbsp;<BR>
 123         <UL>
 124         <LI CLASS="lh15"><A HREF="#chrome">Can I add chrome to the terminal? (e.g. a window header, a close box)</A></LI>
 125         <LI CLASS="lh15"><A HREF="#embed">How can I embed a terminal relative to my HTML layout?</A></LI>
 126         <LI CLASS="lh15"><A HREF="#syntax">I pasted your sample code and just got an error. - ???</A></LI>
 127         <LI CLASS="lh15"><A HREF="#keyboard">I can't get any input, but I don't get any erros too.</A></LI>
 128         <LI CLASS="lh15"><A HREF="#keylock">How can I temporary disable the keyboard handlers?</A></LI>
 129         <LI CLASS="lh15"><A HREF="#linesranges">How can I set the cusor to the start / the end of the command line?</A></LI>
 130         <LI CLASS="lh15"><A HREF="#historyunique">How can I limit the command history to unique entries only?</A></LI>
 131         <LI CLASS="lh15"><A HREF="#rebuild">How can I change my color theme on the fly?</A></LI>
 132         <LI CLASS="lh15"><A HREF="#connect">How can I connect to a server?</A></LI>
 133         </UL>
 134         </TD></TR>
 135         <TR><TD CLASS="lh13"><A NAME="chrome"></A>
 136 &nbsp;<BR>
 137 <B CLASS="quest">Can I add chrome to the terminal? (e.g. a window header, a close box)</B><BR><BR>
 138
 139 Not by the means of the Terminal object's interface (since there are way too many things that you may possibly want to add).<BR>
 140 The Terminal object allows you to specify the background color, the frame color, the frame's width and the font class used. If you want to add more chrome, you must align this in a separate division element.<BR><BR>
 141
 142 To calculate the dimensions of the terminal use this formula:<BR><BR>
 143
 144 width:&nbsp; 2 * frameWidth + conf.cols * &lt;width of &nbsp;&gt; + 2 * 2px padding (left and right)<BR>
 145 height: 2 * frameWidth + conf.rows * conf.rowHeight + 2 * 2px padding (top and bottom).<BR><BR>
 146
 147 Or you could get the empirical values for width and height by calling a terminal's `<SPAN CLASS="prop">getDimensions()</SPAN>' method, once the terminal is open. (see documentation in &quot;readme.txt&quot;).<BR><BR>
 148
 149 Finnally, you could obviously embed the terminal's division element in your custom chrome layout (see below). [This will not be compatible to Netscape 4.]<BR><BR>
 150
 151 p.e.:<PRE>
 152   &lt;div id=&quot;myTerminal1&quot; style=&quot;position:absolute; top:100px; left:100px;&quot;&gt;
 153      &lt;table class=&quot;termChrome&quot;&gt;
 154         &lt;tbody&gt;
 155         &lt;tr&gt;
 156            &lt;td class=&quot;termTitle&quot;&gt;terminal 1&lt;/td&gt;
 157         &lt;/tr&gt;
 158         &lt;tr&gt;
 159            &lt;td class=&quot;termBody&quot;&gt;&lt;div id=&quot;termDiv1&quot; style=&quot;position:relative&quot;&gt;&lt;/div&gt;&lt;/td&gt;
 160         &lt;/tr&gt;
 161         &lt;/tbody&gt;
 162      &lt;/table&gt;
 163    &lt;/div&gt;
 164
 165    // get a terminal for this
 166
 167    var term1 = new Terminal(
 168                  {
 169                    x: 0,
 170                    y: 0,
 171                    id: 1,
 172                    termDiv: &quot;termDiv1&quot;,
 173                    handler: myTermHandler
 174                  }
 175               );
 176    term1.open();
 177
 178    // and this is how to move the chrome and the embedded terminal
 179
 180    TermGlobals.setElementXY( &quot;myTerminal1&quot;, 200, 80 );
 181 </PRE>
 182 To keep track of the instance for any widgets use the terminal's `id' property. (You must set this in the configuration object to a unique value for this purpose.)<BR><BR>
 183
 184 For a demonstration see the <A HREF="chrome_sample.html">Chrome Sample Page</A>.
 185         </TD></TR>
 186         <TR><TD CLASS="lh13"><A NAME="embed"></A>
 187 &nbsp;<BR>
 188 <B CLASS="quest">How can I embed a terminal relative to my HTML layout?</B><BR><BR>
 189
 190 Define your devision element with attribute &quot;position&quot; set to &quot;relative&quot; and place this inside your layout. Call &quot;new Terminal()&quot; with config-values { x: 0, y: 0 } to leave it at its relative origin.
 191         </TD></TR>
 192         <TR><TD CLASS="lh13"><A NAME="syntax"></A>
 193 &nbsp;<BR>
 194 <B CLASS="quest">I pasted your sample code and just got an error. - ???</B><BR><BR>
 195
 196 The short examples are kept arbitrarily simple to show the syntax.<BR>
 197 Make sure that your divison element(s) is/are rendered by the browser before `Terminal.open()' is called.<BR><BR>
 198
 199 Does not work:
 200 <PRE>  &lt;head&gt;
 201   &lt;script&gt;
 202     var term = new Terminal();
 203     term.open();
 204   &lt;/script&gt;
 205   &lt;/head&gt;
 206 </PRE>
 207 Does work:
 208 <PRE>  &lt;head&gt;
 209   &lt;script&gt;
 210     var term;
 211
 212     function termOpen() {
 213        // to be called from outside after compile time
 214        term = new Terminal();
 215        term.open();
 216     }
 217   &lt;/script&gt;
 218   &lt;/head&gt;
 219 </PRE>
 220 c.f. &quot;readme.txt&quot;<BR>
 221 (Opening a terminal by clicking a link implies also that the page has currently focus.)<BR><BR>
 222 With v.1.01 and higher this doesn't cause an error any more.<BR>`Terminal.prototype.open()' now returns a value for success.
 223         </TD></TR>
 224         <TR><TD CLASS="lh13"><A NAME="keyboard"></A>
 225 &nbsp;<BR>
 226 <B CLASS="quest">I can't get any input, but I don't get any erros too.</B><BR><BR>
 227
 228 The Terminal object's functionality relies on the browsers ability to generate and handle keyboard events.<BR>
 229 Sadly some browsers lack a full implementation of the event model. (e.g. Konquerer [khtml] and early versions of Apple Safari, which is a descendant of khtml.)
 230         </TD></TR>
 231         <TR><TD CLASS="lh13"><A NAME="keylock"></A>
 232 &nbsp;<BR>
 233 <B CLASS="quest">How can I temporary disable the keyboard handlers?</B><BR>
 234 <SPAN CLASS="prop">(The terminal is blocking my HTML form fields, etc.)</SPAN><BR><BR>
 235
 236 With version 1.03 there's a global property `<SPAN CLASS="prop">TermGlobals.keylock</SPAN>'. Set this to `true' to disable the keyboard handlers without altering any other state. Reset it to `false' to continue with your terminal session(s).
 237         </TD></TR>
 238         <TR><TD CLASS="lh13"><A NAME="linesranges"></A>
 239 &nbsp;<BR>
 240 <B CLASS="quest">How can I set the cusor to the start / the end of the command line?</B><BR><BR>
 241
 242 In case you need to implement a shortcut (like ^A of some UN*X-shells) to jump to the beginning or the end of the current input line, there are two private instance methods you could utilize:<BR><BR>
 243 `<SPAN CLASS="prop">_getLineEnd(&lt;row&gt;, &lt;col&gt;)</SPAN>' returns an array [&lt;row&gt;, &lt;col&gt;] with the position of the last character in the logical input line with ASCII value &gt;= 32 (0x20).<BR><BR>
 244 `<SPAN CLASS="prop">_getLineStart(&lt;row&gt;, &lt;col&gt;)</SPAN>' returns an array [&lt;row&gt;, &lt;col&gt;] with the position of the first character in the logical input line with ASCII value &gt;= 32 (0x20).<BR><BR>
 245 Both take a row and a column of a cursor position as arguments.<BR><BR>
 246
 247 p.e.:
 248 <PRE>
 249   // jump to the start of the input line
 250
 251   myCtrlHandler() {
 252      // catch ^A and jump to start of the line
 253      if (this.inputChar == 1) {
 254         var firstChar = this._getLineStart(this.r, this.c);
 255         this.cursorSet(firstChar[0], firstChar[1]);
 256      }
 257   }</PRE>
 258 (Keep in mind that this is not exactly a good example, since some browser actually don't issue a keyboard event for
 259 &quot;^A&quot;. And other browsers, which do catch such codes, are not very reliable in that.)
 260         </TD></TR>
 261         <TR><TD CLASS="lh13"><A NAME="historyunique"></A>
 262 &nbsp;<BR>
 263 <B CLASS="quest">How can I limit the command history to unique entries only?</B><BR>
 264         <SPAN CLASS="prop">(My application effords commands to be commonly repeated.)</SPAN><BR><BR>
 265
 266 With version 1.05 there is a new configuration and control flag `<SPAN CLASS="prop">historyUnique</SPAN>'. All you need is setting this to `true' in your terminal's configuration object.
 267         </TD></TR>
 268         <TR><TD CLASS="lh13"><A NAME="rebuild"></A>
 269 &nbsp;<BR>
 270 <B CLASS="quest">How can I change my color theme on the fly?</B><BR><BR>
 271
 272 With version 1.07 there is a new method `<SPAN CLASS="prop">Terminal.rebuild()</SPAN>'.<BR>
 273 This method updates the GUI to current config settings while preserving all other state.<BR><BR>
 274 p.e.:
 275 <PRE>
 276    // change color settings on the fly
 277    // here: set bgColor to white and font style to class &quot;termWhite&quot;
 278    // method rebuild() updates the GUI without side effects
 279    // assume var term holds a referene to a Terminal object already active
 280
 281    term.conf.bgColor = '#ffffff';
 282    term.conf.fontClass = 'termWhite';
 283    term.rebuild();</PRE>
 284         </TD></TR>
 285         <TR><TD CLASS="lh13"><A NAME="connect"></A>
 286 &nbsp;<BR>
 287 <B CLASS="quest">How can I connect to a server?</B><BR><BR>
 288
 289 The Terminal object only provides an interface to handle console input and output.<BR>
 290 External connections have to be handled outside the Terminal object. You could use the XMLHttpRequest-Object (and use a communication model like AJAX or JSON) or connect via a frame or iframe element to a foreign host.<BR><BR>
 291 Handling connections is considered to be out of the realm of the &quot;termlib.js&quot; library.<BR>
 292 The code you need is in fact quite simple:
 293 <PRE>
 294   function connectToHost(url) {
 295      if (window.XMLHttpRequest) {
 296         request = new XMLHttpRequest();
 297      }
 298      else if (window.ActiveXObject) {
 299          request = new ActiveXObject('Microsoft.XMLHTTP');
 300      }
 301      if (request) {
 302          request.onreadystatechange = requestChangeHandler;
 303          request.open('GET', url);
 304          request.send('');
 305      }
 306      else {
 307         // XMLHttpRequest not implemented
 308      }
 309   }
 310
 311   function requestChangeHandler() {
 312      if (request.readyState == 4) {
 313         // readyState 4: complete; now test for server's response status
 314         if (request.status == 200) {
 315            // response in request.responseText or request.responseXML if XML-code
 316            // if it's JS-code we could get this by eval(request.responseText)
 317            // by this we could import whole functions to be used via the terminal
 318         }
 319         else {
 320            // connection error
 321            // status code and message in request.status and request.statusText
 322         }
 323      }
 324   }
 325 </PRE>
 326 You should use this only together with a timer (window.setTimeout()) to handle connection timeouts.<BR>
 327 Additionally you would need some syntax to authenticate and tell the server what you want.<BR>
 328 For this purpose you could use the following methods of the XMLHttpRequest object:<BR><BR>
 329
 330         <TABLE BORDER="0" CELLSPACING="0" CELLPADDING="3">
 331         <TR VALIGN="top"><TD NOWRAP CLASS="prop">setRequestHeader(&quot;<I>headerLabel</I>&quot;, &quot;<I>value</I>&quot;)</TD><TD>set a HTTP header to be sent to the server</TD></TR>
 332         <TR VALIGN="top"><TD NOWRAP CLASS="prop">getResponseHeader(&quot;<I>headerLabel</I>&quot;)</TD><TD>get a HTTP header sent from the server</TD></TR>
 333         <TR VALIGN="top"><TD NOWRAP CLASS="prop">open(<I>method</I>, &quot;<I>url</I>&quot; [, <I>asyncFlag</I> [,<BR>&nbsp; &quot;<I>userid</I>&quot; [, &quot;<I>password</I>&quot;]]])</TD><TD>assign the destination properties to the request.<BR>be aware that userid and password are not encrypted!</TD></TR>
 334         <TR VALIGN="top"><TD NOWRAP CLASS="prop">send(<I>content</I>)</TD><TD>transmit a message body (post-string or DOM object)</TD></TR>
 335         <TR VALIGN="top"><TD NOWRAP CLASS="prop">abort()</TD><TD>use this to stop a pending connection</TD></TR>
 336         </TABLE>
 337
 338         </TD></TR>
 339         <TR><TD CLASS="lh13">
 340         &nbsp;<BR>
 341         Norbert Landsteiner - August 2005<BR>
 342         <A HREF="http://www.masswerk.at/" TARGET="_blank">http://www.masswerk.at</A>
 343         </TD></TR>
 344         <TR><TD CLASS="lh13">
 345         &nbsp;<BR>
 346                 <A HREF="#top">&gt; top of page</A>
 347         </TD></TR>
 348         <TR><TD CLASS="lh13">
 349         &nbsp;
 350         </TD></TR>
 351 </TABLE>
 352
 353 <DIV ID="termDiv" STYLE="position:absolute; top:20px; left:100px;"></DIV>
 354
 355 </BODY>
 356 </HTML>