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="...">