$Id: FAQ.xml,v 1.15 2003/03/03 05:41:01 russcoon Exp $
Copyright © 2003 Alex Russell
Revision History | |
---|---|
Revision 0.4 | March 1, 2003 |
Editorial revisions. | |
Revision 0.3 | Feb 28, 2003 |
Filling out sections on configuration, JS language feature requirements, browser support, Signals and Slots, debugging, and code base size. Removing duplicate questions. | |
Revision 0.2 | Feb 21, 2003 |
Filling in answers to many questions | |
Revision 0.1 | Feb 18, 2003 |
First Revision |
Abstract
netWindows is a flexible client-side toolkit designed to aid in the development of web application interfaces. This document provides developers with answers to many of the most pertinent questions of those beginning to develop with or those evaluating netWindows.
Q:. | How do I integrate the netWindows distribution with my own project at the web application directory level? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | The 0.3 series allow netWindows to "live" anywhere, even on different servers than the applications using it. Despite this, most developers integrate netWindows into their local web server root, and netWindows provides many options to support both types of configurations. netWindows does not have to be "above" or "below" the page calling it (relative to the web root), and indeed, all of its script directories can be moved and renamed. The only major caveat to netWindows's path flexibility is the location of script groups. netWindows provides core, theme, and widget files in their own directories and the toolkit will look for all scripts of each group to be in the same directory, although all scripts from the entire distribution could be put in the same directory if desired. The simplest way to use netWindows is to simply extract the release files into a directory under the web root. This will create a directory with this structure: ![]() Once extracted, include the netWindows.js file with a relative URL. Many developers require more flexibility regarding netWindows path locations than this method can provide, and netWindows supports these needs through a set of configuration variables and a wrapper script that can be easily customized to meet almost any server or directory layout need. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | What is the minimum code required to get netWindows working on an HTML page? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | The core of netWindows will automatically self-load if the file netWindows.js is included like this: <script src="winScripts/netWindows.js" language="JavaScript" type="text/javascript" ></script> ImportantNEVER specify language="JavaScript1.2", always use "JavaScript" or "JavaScript1.5". netWindows relies on features introduced in JavaScript 1.3. Specifying JavaScript version 1.2 in any script declaration on a page will throw Mozilla (and other Mozilla derived browsers) into a "bugs mode" not unlike that triggered by older HTML DTDs in many browsers. If netWindows detects that it is running in a JavaScript 1.2 environment it will throw an exception and will NOT complete loading. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | What netWindows JavaScript files do I need to explicitly load, and which self-load? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | The only file that need be explicitly included (either directly, or through a wrapper script) is netWindows.js. When netWindows.js loads, it immediately requests the following files (found in [netWindows root]/winScripts by default):
Through the use of a wrapper file or with some direct calls to __scripts__.require() (before the onload event fire), one can easily instruct netWindows to load other scripts. The primary use of this facility is to include widgets, which may include their own file dependencies which will be automatically loaded. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | When netWindows is included in a page, how do I know what it's doing at each stage? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | The netWindows loading concept can be thought of as a series of stages, with no netWindows objects or methods available prior to the inclusion of netWindows.js. Procedure 1. The netWindows loading concept.
Scripts declared or included after netWindows.js are guaranteed access to all of the core netWindows objects and scripts. For instance, the following code illustrates how to register a number of functions that will be called when the onLoadevent fires. NoteAttempting to assign window.onload directly may cause netWindows to fail when loading.<html> <head> <!-- no netWindows objects are available up here --> <script src="winScripts/netWindows.js" language="JavaScript" type="text/javascript"></script> <!-- all netWindows core objects (including __sig__) are now in scope --> <script language="JavaScript" type="text/javascript" > function postOnLoad(){ alert("It's the end of the world..."); } function postOnLoad2(){ alert("...and I feel fine"); } __sig__.connect(__env__, __env__.onLoad, null, postOnLoad); __sig__.connect(__env__, __env__.onLoad, null, postOnLoad2); </script> </head> <body> </body> </html> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | How do I configure netWindows? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | netWindows supports quite a few runtime options that affect the behavior of the toolkit. Things that can be configured include:
netWindows provides two methods for specifying each of these options. The first is a specially named array, NWconfig, whose elements must be set prior to the inclusion of netWindows.js. Alternately, netWindows can be configured using HTTP GET strings (if this feature is enabled via NWconfig). As an example, the following code disables the built-in theming provided with netWindows, deferring look and feel styling to CSS classes. GET string parsing of configuration directives is also enabled: var NWconfig = []; NWconfig["applyThemedStyles"]=false; NWconfig["obeyRequestEnv"]=false; Wrapper scripts can combine both configuration and and inclusion of netWindows.js into the same file. For more detail on the available options in your netWindows environment, see the example wrapper script provided in the distribution. This script contains a listing of all the available configuration variables and descriptions of their effect. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | What is a wrapper script? How do I use one? Is there a pre-built wrapper that I can use? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | Starting with 0.3, netWindows provides a sample wrapper script to illustrate the available options and provide for common netWindows configurations across multiple pages or sites. Without a wrapper script, the code to configure netWindows to use CSS-based theming, load the netWindows core framework, and include the button widget is: <html> <head> <script language="JavaScript" type="text/javascript"> NWconfig = []; NWconfig["applyThemedStyles"]=false; </script> <script src="winScripts/netWindows.js" language="JavaScript" type="text/javascript"></script> <script language="JavaScript" type="text/javascript"> __scripts__.require(__config__.widgetPath+"button_widget.js") </script> </head> <body> </body> </html> While straightforward, requiring that developers include this much (or more) code on every page they build is rather cumbersome. The situation only worsens as more widgets and configuration options are used. A netWindows wrapper can make this more manageable. For example, consider the following wrapper script to achieve the same thing (we'll call this nwWrapper.js): // the base URL need not be on the same server as the app var NWrootURL = "http://url.to.my/netWindows/intstallation/"; // change the next line if you want the core to "live" elsewhere var NWcorePathDir = "winScripts/"; // netWindows environment configuration var NWconfig = []; NWconfig["applyThemedStyles"]=false; NWconfig["corePath"]=NWcorePathDir; NWconfig["rootPath"]="./"; NWconfig["loadEvalName"]="loadWidgets"; function loadWidgets(){ with(__scripts__){ require(__config__.widgetPath+"button_widget.js"); // we can easily include other widgets here } return true; } // start inclusion of the netWindows framework document.write('<script language="JavaScript"'); document.write(' src="'+NWrootURL+NWcorePathDir+'netWindows.js"'); document.write(' type="text/javascript"><\/script>'); Using this new script, we can shorten the first example to this: <html> <head> <script language="JavaScript" src="http://some.path/nwWrapper.js" type="text/javascript"></script> </head> <body></body> </html> Multiple pages can benefit from the same configuration by including the same wrapper file, making it much easier to maintain a complex, changing netWindows configuration across applications with many pages. Developers can also build "testing" and "production" wrappers that specify different netWindows options to provide more or less debugging capability while ensuring that that they need replace only one file when deploying an application. This is especially handy for debugging against "source" versions of netWindows and deploying with their comment and white space stripped counterparts (provided in the distribution). A sample self-documenting wrapper script that outlines all of the options available to netWindows developers is provided in the 0.3 distribution and is named nwWrapper.js. A copy of this file is available via anonymous CVS. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | What EcmaScript language features are required by netWindows? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | netWindows makes heavy use of Object Oriented JavaScript, associative arrays, and inheritance. Some quirks with the 1.2 version of the language prevent netWindows from working reliably. Therefore JavaScript version 1.3 or higher (preferably 1.5, aka ECMA-262 3rd edition) is required. If netWindows detects that it is running under an interpreter in JavaScript 1.2 mode, it will not load. If you find that you are having problems getting netWindows to initialize, please make sure that JavaScript 1.3 or higher is specified in all script tag declarations. Aside from this restriction, most of netWindows's dependency-related issues tend to be with the broken DOM implementations provided by various browsers. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | What browser makes and versions is netWindows known to work on? Known to not work on? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | netWindows is designed to make extensive use of the W3C DOM where possible, while abstracting away proprietary interfaces where DOM-only solutions are cumbersome or non-existent. With that in mind, no "4.0" browsers are supported directly or indirectly by the toolkit. Since many browsers have version numbers which are out of sync with the numbers adopted by the major browser manufacturers in terms of capabilities provided at a given version number, what follows is a brief list of browsers known to work and the various platforms they are supported on. Where support is fractional or there are major caveats, they are listed. Browser Support
We fully expect that netWindows will be capable of running on even more browsers as the market penetration of standards-compliant browsers grows. It's believed that better than than 90% of desktop web clients are netWindows capable. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | How do I arrange to have a function called after netWindows finishes loading? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | netWindows provides several mechanisms to register callbacks or listen for signals at various points in the loading process. The easiest way to have a function called is to attach a slot to a signal that will be send when netWindows finishes initializing. ImportantScripts that wish to register a signal in this way MUST connect to the signal after netWindows.js has been included. Attempting to connect a function to the __env__.onLoad signal earlier will result in errors (as neither the __sig__ nor __env__ objects will be available yet). Other methods of registering code to be called during or after loading are available, but are not widely used and are discouraged from normal use, as they may be deprecated or removed in subsequent versions. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | How do I debug netWindows problems? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | The first step in debugging netWindows problems, notably inline constructors, is to ensure that your code and HTML is well formed (opening and closing tags in the right places). Experience has shown that when inline constructors mysteriously "fail", more often than not badly formed HTML is to blame. Next, ensure that netWindows is not being being called into a page containing script tag declarations that specify language="JavaScript1.2". netWindows will not load if this is the case, so be sure to specify "JavaScript" or "JavaScript1.5". If that does not solve the problem, try the page/application in multiple browsers to determine if the problem is browser-specific. Mozilla in particular has top-notch debugging facilities. Try loading the page in Mozilla with the JavaScript console open. If an error is thrown, it will be displayed to this console, including line numbers, a contextual error fragment, and file name. If you suspect the problem is with netWindows (and not your code), please put all of these details in an email to the netWindows developers mailing list <devel@netWindows.org>. You must be subscribed to the list to post to it. For the JavaScript savvy, consider using the Mozilla debugger (Venkman) to set breakpoints and intercept exceptions. Alternately, try instrumenting your code using the netWindows debugging console. To use it, simply enable it in your environment and call stdout() with your debugging output as an argument. A script debugger is also available for IE, however it is of lower quality than that of Venkman. We recommend using Mozilla for debugging JavaScript unless your problem is not reproducible on that platform. To report problems with netWindows, please use the bug submission form at the SourceForge project page or report the problem to the developer's mailing list <devel@netWindows.org>. ImportantOnly bug reports that include the reporters email address, browser (name, version and OS), and netWindows version will be given serious attention. Reports not including this information in addition to a detailed problem description may be closed due to insufficient information. We can't fix bugs we can't reproduce. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | Isn't netWindows too big? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | One of the most frequent concerns voiced by those new to netWindows is the size of the toolkit. The size of the white space stripped core scripts approaches 60K in size, while the "source" versions are even larger. This is not the bitter pill it first seems, though. Unlike 60K of content (text or page-specific images), external JavaScript files (which is how the entire netWindows distribution is provided) are cached between page views, meaning that for a given domain it is probable that a user with normal cache settings will only download the toolkit once, regardless of how many pages make use of it. For sites looking to retrofit existing applications with netWindows widgets, browser-side caching of script objects can make netWindows very fast indeed. Applications that make use of the netWindows content loading mechanism can actually increase the responsiveness of their applications by removing the verbose re-sending of formatting for data each time anything on a page changes. netWindows allows you to develop applications that are long-lived (a single page can do many things, and therefore, can stay around a long time without refreshing). Using the netWindows content and data loading mechanisms in conjunction with netWindows widgets for data presentation, your applications to send only data across the wire (and only the data that has changed), thereby eliminating the overhead and latency required with in re-sending identical navigation elements and data between page views. By letting smarter client applications manage interface state, server-side applications can be freed to manipulate and send only data with only structure, not formatting, to the client. For more information on how netWindows can help reduce perceived latency in your application, see the article "netWindows and the Round Trip Problem" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | Can I use netWindows in my intranet application? In my commercial product? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | Yes! So long as you don't claim you wrote it, and you can do (almost) anything you like with it. netWindows is licensed very liberally. The netWindows license allows for use of the code for purposes both Free and commercial. While some may see this weak Open Source license as a liability for the project, it was chosen to promote the fastest uptake of the toolkit by the widest possible audience. We want as few barriers to inhibit developers using netWindows as possible while still providing the netWindows team with the ability to re-license the code as we see fit in special cases (which is why we retain and will vigorously enforce all of our copyright rights). Unlike some Open Source licenses, netWindows places no restrictions on redistribution or modification. Virtually the only thing forbidden by the netWindows license is removal of copyright notices or other breaches of the author's copyright, subject to modification by licensing terms. For example, a business cannot claim copyright ownership over netWindows code or legally derivative works. The netWindows license indemnifies the netWindows team of all liability (written or implied) and does not allow licensees to use the netWindows author's name or trade names in conjunction with the code without express written consent, copyright notices excepted. See the project license page for details. Developers or organizations looking for commercial development and support options for the netWindows toolkit should contact Alex Russell <alex@netWindows.org> directly. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | How does netWindows compare to DynAPI, WebFX, DomAPI, and others? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | While we won't discuss specific differences between netWindows and other APIs, there are several technical and licensing features that taken together make netWindows unique.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | How much JavaScript do I need to know to use netWindows? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | It is possible to use netWindows widgets without a single line of JavaScript (aside from the line to include a wrapper script) through the use of inline constructors. Some features of netWindows are of benefit mostly to those using JS, but netWindows tries to meet developers at their comfort level by providing advanced features to those who need them and a quick learning curve to those that don't. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | What are "inline constructors"? How are they used? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | One of netWindows most distinctive features is its concept of "inline constructors", specially structured and augmented blocks of HTML that provide the toolkit with the ability to provide advanced DHTML widgets that are both simple to use and degradable for DHTML-poor web clients. Most DHTML toolkits require explicit declaration of a widget in JavaScript. For instance, this snippet can be used to create a button widget that includes an image in it's label using an alternative toolkit (DomAPI): var buttonElem = Button({x:100,y:100,w:100,h:25,caption:'<img src="foo.gif" align="absmiddle"> Foo!'}); Which can be compared to the same JavaScript "traditional" constructor using netWindows var buttonObj = new NW_WIDGET_FACTORY_button("Foo!", 100, 25, "foo.gif"); with(buttonObj.domNode.style){ top = "100px"; left = "100px"; } Both of these are rather simplistic and neither define custom actions for various button states, but both widgets allow it. However, many people will not want to learn or write even this much JavaScript, and may not know in the <head> section of a document where a widget will be wanted. To address these concerns, netWindows allows for the equivalent inline constructor for this button widget: <div nwType="button" text="Foo!" image="foo.gif" width="100" height="25" styleList="left: 100px; top: 100px;" /> This can alternately be declared with a one-child-per-attribute style, which would yield this block to create the same widget: <div nwType="button"> <div nwProperty="text">Foo!</div> <div nwProperty="image">foo.gif</div> <div nwProperty="width">100</div> <div nwProperty="height">25</div> <div nwProperty="styleList">left: 100px; top: 100px;</div> </div> This declaration can live anywhere inside the <body> tag of the document and will be replaced with a button widget exactly where it is declared after the page loads. The constructor's functioning does not rely on the element type of the tag it is created with, so the above widget could be declared as easily with a <button> tag as with the <div> tag used in the example. Almost all netWindows widgets provide both "regular" and "inline" constructors. Inline constructors whose widget definitions have not been included will not be parsed. One of the most damning criticisms of DHTML widgets has traditionally been their inability to degrade gracefully. Instead of getting a slightly less functional page when DHTML support is not available, most DHTML toolkits simply fail without any warning or recourse. Inline constructors provide an answer for this. Consider the following inline constructor for a combo box: <select nwType="combo_box" name="foo"> <option nwType="option" label="toe foo" value="bar">toe foo</option> <option nwType="option" label="foo" value="bart">foo</option> <option nwType="option" label="food" value="bard">food</option> </select> This declaration will provide a combo-box that can provide incremental text matching over all of the labels available. Users without a full DOM implementation available through their browser will simply see a "regular" HTML select box. Inline constructors are one of the most compelling reasons to use netWindows to provide advanced UI functionality for existing web applications. Developers looking for simple to use, easy to understand, degradable DHTML widgets to enhance their app can start using inline constructors without becoming invested in the programmatic API to netWindows. The demo pages provided with the toolkit provide examples of most of the options and syntax for the both the programmatic and inline constructors of each widget. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Q:. | Where can I find out about the netWindows event system (Signals and Slots)? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
A:. | Alex Russell (the netWindows Project Lead) has written an article describing the Signals and Slots mechanism used in netWindows. For a better overview of what Signals and Slots are all about, see the Trolltech description of their C++ Signals and Slots implementation. Note that netWindows does not require any sort of pre-compiler the way QT does, however netWindows does require more syntax to "throw" a signal. |