Basic ucw mechanics <- back | toc | forward -> Widget Components

Yaclml tags

This will partly be a rehash of what's explained about them in the Basics chapter, but it might be covienient to have all the yaclml explanation in the same place.

standard yaclml tags

Yaclml is the default html emitter library ucw uses. Yaclml defines a set of macros that correspond to html tags. The standard yaclml tags map directly to html tags, but there are a few that add functionality. Yaclml first checks if it's followed by keywords which get converted to html-attributes if they are allowed by the xhtml 1 standard. The rest of the arguments are used for the body. Everything is parsed and is princ'ed to the *yaclml* stream. Standard use of a tag looks like this:

(<:p :class "a-class" "bla bla")
    

The "<" is really a nickname for the yaclml package, and p is a macro in the package.

You can use the <:as-html (or <:ah) macro and just type big slabs of html-escaped text or use <:as-is (or <:ai) to produce un-html-escaped text. Normally objects are output as html-escaped by default, but objects that are the product of function calls need a push to be printed.

extended yaclml tags

For some html tags ucw has it's own yaclml equivalent with extended functionality: a, area, button, form, select, option, textarea and input. For convenience ucw gives the input attributes text, password and submit their own tag. Furthermore ucw sports such outlandish tag-names as integer-range-select, month-day-select, month-select, render-component, simple-form, simple-submit and script. All these tags become invocable macro-forms by putting <ucw: in front of them; eg by searching for them in the ucw namespace.

The extra functionality comes from the extra keywords you can pass them: :action, :accessor, :reader and writer. The macro's can handle one or more of these, depending on the macro, but the keywords are mutually exclusive. With the :action keyword you can specify an action form which will be executed with the relevant parameters when the form returns. With :accessor you can specify a place. It's value is the initial value of the specified tag. If the tag returns a value, the place will store it. :reader and :writer are used as a team to provide more flexibility than :accessor does. If provided, the value of :reader is used as the initial value of place. The value of writer should be a function which accepts one argument: the value returned by the tag.

You can use :accessors only for elements that can be embedded in a form. You then give the form an action to initiate with :action. As long as you keep on rendering the current component your slots will be automagically updated. For examples for all of this check the code in the previous chapter.

special form tags

Normally forms come with a bunch of javascript to play nice with other javascript code. A javascript enabled browser is not strictly necessary for the form to behave well but if you don't want the javascript use <:simple-form. It will not play nice with <ucw:submit though.

Submit buttons also standard come with javascript code on the client side. <:simple-submit provides a button without javascript which can be used with <ucw:form as with <:form. The great thing about this one is that the standard <ucw:submit won't let you define actions on it. With this one you can.

Select fields

The html select tag knows quite a few incarnations in ucw. A roundup:

• <:select - works just like a html <select>. Accepts all of <select>s attributes.
• <:option - works just like an html <option>. Accepts all of <options>s attributes.
• <ucw:select - What's cool about this one, except for the accessor stuff you know from other <ucw:bla.. accessors is that its options, when they are also foregone by <ucw: can hold any lisp object as their value. So it has some extra options to deal with them. It also supplies an on-change keyword (not to be confused with onchange) which automatically generates javascript that submits the action it holds as its value, without the need for a submit button. A breakdown of its keywords:
  • an :accessor or a :writer (not a reader since that functionality travels through the <option> options) - works pretty much like any other <ucw:bla accessor or writer.
  • :test - a test function to compare values. Defaults to eql
  • :key - a key which defaults to identity
  • :on-change - Is for logical reasons not compatible with onchange. Automatically generates javascript that submits the action it holds as its value, without the need for a submit button.
  • :name - you can optionally name your select. If you don't, ucw assigns a random string.
  • &optional - other options not needed for the <ucw:select function
• <ucw:option - Accepts any lisp object as its value.
• <ucw:integer-range-select - Has the extra options :min, :max and :step which defaults to 1. Generates a select with the options value and display name set to integers in the range of and stepped by the added keywords.
• <ucw:month-day-select - Generates a select with numbers from 1 to 31 as its values and display name. Inherits from integer-range select.
• <ucw:month-select - renders a select with the months of the year in english.

Some select examples:

(<:p "some select forms"
 (<ucw:form
  (<ucw:select :name "normal"
               :accessor (select-of forms)
               :on-change (refresh-component forms)
               (<ucw:option :value "snabbel" "bla")
               (<ucw:option :value "snibbie" "snap")))
 (<ucw:form
  (<ucw:month-day-select :name "day"
                         :accessor (select-of forms)
                         :on-change (refresh-component forms))
  (<ucw:month-select :accessor (select2-of forms)
                     :name "month"
                     :on-change (refresh-component forms))
  (<ucw:integer-range-select :min 1999 :max 2006
                             :name "bla"
                             :accessor (select3-of forms)
                             :on-change (refresh-component forms)))
 (<:ah "value of select1: " (select-of forms)) (<:br)
 (<:ah "value of select2: " (select2-of forms)) (<:br)
 (<:ah "value of select3: " (select3-of forms)))
    

Miscellaneous tags

• <ucw:render-component - Used in tal files to render a component. See the tal section.
• <ucw:script - wraps your handcrafted javascript text in <script type="javascript" .... >

Basic ucw mechanics <- back | toc | forward -> Widget Components