A framework that allows easy switching between form elements and static text.
Introduction
The dynamic elements in this framework provide an easy way to switch between user-editable form elements and static strings within the same page layout, all controlled via a boolean binding. In addition, they provide configurable filtering for HTML tags, to help prevent cross-site scripting or script insertion attacks on a dynamic web site.They are drop-in replacements for the standard dynamic form elements that ship with WebObjects 5.2; all of the existing bindings work as documented in the WebObjects Dynamic Elements reference, and if you change the type of your dynamic elements from WOTextField or WOPopUpMenu to SSTextField or SSPopUpMenu in your .wod files, your WOComponents will continue to work as is.
Version Compatibility
This is version 2.0 of the SwitchableString framework. It is compatible with WebObjects 5.2.x.
Bindings
All of the existing bindings for the dynamic form elements are still valid. To save space, they have not been re-documented here. The new bindings and their effects are:
| editable | If true or unbound, a form element is generated. If false, a static string is generated. |
| allowedTags | A list of allowed tags in the static HTML. Any tags not on this list are escaped; any tags on this list are passed through as is. It can take one of three forms:
A comma-separated string: "B,I,BR,strong" An old-style plist: "(B, I, BR, strong)" An XML plist: "<?xml version="1.0" encoding=\"UTF-8\"?>
</array> Case does not matter — "B" and "b" will both pick out all boldface tags. Note that you may need to \-escape double quotes if you are using a static string binding value in your .wod file. You should strongly consider allowing only the default set of "safe" tags from Slashdot.org: B,I,P,A,LI,OL,UL,EM,BR,TT,STRONG,BLOCKQUOTE,DIV |
| disallowedTags | A list of disallowed tags in the static HTML. Any tags on this list are escaped; any tags not on this list are passed through as is. The format is identical to the format used by the allowedTags binding. |
| truncateLength | Truncates a static string at this many characters. Useful if you are working with a WOText element that contains a lot of text which would be unwieldly to display in its entirety in the static text. |
| separator | Used to separate items in a list from a "selections" binding. The default separator (used if you do not set this binding) is ", " (comma space). |
For convenience, here is a set of links to the documentation for the base dynamic elements. (The on-disk links are for the updated version of the dynamic elements documentation that you can download from the developer.apple.com web site. The dynamic elements documentation that is installed with WebObjects 5.2 is incomplete.)
| In /Developer/Documentation | On developer.apple.com |
|---|---|
| WOBrowser | WOBrowser |
| WOCheckBoxList | WOCheckBoxList |
| WOCheckboxMatrix | WOCheckboxMatrix |
| WOPopUpButton | WOPopUpButton |
| WORadioButtonList | WORadioButtonList |
| WORadioButtonMatrix | WORadioButtonMatrix |
| WOText | WOText |
| WOTextField | WOTextField |
The allowedTags, disallowedTags, and escapeHTML bindings interact as follows:
The javadoc output for the new dynamic elements themselves is uninteresting, which is why you don't see them listed here. Look at the javadoc for the SSHelper class if you want to see how to create or work with a subclass yourself.
Developer Notes
I originally wrote the SwitchableString framework back in 1999 as a set of WOComponents. It was my first fumbling attempt at writing a set of reusable components, and while the Java class structure was fairly good, I didn't really grok bindings and dynamic elements properly so they were a bit rough around the edges.
While there are template .wo and .api files in this framework, they are purely for the use of WOBuilder — providing a nice display graphic and a template for the bindings. The templates are not used at all in the generation of the response.
This framework once again makes me long for multiple inheritance in Java. I had to pass extra parameters into the static methods in the SSHelper class that could have been accessed as instance variables instead.
Two of the elements, WOCheckboxMatrix and WORadioButtonMatrix, were tricky to subclass because they are based on WOComponent, not on WODynamicElement. With a WODynamicElement you have direct access to the WOAssociations since they are passed in as a parameter to the constructor; with a WOComponent you only have indirect access via the valueForBinding() method and the target of the call is one WOContext level higher up. As a result, I had to create the SSParentAssociation class to act as glue between the two elements and the rest of the framework.
There are a couple of features from the original which I have left out of this version as gilding the lily. The editUserLevel and currentUserLevel bindings have been removed as excess baggage — this kind of code is really a part of the developer's business logic and shouldn't be a part of the framework. Also, SSText used to have a table wrapping the static text so that it would fit into roughly the same space as the TEXTAREA element, but it never worked really well and would have required a lot of special-case code in this framework so I dropped it.
There is an additional Javadoc sub-target in the project which builds this javadoc-based documentation. It is generated fresh from the source each time you do a build. The deprecation warning is for the WOCheckBoxList and WORadioButtonList classes which have been deprecated. They are subclassed in this framework for completeness.
License
This framework is distributed under a modified BSD license as follows:
Copyright (c) 2003 Paul Suh. 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 the site goodeast.com nor the names of its 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 THE COPYRIGHT OWNER OR 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.
Revision History
Version 2.0.1: Fixed warnings/errors in Javadoc target November 4, 2003.
Version 2.0: First general release October 23, 2003.
1999: Original SwitchableString 1.0 framework written for WebObjects 4.0. Never publicly released.
Paul Suh