module/slib/htmlform.txi

   1 @code{(require 'html-form)}
   2
   3
   4 @defun html:atval txt
   5 Returns a string with character substitutions appropriate to
   6 send @var{txt} as an @dfn{attribute-value}.
   7 @cindex attribute-value
   8 @end defun
   9
  10 @defun html:plain txt
  11 Returns a string with character substitutions appropriate to
  12 send @var{txt} as an @dfn{plain-text}.
  13 @cindex plain-text
  14 @end defun
  15
  16 @defun html:meta name content
  17 Returns a tag of meta-information suitable for passing as the
  18 third argument to @code{html:head}.  The tag produced is @samp{<META
  19 NAME="@var{name}" CONTENT="@var{content}">}.  The string or symbol @var{name} can be
  20 @samp{author}, @samp{copyright}, @samp{keywords}, @samp{description},
  21 @samp{date}, @samp{robots}, @dots{}.
  22 @end defun
  23
  24 @defun html:http-equiv name content
  25 Returns a tag of HTTP information suitable for passing as the
  26 third argument to @code{html:head}.  The tag produced is @samp{<META
  27 HTTP-EQUIV="@var{name}" CONTENT="@var{content}">}.  The string or symbol @var{name} can be
  28 @samp{Expires}, @samp{PICS-Label}, @samp{Content-Type},
  29 @samp{Refresh}, @dots{}.
  30 @end defun
  31
  32 @defun html:meta-refresh delay uri
  33
  34
  35 @defunx html:meta-refresh delay
  36
  37 Returns a tag suitable for passing as the third argument to
  38 @code{html:head}.  If @var{uri} argument is supplied, then @var{delay} seconds after
  39 displaying the page with this tag, Netscape or IE browsers will fetch
  40 and display @var{uri}.  Otherwise, @var{delay} seconds after displaying the page with
  41 this tag, Netscape or IE browsers will fetch and redisplay this page.
  42 @end defun
  43
  44 @defun html:head title backlink tags @dots{}
  45
  46
  47 @defunx html:head title backlink
  48
  49 @defunx html:head title
  50
  51 Returns header string for an HTML page named @var{title}.  If @var{backlink} is a string,
  52 it is used verbatim between the @samp{H1} tags; otherwise @var{title} is
  53 used.  If string arguments @var{tags} ... are supplied, then they are
  54 included verbatim within the @t{<HEAD>} section.
  55 @end defun
  56
  57 @defun html:body body @dots{}
  58 Returns HTML string to end a page.
  59 @end defun
  60
  61 @defun html:pre line1 line @dots{}
  62 Returns the strings @var{line1}, @var{lines} as @dfn{PRE}formmated plain text
  63 @cindex PRE
  64 (rendered in fixed-width font).  Newlines are inserted between @var{line1},
  65 @var{lines}.  HTML tags (@samp{<tag>}) within @var{lines} will be visible verbatim.
  66 @end defun
  67
  68 @defun html:comment line1 line @dots{}
  69 Returns the strings @var{line1} as HTML comments.
  70 @end defun
  71 @section HTML Forms
  72
  73
  74 @defun html:form method action body @dots{}
  75 The symbol @var{method} is either @code{get}, @code{head}, @code{post},
  76 @code{put}, or @code{delete}.  The strings @var{body} form the body of the
  77 form.  @code{html:form} returns the HTML @dfn{form}.
  78 @cindex form
  79 @end defun
  80
  81 @defun html:hidden name value
  82 Returns HTML string which will cause @var{name}=@var{value} in form.
  83 @end defun
  84
  85 @defun html:checkbox pname default
  86 Returns HTML string for check box.
  87 @end defun
  88
  89 @defun html:text pname default size @dots{}
  90 Returns HTML string for one-line text box.
  91 @end defun
  92
  93 @defun html:text-area pname default-list
  94 Returns HTML string for multi-line text box.
  95 @end defun
  96
  97 @defun html:select pname arity default-list foreign-values
  98 Returns HTML string for pull-down menu selector.
  99 @end defun
 100
 101 @defun html:buttons pname arity default-list foreign-values
 102 Returns HTML string for any-of selector.
 103 @end defun
 104
 105 @defun form:submit submit-label command
 106
 107
 108 @defunx form:submit submit-label
 109
 110 The string or symbol @var{submit-label} appears on the button which submits the form.
 111 If the optional second argument @var{command} is given, then @code{*command*=@var{command}}
 112 and @code{*button*=@var{submit-label}} are set in the query.  Otherwise,
 113 @code{*command*=@var{submit-label}} is set in the query.
 114 @end defun
 115
 116 @defun form:image submit-label image-src
 117 The @var{image-src} appears on the button which submits the form.
 118 @end defun
 119
 120 @defun form:reset
 121 Returns a string which generates a @dfn{reset} button.
 122 @cindex reset
 123 @end defun
 124
 125 @defun form:element pname arity default-list foreign-values
 126 Returns a string which generates an INPUT element for the field
 127 named @var{pname}.  The element appears in the created form with its
 128 representation determined by its @var{arity} and domain.  For domains which
 129 are foreign-keys:
 130
 131 @table @code
 132 @item single
 133 select menu
 134 @item optional
 135 select menu
 136 @item nary
 137 check boxes
 138 @item nary1
 139 check boxes
 140 @end table
 141
 142 If the foreign-key table has a field named @samp{visible-name}, then
 143 the contents of that field are the names visible to the user for
 144 those choices.  Otherwise, the foreign-key itself is visible.
 145
 146 For other types of domains:
 147
 148 @table @code
 149 @item single
 150 text area
 151 @item optional
 152 text area
 153 @item boolean
 154 check box
 155 @item nary
 156 text area
 157 @item nary1
 158 text area
 159 @end table
 160 @end defun
 161
 162 @defun form:delimited pname doc aliat arity default-list foreign-values
 163
 164
 165 Returns a HTML string for a form element embedded in a line of a
 166 delimited list.  Apply map @code{form:delimited} to the list returned by
 167 @code{command->p-specs}.
 168 @end defun
 169
 170 @defun command->p-specs rdb command-table command
 171
 172
 173 The symbol @var{command-table} names a command table in the @var{rdb} relational database.
 174 The symbol @var{command} names a key in @var{command-table}.
 175
 176 @code{command->p-specs} returns a list of lists of @var{pname}, @var{doc}, @var{aliat},
 177 @var{arity}, @var{default-list}, and @var{foreign-values}.  The
 178 returned list has one element for each parameter of command @var{command}.
 179
 180 This example demonstrates how to create a HTML-form for the @samp{build}
 181 command.
 182
 183 @example
 184 (require (in-vicinity (implementation-vicinity) "build.scm"))
 185 (call-with-output-file "buildscm.html"
 186   (lambda (port)
 187     (display
 188      (string-append
 189       (html:head 'commands)
 190       (html:body
 191        (sprintf #f "<H2>%s:</H2><BLOCKQUOTE>%s</BLOCKQUOTE>\\n"
 192                 (html:plain 'build)
 193                 (html:plain ((comtab 'get 'documentation) 'build)))
 194        (html:form
 195         'post
 196         (or "http://localhost:8081/buildscm" "/cgi-bin/build.cgi")
 197         (apply html:delimited-list
 198                (apply map form:delimited
 199                       (command->p-specs build '*commands* 'build)))
 200         (form:submit 'build)
 201         (form:reset))))
 202      port)))
 203 @end example
 204 @end defun