Changes between Initial Version and Version 1 of IntroYaclmlTags

07/25/06 04:21:54 (8 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]