jZed has asked for the wisdom of the Perl Monks concerning the following question:

I need to create a text describing an online survey that can be easily edited by non-techies. I'd like to autogenerate the text into an HTML survey form but the process is applicable to all forms. I've attached my first ideas below. Is there something else out there like it? Perhaps part of some wiki markup? If not, please comment on the markup I've sketched out below.

update thanks to Fletch and Scooterm I've clarified my goals a bit, please see my reply below that has some goal clarifications

Name : ??? CGI::FormBuilder::Text2Form ???

Purpose : Allow a lightly marked up text file to be autogenerated into an HTML survey form. Markup will be parsed and fed into (probably) CGI::FormBuilder

Sample Input file: 

 %%start     action="/somepath/foobar-survey.cgi"
 %%text      Name %% 30
 %%radio     Gender %% Male %% Female
 %%checkbox  Location %% Heaven %% Hell %% Purgatory
 %%popup     Occupation %% Student %% Flunky %% Other
 %%textarea  Complaints(Please list your complaints here.) %% 60 %% 4
 %%end
These could be intersperced with pod lines - lines that start with %% would be interpreted as form markup, other lines would be interpreted as pod (i.e. flush left would be wrapped and interpolated and indented would be verbatim)

Quick Guide to markup 

     %%start     $start_form_attributs
     %%text      $name %% $width
     %%textarea  $name %% $width %% height
     %%radio     $name %% $value1 %% $value2 ... %% $valueN
     %%checkbox  same as radio
     %%popup     same as radio
     %%submit    $name
     %%end

     $name    - the name of the field
     $value   - value of a radio, checkbox or popup item
     $width   - width of a text field or area
     $height  - height of a text field or area

     Labels and prompts will be created from $name and $value unless
     you put a label/prompt in parentheses after $name or $value.
     For example:

	 %%text City

     Will create a textfield with "City" as both the field name
     and the label/prompt.

	 %%text fname (Please enter your First Name)

     Will create a textfield with the name "fname" and the prompt as
     shown in the parentheses.
  • Comment on Generating an HTML survey form from simple markup

Replies are listed 'Best First'.
Re: Generating an HTML survey form from simple markup
by Fletch (Bishop) on Feb 03, 2005 at 16:54 UTC

    o/` What the world needs now / is another Perl Templating module / like I need a hole in my head o/`

    I'd either use one of the plethora of existing templating modules (TT2 or what not) to define your survey markup, or if you're looking for something more programmatic then use YAML as the format, let it do the heavy lifting for the parsing, and then run over the structure that produces making calls to CGI::FormBuilder. 

    action: /somepath/survey.cgi
fields:
  - type: text
    name: Name
    width: 30
  - type: radio
    name: Gender
    choices: [ Male, Female ]

    [download]

    (Now I have to go hide before Bob Mould's Cracker's lawyers come to beat me up . . .)

    Update: Tweaked the YAML formatting. And I misremembered the lyric reference (Sugar, Cracker, tomayto, tomahto)

[reply]
[d/l]
      Yes, for sure, templating modules will be used. If this is a front end for CGI::FormBuilder, it can send it's output to HTML::Template, Text::Template, etc. My module shouldn't mess with presentation *at all*.

      Yes, I considered YAML, but compare the legibility of your example to mine. Too much typing!

[reply]
        Yes, I considered YAML, but compare the legibility of your example to mine. Too much typing!

        But the YAML is self documenting. You can tell exactly what each parameter that's being set; with positional parameters you have to remember the right order. If that's too chatty for you you could still use positional parameters and let YAML parse it. 

        action: '/somepath/foo.cgi'
fields:
  - [ text, name, "Your name:" ]
  - [ radio, gender, Male, Female ]
  - [ textarea, complaints, "Enter your complaints here", 80, 24 ]

        [download]
[reply]
[d/l]
Re: Generating an HTML survey form from simple markup
by dimar (Curate) on Feb 03, 2005 at 17:54 UTC
    I need to create a text describing an online survey that can be easily edited by non-techies.

    I know you have probably already considered these issues jZed, but just for the sake of posterity:

    Use YAML (and/or another pre-existing well-known syntax)

    Thanks to YAML, there are now no more mini-syntaxes left to be invented. That's right, people, move along, there's nothing left do be done here, please clear the area.

    Avoid The Perils of Positional Attributes

    I offer no empirical data to back this up, but 'non-techies' and the keystroke-saving 'positional attributes' do not mix well. Why? Because generally: 1) non-techies are not going to read your mini syntax "cheatsheet" (although to your credit at least you provided one); 2) Those who do read your cheatsheet will not remember the parameters long enough to reliably put them in the right order; 3) The time they save in typing will be lost in the time it takes for them to: (a) repeatedly go back to you and ask where the cheatsheet is saved, or (b) pawn the work off on someone else down the line who is even *less* familiar with the project; AND 4) When the non-techies ask for "just one more feature" (and they will) you will have to (a) rewrite your cheatsheet, and (b) remember not to mess up the positional ordering (*headaches*)

    I realize a lot of this is personal stylistic preference (which is why there are so many 'mini syntaxes' out there), but really ... learning the new 'mini syntax of the day' just gets old fast, non-techie or not.

    By the way, personal experience has shown you may want to distinguish "$name" from "$caption" (i.e., the name of the field versus the on-screen "FriendlyName" that the users see.)

    ### YAML+XML Variant1 (no positional attributes, self 
### documenting and "extensible")
###
form_submit: action="/somepath/foobar-survey.cgi"
form_body: | 
    <input type="text" name="xxx" width="22" />
    <input type="radio" name="xxx" value1="foo" />
    <input type="textarea" name="xxx" width="22" height="11" />

### YAML+XML Variant2 if you absolutely insist on
### positional attributes and less typing
###
form_submit: action="/somepath/foobar-survey.cgi"
form_body: | 
    <!-- form for foobar-survey 2005-02-02 -->
    <text     props="name ;; 22" />
    <radio    props="name ;; foo ;; fee ;; faa" />
    <textarea props="name ;; Say Something ;; 60 ;; 4 " />

    [download]

    Mixing YAML and XML is surely unappealing, but it gets the job done, no new mini syntaxes were invented, and if you dont like it you can replace it with something else. Plus, using this style we get comments for free.

    Update YAML+XML is mostly a kludge offered as a crutch for the "non-techies" who are (likely) already familiar with HTML, to which the XML looks similar. YAML can do all this by itself. Some points in this node were de-emphasized elsewhere in the thread.
[reply]
[d/l]
      Excellent points, thanks. I guess I mis-stated my goal. It is a) for me to be able to quickly write up a survey using pod markup for the non-form parts and the quickest possible and most legible but non-interfering markup for the form parts and b) for non-techies to be able to read the text file without even needing to see the cheatsheet.

      The idea is much more like pod than like YAML - non-techies should be able to just read it, ignoring the =head1, etc.

      Maybe the "another markup" thing is a reason for me to just use the module myself rather than CPAN it.

[reply]
Re: Generating an HTML survey form from simple markup
by ikegami (Patriarch) on Feb 03, 2005 at 16:57 UTC
    %%start     action="/somepath/foobar-survey.cgi"
    is "techie". Why not use
    %%action     /somepath/foobar-survey.cgi
[reply]
[d/l]
[select]

Back to Seekers of Perl Wisdom