User Interface Functions

The functions listed in this section are defined in the library ui-lib.pl, which is included with Webmin versions 1.130 and above. They are designed to make the creation of pages, forms and input fields easier, so that module developers do not have to manually generate as much HTML.

Developers writing modules for Webmin versions above 1.130 should make use of these functions where possible. This ensures consistency between modules, and allows themes to change the appearance of Webmin in more detail. In particular, the ui_print_header and ui_print_footer functions should be called instead of header and footer, as they allow a theme to supress the <hr> lines that normally appear below the title and above the footer.

All of the functions in ui-lib.pl can be over-ridden by a theme, by simply defining a function with the same name with theme_ prepended in the theme's functions file. This function will called with the same parameters, and must return compatible HTML.

The following functions can be used to generate a table of input elements, as is used in many Webmin forms :

    ui_table_start(heading, [tabletags], [cols])
    Returns HTML for a table with the given heading, as used on the editing pages of most Webmin modules. The optional tabletags parameter can be used to specify extra attributes for the <table> tag, like width=100%. The cols parameter defines the number of columns inside the table, which defaults to 4.

    ui_table_end()
    Returns HTML to finish a table started by ui_table_start.

    ui_table_row(label, input, [cols], [&td-tags])
    Returns HTML for a pair of cells containing the label and input, within a table started by the ui_table_start function. The optional cols parameter can be used to specify that the second cell spans multiple columns. The optional td-tags parameter can be an array reference of extra HTML attributes to include in the <td> tags.

These functions are used for creating multi-column tables for data :
    ui_columns_start(&headings, [width-percent], [noborder], [&td-tags])
    Returns HTML for the start of a table. The headings parameter must be a reference to an array of titles for the columns in the table. The width-percent is the width of the table as a percentage of the page, to force a width other than the default. The noborder parameter can be set to 1 to turn off the table border. The td-tags parameter is an array reference of extra HTML attributes to include in the heading's <td> tags.

    ui_columns_row(&columns, [&td-tags])
    Returns HTML for some row in the table. The columns parameter must be a reference to an array of HTML to display in the actual columns, and the td-tags can be an array of extra HTML attributes to include in the row's <td> tags.

    ui_checked_columns_row(&columns, &td-tags, checkboxname, checkboxvalue)
    This function is similar to ui_columns_row, but adds an extra column at the start containing a checkbox for selecting the row. The checkboxname parameter gives the input name of the checkbox (which is typically the same for all rows), while the checkboxvalue parameter sets its value (always different for each row).

    ui_columns_end
    Returns HTML for the end of a multi-column table.

    The following functions are for generating HTML forms :

    ui_form_start(script, method)
    Returns HTML for the start of a form. The script parameter is the URL or program that the form submits to, and the method parameter is the request method for the form to use (get, port or form-data).

    ui_form_end([&buttons], [width])
    Returns HTML for the end of a form. If the optional buttons parameter is given, a row of submit buttons will be added to the end of the form. The parameter must be a reference to an array, each element of which is a array reference containing the name and label for a button. The width parameter can be used to specify the size of the table that contains these buttons, such as 100%.

These functions return HTML for various types of form input elements :
    ui_textbox(name, value, size)
    Returns a text input box named name with value as its initial contents, of size characters in width.

    ui_upload(name, size)
    Returns a file upload input box, named name and of size characters in width. These will only work properly in forms using the form-data method.

    ui_password(name, value, size)
    Like ui_textbox, but the input box displays stars instead of the actual password entered by the user.

    ui_hidden(name, value)
    Returns HTML for a form input with the specified name and value which is not visible to the user.

    ui_select(name, value, &options, [size], [multiple])
    Returns an input for selecting one or many items from a list, depending on the multiple flag. The value can either by a single scalar or an array reference, the latter case indicating that multiple items are selected by default. The options parameter must be an array reference, and each member of the array must be itself a two-element array ref. The first member of each element is the value for one option, while the second is the text to display for that option. When multiple options are being selected, the size parameter determines the number of rows in the selection list.

    ui_radio(name, value, &options)
    Returns HTML for one or more radio buttons, of which only one can be selected by the user. The name parameter determines the name of these inputs, and the value which one is initial selected. The options parameter must be an array reference, and each member of the array must be itself a two-element array ref. The first member of each element is the value for one radio button, while the second is the text to display next to that button.

    ui_yesno_radio(name, value)
    Like ui_radio, but always returns a pair of checkboxes with values 1 and 0 and names 'Yes' and 'No' respectively.

    ui_checkbox(name, value, label, selected)
    Returns a single checkbox input, named name and with value as the value to submit when it is selected. The label parameter determines the text to display next to it, and the box will be initially checked if selected is non-zero.

    ui_oneradio(name, value, label, selected)
    Like ui_checkbox, but returns a single radio button instead.

    ui_textarea(name, value, rows, cols, [wrap-mode])
    Returns HTML for a multi-line text input field, with name as its name and value as the initial value. The rows and cols parameters determine the size in characters of the text area. If the wrap-mode is specified, it can be either on, off or auto.