Date: 2004-12-30T23:30:00 Editor: DavidLeangen Wiki: Cocoon Wiki Page: CFormsMinimalExamples URL: http://wiki.apache.org/cocoon/CFormsMinimalExamples
no comment Change Log: ------------------------------------------------------------------------------ @@ -1,18 +1,19 @@ -== CForms Minimal Examples == -- TARGET-AUDIENCE: '''*beginner*''' advanced expert[[BR]] -- COCOON-RELEASES: 2.0.3, 2.0.4[[BR]] -- DOCUMENT-STATUS: '''*draft*''' reviewed released[[BR]] ----- += Page Summary = +- TARGET-AUDIENCE: users new to CForms[[BR]] +- COCOON-RELEASES: 2.1.5[[BR]] +- DOCUMENT-STATUS: draft[[BR]] +- AUTHOR: DavidLeangen[[BR]] +- AUTHOR-CONTACT: mailto:dleangen<at>canada.com[[BR]] '''Please review!!''' This page needs validation by people more experienced and knowledgeable about CForms. -=== What you will get from this page === +== What you will get from this page == This page presents a series of minimal examples for people new to CForms. The creation of this page was motivated by my own need to simplify the examples currently available for CForms. Though the current examples are rich with information, I found that they are difficult for first learning about CForms precisely because they are so rich in information. For CForm newbies, I believe that it would be easier to have more minimal examples that show each of the many concepts. -=== Your basic skills and Technical prerequisites === +== Your basic skills and Technical prerequisites == You need to have a general understanding of what Cocoon is, including: @@ -22,11 +23,104 @@ You should also have at least some general understanding of JavaScript and Java. -=== Links to other information sources === +<TODO: provide links to all these concepts> + +== Links to other information sources == + +<TODO> ---- -=== page metadata === -- AUTHOR: DavidLeangen[[BR]] -- AUTHOR-CONTACT: mailto:dleangen<at>canada.com[[BR]] -- REVIEWED-BY:[[BR]] -- REVIEWER-CONTACT:[[BR]] + += Main Content = + +== Overview == + +CForms provide a useful and relatively simple means of producing web-based forms. CForms are relatively simple to author, but there are so many concepts involved that it can be difficult for the beginner to grasp what is happening. + +=== Motivation === + +These tutorials are based on my own ongoing struggle to learn about: + + * what CForms are + * how CForms work + * how to effectively use CForms + + +=== Tutorial Structure === + +The tutorials each have a short explanation on this wiki page. The bulk of the information is provided in the form on inline comments in the actual tutorial files that are attached to this page. + +Eventually, if these tutorials are actually useful, they could be moved to the main Cocoon examples in the Cocoon distribution. + +Please update the content both on this page as well as in the attached files if there are errors or omissions. Remember that I am learning CForms myself. What I claim in the tutorials is based on deduction and reverse engineering. Hopefully, people more experienced with the inner workings of CForms will soon be able to validate these tutorials. + +== Dynamic CForms == + +=== Overview === + +The first (and for now the only) tutorial explains how to create a minimal dynamic CForm. + +By "dynamic", we mean that when the user changes a value in the form, an action will trigger an update of the form. (You'll understand better what this means when you actually see the examples.) + +=== Files === + +This tutorial contains 10 files. In alphabetical order, they are: + + 1. form.js + 2. form.xml + 3. form_success.xsp + 4. form_template.xml + 5. forms-lib.js + 7. forms-styling.xsl + 8. main.css + 9. simple-page2html.xsl + 9. sitemap.xmap + 10. welcome.xml + +==== welcome.xml ==== + +This file provides a simple welcome page to the (eventual) various tutorials. (For now there is only 1 tutorial.) + +==== sitemap.xmap ==== + +The sitemap for the tutorials. The goal is to provide a minimal sitemap to help with the comprehension of how CForms work. + +==== form.xml ==== + +This is the definition file for the sample form. + +==== form_template.xml ==== + +This is the template for our form. + +==== form.js ==== + +The flowscript is contained in this file. Control is passed to the flowscript from the sitemap. + +==== form_success.xsp ==== + +This page is displayed when the form is submitted. + +==== simple-page2html.xsl ==== + +A simple transform for the pages in this example. This will most likely be replaced by your own page transform. + +==== forms-styling.xsl ==== + +A (somewhat) minimal example of a file needed (?) for styling the form. I am still in the process of trying to figure out what is necessary and what is fluff. + +==== forms-lib.js ==== + +Required runtime javascript functions for submitting the forms. + +==== main.css ==== + +A simple css for rendering the pages. + +=== Unexplained Behaviours === + +There are a few things that I am unable to explain. Most of them are indicated by <TODO> tags in the inline comments. I mention here, however, one thing that has me puzzled. + +Although the javascript "forms-lib.js" is saved in the same directory of the other files, this form only works when the page is referenced as "resource/forms-lib.js". Nowhere in the pipeline is there a reference to "resource/*.js" or anything like it. + +Can somebody explain this to me?
