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.
- 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.
- 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%.
The following functions are for generating HTML forms :
- 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.