1.1 --- a/app/controllers/_woof/docs/ug_controller.tcl Tue Nov 10 22:35:28 2009 +0530
1.2 +++ b/app/controllers/_woof/docs/ug_controller.tcl Tue Nov 10 23:38:54 2009 +0530
1.3 @@ -81,10 +81,15 @@
1.4 {wtf "Woof! Template Files" 2}
1.5 {tools "Tools and Utilities"}
1.6 {installer "installer - Installation Utility" 2}
1.7 + {woofus "woofus - Woof! Utility Script" 2}
1.8 + {generating_stubs "Generating controller stubs" 3}
1.9 + {verifying_stubs "Verifying controller stubs" 3}
1.10 {bowwow "bowwow - a Lightweight Web Server" 2}
1.11 + {console "console - Interactive Console" 2}
1.12 + {ruffian "ruffian - Documentation Generator" 2}
1.13 {scgi_winservice "scgi_winservice - Woof! Windows Service" 2}
1.14 - {wtf "Woof! Template Files"}
1.15 {recommended_reading "Recommended Reading"}
1.16 + {acknowledgements "Acknowledgements"}
1.17 }
1.18
1.19 # Only use Woof default section layout, not something user might
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/app/controllers/_woof/docs/views/ug-acknowledgements-content.wtf Tue Nov 10 23:38:54 2009 +0530
2.3 @@ -0,0 +1,11 @@
2.4 +<p>Woof! reuses code, design and ideas from all over. Below is
2.5 + a list, <strong>still incomplete</strong>. Woof! to all of them.</p>
2.6 +<ul>
2.7 + <li>John Ousterhout for Tcl, of course, and the
2.8 + current <a href="http://wiki.tcl.tk/977">Tcl Core Team</a> for 8.6
2.9 + in particular</li>
2.10 + <li><a href="http://tcl.activestate.com">ActiveState</a> which provides the most widely used Tcl binary distributions</li>
2.11 + <li>The Rails/Pylons/Symfony folks for concepts and ideas</li>
2.12 + <li>Ronnie Brunner for the <a href="http://tcl.apache.org/websh/">mod_websh</a> Apache interface</li>
2.13 + <li>Various Tcllib and Tcl Wiki authors, too many to enumerate</li>
2.14 +</ul>
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/app/controllers/_woof/docs/views/ug-bowwow-content.wtf Tue Nov 10 23:38:54 2009 +0530
3.3 @@ -0,0 +1,57 @@
3.4 +<p>BowWow is a single file executable for Windows that contains everything
3.5 +you need to try Woof! or to use as a development web server. It includes
3.6 +a very basic web server as well as the Tcl interpreter and all required
3.7 +libraries.
3.8 +</p>
3.9 +
3.10 +<h3>Running BowWow</h3>
3.11 +
3.12 +<p>To run BowWow, simply type its name on the command line. Or as seen
3.13 +in the screenshot below, type <code>start bowwow</code> to start it in
3.14 +a separate console window.</p>
3.15 +[my _code_sample {
3.16 +C:\bowwow>ls
3.17 +bowwow.exe
3.18 +
3.19 +C:\bowwow>start bowwow.exe
3.20 +
3.21 +C:\bowwow>ls
3.22 +app bowwow.exe bowwow.pid config public temp
3.23 +
3.24 +C:\bowwow>
3.25 +}]
3.26 +
3.27 +<p>As seen in the directory listing above, several new directories
3.28 +appear after BowWow is
3.29 +started. The <span class="wf_filename">app</span> directory will
3.30 +contain your application code and
3.31 +templates. The <span class="wf_filename">config</span> directory
3.32 +will contain configuration settings for the installation. The public
3.33 +directory contains files such as stylesheets and
3.34 +images.The <span class="wf_filename">temp </span>directory is the
3.35 +default location for log files, session state, and other miscelleneous
3.36 +files.</p>
3.37 +
3.38 +<p>The above commands will start up BowWow in a separate console
3.39 +window as shown below.</p>
3.40 +
3.41 +[my _code_sample {
3.42 +BowWow 0.1
3.43 +Server started on port 8015
3.44 +Enter Ctrl-C to exit...
3.45 +}]
3.46 +
3.47 +<p>The window shows the BowWow V0.1 server running on port 8015, which
3.48 +is the BowWow default. You can run the server on a different port by
3.49 +specifying the <code>-port <em>PORTNUMBER</em></code> command line
3.50 +option when starting the server. After starting BowWow, browsing to
3.51 +URL <span class='wf_filename'>http://localhost:8015</span>
3.52 +should bring up the web page below.</p>
3.53 +
3.54 +<p class="wf_center">
3.55 +[my include_image bowwow_welcome.png alt "BowWow Welcome Page"]
3.56 +</p>
3.57 +<p>The BowWow installation is now ready and we can start building the
3.58 +application.</p>
3.59 +
3.60 +% # TBD - option details, ptr to quick start. Running built-in scripts.
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/app/controllers/_woof/docs/views/ug-console-content.wtf Tue Nov 10 23:38:54 2009 +0530
4.3 @@ -0,0 +1,44 @@
4.4 +<p>The <span class="wf_filename">console.tcl</span> script in
4.5 +the <span class="wf_filename">scripts</span> subdirectory provides an
4.6 +interactive command line Tcl environment for developing and debugging
4.7 +Woof! applications.</p>
4.8 +
4.9 +<p>In addition to the standard Tcl commands, the console provides
4.10 +a <span class='wf_code'>get</span> command that emulates an HTTP GET request as
4.11 +shown in the sample output below.</p>
4.12 +
4.13 +[my _code_sample {
4.14 +
4.15 +(woof) 1 % get http://localhost/math/index
4.16 +HTTP/?? 200 OK
4.17 +Content-Type: text/html
4.18 +Cache-Control: no-cache
4.19 +Set-Cookie: woofsid=D2CEFE233AF96BA4D01C16E4C03DB99E; expires=Friday, 05-Jun-2009 03:47:54 GMT;
4.20 +
4.21 +
4.22 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
4.23 +<html>
4.24 + <head>
4.25 + <title>woof</title>
4.26 + <link rel='stylesheet' type='text/css' href='http://localhost/stylesheets/_yui-2-7-0b-reset-fonts-grids.css' /> </head>
4.27 + <body> <div id="doc3"> <div id="bd"> <div class="yui-g"> <form method='POST' action='http://localhost/math/add'>
4.28 +Enter the two numbers to be added:<br/>
4.29 +<input type='text' name='a'/> +
4.30 +<input type='text' name='b'/>
4.31 +<input type='submit' value='Calculate'/>
4.32 +</form> </div> </div> </div>
4.33 + </body>
4.34 +</html>
4.35 +
4.36 +(woof)
4.37 +}]
4.38 +
4.39 +<p>The <span class='wf_code'>get</span> command will issue the
4.40 +equivalent of an HTTP request to the controller
4.41 +action <span class="wf_filename">/math/index</span> (using the example
4.42 +from the [my _chapter_link implementing_controllers]> chapter) and
4.43 +print the content generated by Woof!, including HTTP headers and
4.44 +content. In case of errors, the error stack will also be printed and
4.45 +if desired, standard Tcl debuggers can be used for stepping through
4.46 +the code. Debugging is much easier in this environment compared to
4.47 +using a real Web server and browser.</p>
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/app/controllers/_woof/docs/views/ug-generating_stubs-content.wtf Tue Nov 10 23:38:54 2009 +0530
5.3 @@ -0,0 +1,47 @@
5.4 +<p>The <span class='wf_code'>woofus</span>
5.5 +script's <span class='wf_code'>stubs url</span> command can be used to
5.6 +generate the common boilerplate code that is contained in Woof!
5.7 +controllers as was illustrated in the
5.8 +[my _chapter_link implementing_controllers] section of the
5.9 +[my _chapter_link quick_start] chapter.
5.10 +The general form of the command is</p>
5.11 +
5.12 +[my _code_sample {
5.13 + tclsh86 scripts/woofus.tcl stubs url ?-excludeviews BOOLEAN? ?list of urls?
5.14 +}]
5.15 +
5.16 +<p>For each URL specified as an argument, the command will check if
5.17 +the controller and action exist, and if not, generate stubs
5.18 +corresponding to each URL, creating files, classes and method stubs as
5.19 +necessary. Moreover, if
5.20 +the <span class='wf_code'>-excludeviews </span>option is not specified
5.21 +or specified as <span class='wf_code'>false</span>, the command will
5.22 +also generate a stub for the main
5.23 +[my _chapter_link page_sections "page section"].
5.24 +Specifying true for this option will prevent generation
5.25 +of the view stubs. Note that stubs for other page sections are not
5.26 +generated as they are expected to be shared between actions, and even
5.27 +controllers.</p>
5.28 +
5.29 +<p>The example below continues the one in the
5.30 +[my _chapter_link implementing_controllers "aforementioned chapter"].</p>
5.31 +
5.32 +[my _code_sample {
5.33 +> tclsh86 scripts/woofus.tcl stubs url /math/add /math/multiply
5.34 +Controller MathController:
5.35 + File app/controllers/math_controller.tcl will be modified.
5.36 + Class MathController will be modified.
5.37 + Methods to be added: multiply.
5.38 + View stubs to be added:
5.39 + app/controllers/views/math-multiply-main.wtf
5.40 +Do you want to continue? [YN] y
5.41 +Created action MathController.multiply.
5.42 +}]
5.43 +
5.44 +<p>The above example specifies the generation of stubs for
5.45 +the <span class='wf_code'>add</span>
5.46 +and <span class='wf_code'>multiply</span> methods. As indicated in the
5.47 +output, the script discovers only
5.48 +the <span class='wf_code'>multiply</span> stubs are missing and
5.49 +generates the same. The <span class='wf_code'>add</span> method and
5.50 +view are not touched in any way.</p>
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/app/controllers/_woof/docs/views/ug-recommended_reading-content.wtf Tue Nov 10 23:38:54 2009 +0530
6.3 @@ -0,0 +1,25 @@
6.4 +<p>For those who are new to either Tcl or Web development, here are
6.5 +some links to useful online resources.</p>
6.6 +
6.7 +<h3>Tcl</h3>
6.8 +<ul>
6.9 + <li>An <a href="http://www.tcl.tk/man/tcl8.5/tutorial/tcltutorial.html">online
6.10 + Tcl tutorial</a> provides a step-by-step introduction to the Tcl
6.11 + language. This tutorial currently covers features upto version
6.12 + 8.5.</li>
6.13 + <li>The <a href="http://en.wikibooks.org/wiki/Tcl_Programming">Tcl
6.14 + Wikibook</a> provides another introduction to the Tcl language and
6.15 + libraries.</li>
6.16 +</ul>
6.17 +
6.18 +<h3>Web development</h3>
6.19 +<ul>
6.20 + <li>eXtropia has a
6.21 + general <a href="http://www.extropia.com/tutorials/devenv/toc.html">introduction</a>
6.22 + as well as
6.23 + a <a href="http://www.extropia.com/tutorials/perl_cgi/pre_requisite_intro.html">tutorial</a>
6.24 + for web programming.</li>
6.25 + <li>An <a href="http://www.technicalinfo.net/papers/WebBasedSessionManagement.html">introduction
6.26 + to Web sessions</a> describes various mechanisms for maintaining
6.27 + session contexts and the tradeoffs involved in each.</li>
6.28 +</ul>
7.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2 +++ b/app/controllers/_woof/docs/views/ug-ruffian-content.wtf Tue Nov 10 23:38:54 2009 +0530
7.3 @@ -0,0 +1,8 @@
7.4 +<p>The <span class="wf_filename">ruffian.tcl</span> script, located
7.5 +in the <span class="wf_filename">scripts</span> subdirectory,
7.6 +generates reference pages for Woof! using the Ruff! documentation
7.7 +generator. For example,</p>
7.8 +[my _code_sample {
7.9 +tclsh86 scripts/ruffian.tcl woof.html
7.10 +}]
7.11 +<p>will generate Woof! reference documentation in the woof.html file.</p>
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/app/controllers/_woof/docs/views/ug-verifying_stubs-content.wtf Tue Nov 10 23:38:54 2009 +0530
8.3 @@ -0,0 +1,21 @@
8.4 +<p>When generating stubs using <span class='wf_code'>woofus</span>, it
8.5 +is sometimes easy to lose track of which stubs have actually been
8.6 +implemented and which are still to be
8.7 +written. The <span class='wf_code'>stubs verify</span> command
8.8 +provides a way of checking which stubs remain to be written.</p>
8.9 +
8.10 +<p>The example below is a continuation of the one in the previous section.</p>
8.11 +[my _code_sample {
8.12 +> tclsh86 scripts/woofus.tcl stubs verify
8.13 +ApplicationController: no stubs found.
8.14 +MathController:
8.15 + Action method stubs:
8.16 + multiply
8.17 +
8.18 + View stubs:
8.19 + app/controllers/views/math-multiply-main.wtf
8.20 +}]
8.21 +
8.22 +<p>The output shows that we have not actually implemented the stubs
8.23 +for the <span class='wf_code'>multiply</span> action method and
8.24 +corresponding view.</p>
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/app/controllers/_woof/docs/views/ug-woofus-content.wtf Tue Nov 10 23:38:54 2009 +0530
9.3 @@ -0,0 +1,9 @@
9.4 +<p>The <span class="wf_filename">woofus.tcl</span> script, located
9.5 +in the <span class="wf_filename">scripts</span> subdirectory under
9.6 +the Woof! root, implements some features that are useful in the
9.7 +process of developing applications. The general form of the command
9.8 +when invoked from the Woof! root directory is:</p>
9.9 +[my _code_sample {
9.10 +tclsh86 scripts/woofus.tcl COMMAND ?arguments?
9.11 +}]
9.12 +<p>The next sections describe these commands in detail.</p>