Getting Started with the VisualWave Web Toolkit From time to time we may publish updated versions of the WebToolkit parcels, as we add new functionality and/or fix bugs. For the most recent files and parcels, please see http://www.cincomsmalltalk.com/updates or ftp://www.cincomsmalltalk.com/updates Documentation ============= Full documentation for the Web Toolkit concepts and features is described in the VisualWave Application Developer's Guide (waveadg.pdf). The VisualWave Server Configuration Guide may also be useful for setting up your web server (wavescon.pdf). The following sections briefly describe some of the major features to help you get started. Runtime ======= The easiest way to get started is to use the pre-packaged headless image $(VISUALWORKS)/web/runtime.im and some of the example files. Step 1: ------ Assuming visual.exe is in the path, or has a shortcut, in this directory start up the image with (UNIX) visual.exe runtime.im (Windows) visual.exe runtime.im Step 2: ------ Start up a web browser and connect to http://localhost:8008/ You should see the configuration Welcome Page. The Default Configuration is initially set. With this configuration you can visit and investigate a variety of examples which demonstrate features of the Web Toolkit. Step 3: ------ To run the ToyzInc Demo press the "Configure For Demo" button. Step 4: ------ Now connect your web browser to http://localhost:8008/toyzinc/ You should see a demo of a basic shopping site. Development Image ================= For more serious work and debugging, you'll probably want to run a development image with a web server in it. To create one, - Load the WebToolkit parcel from this directory into a VisualWorks image. - Open the Server Console (the button on the right of the toolbar with a globe). - Click on "Create Server". - Switch the type of Server to "TinyHttpServer", and check the box that says "Start server on system start up". - Click the box at the bottom that says "Create and Start" If you wish to use the Cincom Smalltalk logo on the WebToolkit Configuration Pages, copy cst_sp_logo.gif to the directory which contains your image. Note there is an internal logo which will be used if this one is not accessible. Servers ====== We're showing the web browser connecting through the native Smalltalk HTTP Server at port 8008. It's also possible to connect through CGI, through ISAPI using IIS, through FastCGI using Apache or other servers, and using NSAPI using the Netscape/iPlanet server. Many of these, particularly FastCGI and ISAPI, offer advantages over the pure Smalltalk server or CGI. See the VisualWave documentation and the readme information for the new gateways to see how to configure these. ASP/JSP/Servlets ============== The largest new area in the web toolkit is the support for de facto web standards like ASP, JSP, and Java Servlets. Our implementation follows the standards quite closely, so if you're familiar with them, you should be right at home. Naturally, we're using Smalltalk rather than BASIC, JavaScript, or Java, but with the JSP custom tags you can actually build pages that will run interchangeably between a Smalltalk and a Java server. We include documentation, but if you're not familiar with these mechanisms, we recommend you also get information on these subjects to understand the concepts, strengths, weaknesses, and usage patterns. The ToyzInc demo shows some of the ideas that we think would go into a reasonably designed application built with these kind of tools. It also tries to exercise many of the different facilities available. Content Management ================ The other area that will most affect you is the support for content management, including virtual directories, logical links, and site configuration via files. Take a look at the example .ini files in this directory, which specify the configuration for our test sites, and define a number of logical names. Logical names help you organize a site so that links can be changed without breaking many other pages. In addition, they can simplify URLs (e.g. eliminating the need for /servlet prefixes on servlets) and can be dynamically resolved for complex links and/or includes. Examples ======== In the web/examples directory are a number of examples, each of which has its own brief readme file describing it. These should help you get started on your own work. The readme file in the web/examples directory can be used as the main entry point. It contains links to the other example readme files. The "default" web site is configured to access the examples pages. Just visit the site from the configuration pages, or point your web browser to http://localhost:8008/readme.html and select the various readme.html pages to start each example. There are also examples of content management features in the web/tests directory, with a readme file describing the tests. To access the content management tests, go to the configuration Welcome Page and select "Configure For Tests". This will reconfigure the server for the tests. You should see two sites configured as virtual directories, the "default" site and the "tests" site. To run the tests, start up a web browser and connect to http://localhost:8008/tests/ and follow the links to exercise the content management features. Note that the "configure" site is a special site which is only capable of serving internally generated configuration pages. It cannot be visited. However, this site may be configured either through the configure-site.ini file or through the Smalltalk code which configures this site (see WebSite class >> initializeConfigureSite), or with a combination of both. Debugging and Caching ====================== There are a number of options which control debugging in the server. The "Debuggable" option in the web site configuration turns page caching on and off. If debugging for a site is off, then the compiled version of pages will be cached. This is most appropriate for a production situation. To clear out the cache, use the "Clear Caches" option on the configuration page. Normally during development you will want the site to be debuggable. ProcessEnvironment>>isDevelopingOverride: controls whether exceptions are trapped or whether an unhandled exception in a page will result in a debugger on the server. This is true by default on startup, and automatically set to false as part of the deployment process. You can also control this on a per-server basis by setting the flag in the Wave Server Console that says "Trap All Exceptions/Allow Notifiers on Server".