|
jacquard 1.12.0 by The Web Engineering Factory and Toolworks | |||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||
See:
Description
| Interface Summary | |
| ResourceConsumer | An interface for anything that consumes resources. |
| Class Summary | |
| ActionColumn | a column which may be added to a ResultFormatter to allow users to perform actions on individual rows. |
| ActionWidget | An action widget for a hypertext form. |
| AuthenticatedForm | An HTML form with a guaranteed, authenticated database connection, persistent for the life of the session. |
| AutoForm | a form constructed by reading the servlets and widgets it requires from a database. |
| Auxiliary | Auxiliary table information in a Form. |
| BooleanWidget | A Boolean Widget for a hypertext form, by default implemented as a checkbox. |
| Button | Deprecated. see ActionWidget |
| CalendarPseudoWidget | Not really a widget at all, but inheriting from widget so that it can be layed out in forms. |
| ChangePasswordForm | Change password for the currently logged in user. |
| CheckPasswordWidget | A control for adding a new, or changing an old, password. |
| CompositeStylesheetSample | generate a page with sample content to show off the stylesheets selected in a CompositeStylesheetWidget, q.v. |
| CompositeStylesheetWidget | In setting up customisable content management systems (which, let's face it, is 90% of what we do) it's often useful to allow the users to choose - mix-n-match - CSS stylesheets from a number of previously set up stylesheets. |
| Cookie | A cookie, set in an HTTP response. |
| CurrencyWidget | a widget to handle currency. |
| DataMenuWidget | A menu widget taking options from a specified query against a specified database: Must be in an AuthenticatedForm. |
| DataTable | A DataTable is a simple component intended to be used as an embedded servlet which shows tabular data. |
| DateWidget | A composite widget set up to handle dates. |
| DoubleWidget | A widget which constrains entry to floating point numbers -- if JavaScript allows. |
| EkitWidget | A widget for editing an HTML fragment which makes use of the Ekit WYSIWYG editing applet, if the browser will support it, and reverts to the classic HTMLTextAreaWidget where the browser won't. |
| FileMaybeUploadWidget | A file upload widget for a hypertext form. |
| Form | An HTML page which is principally a form. |
| FormLayout | A layout engine for a form. |
| HiddenWidget | A 'hidden input' for a hypertext form. |
| HTML2FormLayout | A layout engine for a form, adapted to browsers which do not support tables. |
| HTMLTextAreaWidget | A textarea widget which knows how to convert text into a very basic HTML fragment. |
| ImageFileMaybeUploadWidget | A file upload widget for a hypertext form, which assumes the file uploaded is an image which may reasonably be displayed. |
| IntegerWidget | A widget which constrains entry to integers -- if JavaScript allows. |
| LabelPseudoWidget | Something which can be laid out like a widget and shows data from the database like a widget but doesn't allow the value to be modified. |
| Layout | A layout engine for a page. |
| LinkTableWidget | In some simple database designs many-to-many relationships are represented by simple link tables. |
| List | An HTML page which is principally a dababase listing. |
| MenuOption | An option in a MenuWidget. |
| MenuWidget | A menu widget implemented as an HTML <SELECT> object: options are provided as uk.co.weft.MenuOption objects, q.v. |
| MessageBuffer | A StringBuffer which knows about substitutions and text wrapping... |
| MultiSelectOption | An option in a MultiSelectWidget. |
| MultiSelectWidget | A multiSelect widget implemented as an HTML <SELECT> object: options are provided as uk.co.weft.MultiSelectOption objects, q.v. |
| OneFieldAuxiliary | A special auxiliary for cases where the auxiliary table has only one other significant field apart from the foreign key field to the parent table |
| OptionSensitiveHelpMenuWidget | A widget which shows different helptext depending on the option which is currently selected. |
| OrderedLayout | A form layout which layout first all normal input widgets in the order they were added, then all action widgets in the order they were added, and finally all hidden widgets in the order they were added. |
| Page | An HTML page, generated by a servlet. |
| PasswordForm | A form for changing the currently logged in database user's password. |
| PasswordWidget | A 'password input' for a hypertext form. |
| ProgressMeterPseudoWidget | Not really a widget at all, but inheriting from widget so that it can be layed out in forms. |
| QueryByExampleList | a list which enables query-by-example. |
| RangeWidget | A widget to return integer values between a specified minimum and maximum, or zero to ten if no values are specified. |
| ResourceConsumerImpl | A superclass for classes which wish to implement ResourceConsumer. |
| ResultFormatter | A ResultFormatter is just a wrapper around a ResultSet that knows how to lay itself out in a Context. |
| SearchableDataMenuWidget | DataMenuWidgets which grow past a certain size are unusable, both because they're too slow to download and render and because it's too hard to find what you're looking for in them. |
| Servlet | This is a basic servlet which produces nothing; to produce anything, specialise generateContent(). |
| ServletForm | A meta-servlet: a servlet for editing servlet definitions. |
| ShuffleOption | An option in a ShuffleWidget. |
| ShuffleWidget | MicroSloth browsers have a particularly unhelpful implementation of multi-select widgets. |
| SimpleDataMenuWidget | Essentially this is just an interface to DataMenuWidget which makes it simpler to set up the menu you want. |
| TableWrapperForm | An HTML form wrapped around a single database table to allow editing of individual records. |
| TextAreaWidget | A textarea widget implemented as an HTML TEXTAREA object. |
| TimeStampWidget | A widget for collecting or displaying a date/time value |
| TimeWidget | A widget set up to handle times. |
| URLWidget | a widget which checks that the value passed is a URL which is fully specified and has valid syntax |
| Widget | A widget for a hypertext form. |
| WidgetForm | a form for populating a database table used by AutoForm. |
| WidgetSet | A complete functioning set of widgets for a hypertext form. |
| WithExceptionHandlerServlet | A class which abstracts out exception handling from more specialised Jacquard servlets. |
| Exception Summary | |
| InitialisationException | A general purpose exception thrown if an HTForm component fails during initialisation. |
A simple, lightweight infrastructure package to support writing servlets, especially servlets which access and update database tables.
Database applications | Passing values | Authentification | Layout | JavaScript | To Do | License
A simple, straightforward layout of data forms is automatically supported by Form; just add Widgets to your Forms in the order you want them layed out. Add your own formatting by providing a stylesheet, and by providing your own specialisations of Form.preForm() and Form.postForm(). To have your form do something, add an ActionWidget and write a defaultActionHandler() method. To have two or more different actions happen by pressing different buttons, specialise ActionWidget to get different types of ActionWidget with different execute() methods. For an example to copy, look at TableWrapperForm.
Database forms are fundamentally what this package is all about, and creating them is absurdly simple. Specialise TableWrapperForm; in your init method, set up the name of the table you want to edit and its primary key field. Then add an appropriate widget for each field you want to be able to edit. If the field is a foreign key onto another table, add a SimpleDataMenuWidget. If it is a foreign key onto a link table which handles a many-to-many join with another table, just add a LinkTableWidget. That's all. Database authentification, record fetching and updating, are all taken care of for you.
Values which arrive in an htform servlet are all available to you as values in the servlet's context object, regardless of whether they arrived as GET or POST paramaters or as cookies, environment variables or anything else. Access them through the context's get() method.
To pass values on, there are a number of possibilities. One is to use putPersistent(); this stores the values on the servlet's session object, and allows you to access it for the remainder of the current session. If you only want to pass a value from a Form to the next servlet in the chain, it may be better simply to create a HiddenWidget.
Finally, you can set cookies, and this is likely to be the best way to communicate between htform servlets and other dynamic content generators, or to pass values which will be retained for more than one session; simply use addCookie(). The value of the cookie will be the value which exists for that name in the current context; you can set it with Context.put(). I don't recommend you use cookies to pass values to other htform objects residing on the same host, and in the same session; use PageContext.putPersistent() instead.
Specialisations of AuthenticatedForm will automatically prompt for user authentification the first time it is required in a session. The username and password given are then passed to the database server for authentification via JDBC. Consequently, the name and password must be valid on the database server. This means that access policies can be implemented at the database layer rather than at the client layer.
If you don't want to handle authentification like this you are better to specialise Form.
htform supports two database connection models, the default model which maintains a separate pool of database connections, used by servlets which are specialisations of Page or Form; and the session model in which each session carries it's own connection, available to specialisations of AuthenticatedForm.
The default model should be used for sites which are going to be hit frequently by lots of different people, with each session only making a few hits, and where database security isn't an issue; the session model should be used where individual users will make more extensive use of the site, or where database security is an issue.
Obviously, the two models can be mixed on one site, and it is quite possible to pass in one session from AuthenticatedForms using the session model to simple Pages and Forms using the default model and back to AuthenticatedForms again, at which point the original session-based connection will again be used.
However, you only need to worry about any of this if you are writing complicated things. Most database systems can simply be built on TableWrapperForm, which uses the session model.
We mostly build things for Intranets, and one of the advantages of that is you know (and can enforce) what browsers people are using. This package is designed to output correct HTML, so it should work with all Web browsers - but there has been little effort to make the appearance customisable on pre-CSS browsers. We think the appearance on pre-CSS browsers is clean and simple; you might call it stark. However, with CSS, you can customise a great deal of the appearance.
One of our more elegant widgets is the ShuffleWidget, which lays out two multi-selects side-by-side, and allows items to be moved between them, like this:
This widget (and LinkTableWidget, which depends on it) depend crucially on JavaScript and will not work without it. Furthermore, all our JavaScript is written to JavaScript 1.2 and won't work with earlier versions. A number of our other widgets also use JavaScript for client-side validation, but these will continue to work without JavaScript.
HTForm is now thorougly mature and generally very reliable. It has been supporting real world applications reliably for seven years now.
It's obvious, given the simplicity of building database applications using htform, it should be possible to automate the process completely given an adequate data dictionary. This is the motivation behind AutoWrapperForm, which doesn't fully work yet. High on the TODO list is fixing AutoWrapperForm.
Some more complex widgets are still missing. Among the things we want to support are:
Additionally, at some stage we would like to rewrite all the client-side stuff to work in older JavaScript environments; at present we only support JavaScript 1.2, and we appreciate this is a limitation. In particular, MultiSelectWidget and LinkTableWidget depend heavily on Javascript and essentially don't work without it.
Finally, there's undoubtedly still a considerable amount of tidying up to do, and we're sure you think this documentation could be improved!
The following is the whole of your license and warranty to use this package:
[Note: this is the 'BSD License' as endorsed by OpenSource.org.]
Copyright (c) 1998,1999, Simon Brooke. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Simon Brooke. nor the names of other contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SIMON BROOKE OR OTHER CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
� Simon Brooke, Carlinscraig, Auchencairn, DG7 1QU, Scotland.
|
jacquard 1.12.0 by The Web Engineering Factory and Toolworks | |||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||