close Warning: Can't synchronize with repository "(default)" (/project/ucw/svn does not appear to be a Subversion repository.). Look in the Trac log for more information.

Changes between Initial Version and Version 1 of IntroYaclmlTags

07/25/06 11:21:54 (9 years ago)



  • IntroYaclmlTags

    v1 v1  
     1[wiki:IntroBasicMechanics Basic ucw mechanics <- back] | [wiki:UcwIntro toc] | [wiki:IntroWidgetComponents forward -> Widget Components]
     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(&lt;:p :class "a-class" "bla bla")
     12    </pre>
     13    <p>The "&lt;" is really a nickname for the yaclml package, and p is a macro in the package. </p>
     14    <p>You can use the &lt;:as-html (or &lt;:ah) macro and just type big slabs of html-escaped text or use &lt;:as-is (or &lt;: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 &lt;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 &lt;:simple-form. It will not play nice with &lt;ucw:submit though.</p>
     26    <p>Submit buttons also standard come with javascript code on the client side. &lt;:simple-submit provides a button without javascript which can be used with &lt;ucw:form as with &lt;:form. The great thing about this one is that the standard &lt;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>&lt;:select - works just like a html &lt;select&gt;. Accepts all of &lt;select&gt;s attributes.</li>
     31      <li>&lt;:option - works just like an html &lt;option&gt;. Accepts all of &lt;options&gt;s attributes.</li>
     32      <li>&lt;ucw:select - What's cool about this one, except for the accessor stuff you know from other &lt;ucw:bla.. accessors is that its options, when they are also foregone by &lt;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:
     34      <ul>
     35        <li>an :accessor or a :writer (not a reader since that functionality travels through the &lt;option&gt; options) - works pretty much like any other &lt;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>&amp;optional - other options not needed for the &lt;ucw:select function</li>
     41      </ul>
     42      </li>
     43      <li>&lt;ucw:option - Accepts any lisp object as its value.</li>
     44      <li>&lt;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>&lt;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>&lt;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(&lt;:p "some select forms"
     51 (&lt;ucw:form
     52  (&lt;ucw:select :name "normal"
     53               :accessor (select-of forms)
     54               :on-change (refresh-component forms)
     55               (&lt;ucw:option :value "snabbel" "bla")
     56               (&lt;ucw:option :value "snibbie" "snap")))
     57 (&lt;ucw:form
     58  (&lt;ucw:month-day-select :name "day"
     59                         :accessor (select-of forms)
     60                         :on-change (refresh-component forms))
     61  (&lt;ucw:month-select :accessor (select2-of forms)
     62                     :name "month"
     63                     :on-change (refresh-component forms))
     64  (&lt;ucw:integer-range-select :min 1999 :max 2006
     65                             :name "bla"
     66                             :accessor (select3-of forms)
     67                             :on-change (refresh-component forms)))
     68 (&lt;:ah "value of select1: " (select-of forms)) (&lt;:br)
     69 (&lt;:ah "value of select2: " (select2-of forms)) (&lt;:br)
     70 (&lt;:ah "value of select3: " (select3-of forms)))
     71    </pre>
     72    <h5>Miscellaneous tags</h5>
     73    <ul>
     74      <li>&lt;ucw:render-component - Used in tal files to render a component. See the tal section.</li>
     75      <li>&lt;ucw:script - wraps your handcrafted javascript text in &lt;script type="javascript" .... &gt; </li>
     76    </ul>
     80[wiki:IntroBasicMechanics Basic ucw mechanics <- back] | [wiki:UcwIntro toc] | [wiki:IntroWidgetComponents forward -> Widget Components]