| | 1 | [wiki:IntroBasicMechanics Basic ucw mechanics <- back] | [wiki:UcwIntro toc] | [wiki:IntroWidgetComponents forward -> Widget Components] |
| | 2 | |
| | 3 | {{{ |
| | 4 | #!html |
| | 5 | |
| | 6 | <h2>Yaclml tags</h2> |
| | 7 | <p>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.</p> |
| | 8 | <h4>standard yaclml tags</h4> |
| | 9 | <p>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> |
| | 10 | <pre> |
| | 11 | (<:p :class "a-class" "bla bla") |
| | 12 | </pre> |
| | 13 | <p>The "<" is really a nickname for the yaclml package, and p is a macro in the package. </p> |
| | 14 | <p>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.</p> |
| | 15 | <h4>extended yaclml tags</h4> |
| | 16 | <p>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.</p> |
| | 17 | <p>The extra functionality comes from the extra keywords you can pass them: :action, :accessor, :reader and writer. The macro's can handle |
| | 18 | one or more of these, depending on the macro, but the keywords are mutually exclusive. With the :action keyword you can specify an action |
| | 19 | 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 |
| | 20 | initial value of the specified tag. If the tag returns a value, the place will store it. :reader and :writer are used as a |
| | 21 | team to provide more flexibility than :accessor does. If provided, the value of :reader is used as the initial value of |
| | 22 | place. The value of writer should be a function which accepts one argument: the value returned by the tag.</p> |
| | 23 | <p>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.</p> |
| | 24 | <h5>special form tags</h5> |
| | 25 | <p>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.</p> |
| | 26 | <p>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.</p> |
| | 27 | <h5>Select fields</h5> |
| | 28 | <p>The html select tag knows quite a few incarnations in ucw. A roundup:</p> |
| | 29 | <ul> |
| | 30 | <li><:select - works just like a html <select>. Accepts all of <select>s attributes.</li> |
| | 31 | <li><:option - works just like an html <option>. Accepts all of <options>s attributes.</li> |
| | 32 | <li><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: |
| | 33 | |
| | 34 | <ul> |
| | 35 | <li>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.</li> |
| | 36 | <li>:test - a test function to compare values. Defaults to eql</li> |
| | 37 | <li>:key - a key which defaults to identity</li> |
| | 38 | <li>: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.</li> |
| | 39 | <li>:name - you can optionally name your select. If you don't, ucw assigns a random string.</li> |
| | 40 | <li>&optional - other options not needed for the <ucw:select function</li> |
| | 41 | </ul> |
| | 42 | </li> |
| | 43 | <li><ucw:option - Accepts any lisp object as its value.</li> |
| | 44 | <li><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.</li> |
| | 45 | <li><ucw:month-day-select - Generates a select with numbers from 1 to 31 as its values and display name. Inherits from integer-range select.</li> |
| | 46 | <li><ucw:month-select - renders a select with the months of the year in english.</li> |
| | 47 | </ul> |
| | 48 | <p>Some select examples:</p> |
| | 49 | <pre> |
| | 50 | (<:p "some select forms" |
| | 51 | (<ucw:form |
| | 52 | (<ucw:select :name "normal" |
| | 53 | :accessor (select-of forms) |
| | 54 | :on-change (refresh-component forms) |
| | 55 | (<ucw:option :value "snabbel" "bla") |
| | 56 | (<ucw:option :value "snibbie" "snap"))) |
| | 57 | (<ucw:form |
| | 58 | (<ucw:month-day-select :name "day" |
| | 59 | :accessor (select-of forms) |
| | 60 | :on-change (refresh-component forms)) |
| | 61 | (<ucw:month-select :accessor (select2-of forms) |
| | 62 | :name "month" |
| | 63 | :on-change (refresh-component forms)) |
| | 64 | (<ucw:integer-range-select :min 1999 :max 2006 |
| | 65 | :name "bla" |
| | 66 | :accessor (select3-of forms) |
| | 67 | :on-change (refresh-component forms))) |
| | 68 | (<:ah "value of select1: " (select-of forms)) (<:br) |
| | 69 | (<:ah "value of select2: " (select2-of forms)) (<:br) |
| | 70 | (<:ah "value of select3: " (select3-of forms))) |
| | 71 | </pre> |
| | 72 | <h5>Miscellaneous tags</h5> |
| | 73 | <ul> |
| | 74 | <li><ucw:render-component - Used in tal files to render a component. See the tal section.</li> |
| | 75 | <li><ucw:script - wraps your handcrafted javascript text in <script type="javascript" .... > </li> |
| | 76 | </ul> |
| | 77 | |
| | 78 | }}} |
| | 79 | |
| | 80 | [wiki:IntroBasicMechanics Basic ucw mechanics <- back] | [wiki:UcwIntro toc] | [wiki:IntroWidgetComponents forward -> Widget Components] |
