Plasma GitLab Archive
Projects Blog Knowledge


[UP]
The UI language
 ui:a
 ui:alist-value and ui:alist-item
 ui:application
 ui:button
 ui:checkbox
 ui:cond
 ui:context
 ui:default
 ui:dialog
 ui:dyn-enum-value and ui:dyn-enum-item
 ui:dynamic
 ui:encode
 ui:enum-value and ui:enum-item
 ui:enumerate
 ui:enumeration and ui:enum
 ui:false
 ui:file
 ui:form
 ui:if
 ui:ifexpr
 ui:iflang
 ui:ifvar
 ui:imagebutton
 ui:iter-*
 ui:iterate
 ui:page
 ui:param
 ui:popup
 ui:radio
 ui:richbutton
 ui:select
 ui:server-popup
 ui:special
 ui:string-value
 ui:template
 ui:text and ui:password
 ui:textarea
 ui:translate
 ui:true
 ui:use
 ui:variable
 t:*, q:*, and p:*
 l:*
 $param
 $[expr]
 Dot notation (v1.v2)
   
The element ui:file

The ui:file element displays a file upload widget. The generated HTML output consists of an INPUT element with TYPE=FILE whose name attribute is set to a special identifier which is recognized by the system when the form is submitted.

The name of the ui:file box is specified by the name attribute. The dialog object provides access methods to find out whether a file has been uploaded, and if yes, where it is stored. The file is a temporary file being automatically deleted after the handle callback method has returned to the caller. It is allowed to move the file away to a different location in the filesystem. An example:

<ui:dialog name="sample" start-page="sample_page">
  <ui:page name="sample_page">
    <html>
      <body>
        <ui:file name="my_upload"/>
        <ui:button label="OK" name="ok"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>
The corresponding code of the handle method - O'Caml:

method handle() =
  match self # event with
    Button "ok" ->
      (* Somebody pressed "OK", so we check if there is an uploaded file: *)
      ( match self # lookup_uploaded_file "my_upload" with
          None ->
            (* No file! *)
            ...
        | Some arg ->
            (* There is a file encoded as arg : Netcgi_types.cgi_argument. 
             * See the documentation of the Netcgi_types module contained 
             * in the netstring/ocamlnet package for details.
             *)
          ( match arg # representation with
              `Memory -> assert false        (* Impossible case *)
            | `File filename ->
                (* "filename" is the file where the contents of the uploaded
                 * file are currently stored. For example:
                 *)
                Sys.rename filename "/other/location";
          )
      )
  | ... ->
      (* Other cases. You need not to check whether there is a temporary
       * upload file to delete, as this is done automatically.
       *)
Here is the same as Perl code:

sub handle {
    my ($self) = @_;
    my ($e, $name) = $self->event();
    if ($e eq 'BUTTON' && $name eq 'ok') {
        # Somebody pressed "OK", so we check if there is an uploaded file:
        my ($username, $mimetype, $filename) = $self->uploaded_file("my_upload");
        if ($filename eq '') {
            # No file!
            ...
        } else {
            # $filename is the file where the contents of the uploaded
            # file are currently stored. For example:
            rename($filename, "/other/location");
        }
    } elsif (...) {
        # Other cases. You need not to check whether there is a temporary
        # upload file to delete, as this is done automatically.
        ...
    }
Declaration

Level: Generative

<!ELEMENT ui:file EMPTY>
<!ATTLIST ui:file
          name     NMTOKEN     #REQUIRED
          cgi     (auto|keep)  "auto"
>
Additionally, ui:file must only occur inside ui:form.
Attributes

  • name: Specifies the name of the file upload widget.

  • cgi: The value "auto" means that the name of the CGI variable associated with the widget is selected automatically. This works perfectly unless you want to refer to this variable from Javascript or from some other manually written event decoder. The value "keep" causes that the name of the CGI variable is predictable: it is upload_ concatenated with the name of the widget. In this case the widget name should only contain alphanumeric characters, because not all punctuation characters can be safely transported over the CGI protocol.

If there are any other attributes, these are added to the generated INPUT HTML element. However, there is rarely an application for this possibility.

Sub elements

ui:file does not have sub element.

Generated HTML code

The ui:file element generates HTML code which roughly looks as follows:

<input type="FILE" name="...">
This web site is published by Informatikbüro Gerd Stolpmann
Powered by Caml