=head2 ui_date_input(day, month, year, day-name, month-name, year-name, [disabled?])
Returns HTML for a date-selection field, with day, month and year inputs.
-XXX
+The parameters are :
+
+=item day - Initial day of the month.
+
+=item month - Initial month of the year, indexed from 1.
+
+=item year - Initial year, four-digit.
+
+=item day-name - Name of the day input field.
+
+=item month-name - Name of the month select field.
+
+=item year-name - Name of the year input field.
+
+=item disabled - Set to 1 to disable all fields by default.
=cut
sub ui_date_input
return $rv;
}
+=head2 ui_buttons_start
+
+Returns HTML for the start of a block of action buttoms with descriptions, as
+generated by ui_buttons_row. Some example code :
+
+ print ui_buttons_start();
+ print ui_buttons_row('start.cgi', 'Start server',
+ 'Click this button to start the server process');
+ print ui_buttons_row('stop.cgi', 'Stop server',
+ 'Click this button to stop the server process');
+ print ui_buttons_end();
+
+=cut
sub ui_buttons_start
{
return &theme_ui_buttons_start(@_) if (defined(&theme_ui_buttons_start));
return "<table width=100% class='ui_buttons_table'>\n";
}
+=head2 ui_buttons_end
+
+Returns HTML for the end of a block started by ui_buttons_start.
+
+=cut
sub ui_buttons_end
{
return &theme_ui_buttons_end(@_) if (defined(&theme_ui_buttons_end));
=head2 ui_buttons_row(script, button-label, description, [hiddens], [after-submit], [before-submit])
-MISSING DOCUMENTATION
+Returns HTML for a button with a description next to it, and perhaps other
+inputs. The parameters are :
+
+=item script - CGI script that this button submits to, like start.cgi.
+
+=item button-label - Text to appear on the button.
+
+=item description - Text to appear next to the button, describing in more detail what it does.
+
+=item hiddens - HTML for hidden fields to include in the form this function generates.
+
+=item after-submit - HTML for text or inputs to appear after the submit button.
+
+=item before-submit - HTML for text or inputs to appear before the submit button.
=cut
sub ui_buttons_row
=head2 ui_buttons_hr([title])
-MISSING DOCUMENTATION
+Returns HTML for a separator row, for use inside a ui_buttons_start block.
=cut
sub ui_buttons_hr
=head2 ui_post_header([subtext])
-Returns HTML to appear directly after a standard header() call
+Returns HTML to appear directly after a standard header() call. This is never
+called directly - instead, ui_print_header calls it. But it can be overridden
+by themes.
=cut
sub ui_post_header
=head2 ui_pre_footer
-Returns HTML to appear directly before a standard footer() call
+Returns HTML to appear directly before a standard footer() call. This is never
+called directly - instead, ui_print_footer calls it. But it can be overridden
+by themes.
=cut
sub ui_pre_footer
=head2 ui_print_header(subtext, args...)
Print HTML for a header with the post-header line. The args are the same
-as those passed to header()
+as those passed to header(), defined in web-lib-funcs.pl. The exception is
+the additional subtext parameter, which is for optional HTML to display
+just below the header.
=cut
sub ui_print_header
=head2 ui_print_unbuffered_header(subtext, args...)
Like ui_print_header, but ensures that output for this page is not buffered
-or contained in a table.
+or contained in a table. This should be called by scripts that are producing
+output while performing some long-running process.
=cut
sub ui_print_unbuffered_header
=head2 ui_print_footer(args...)
Print HTML for a footer with the pre-footer line. Args are the same as those
-passed to footer()
+passed to footer().
=cut
sub ui_print_footer
=head2 ui_config_link(text, &subs)
Returns HTML for a module config link. The first non-null sub will be
-replaced with the appropriate URL.
+replaced with the appropriate URL for the module's config page.
=cut
sub ui_config_link
=head2 ui_subheading(text, ...)
-Returns HTML for a section heading
+Returns HTML for a section heading whose message is the given text strings.
=cut
sub ui_subheading
=head2 ui_links_row(&links)
Returns HTML for a row of links, like select all / invert selection / add..
+Each element of the links array ref should be an HTML fragment like :
+
+ <a href='user_form.cgi'>Create new user</a>
=cut
sub ui_links_row
=head2 ui_hidden_javascript
-Returns <script> and <style> sections for hiding functions and CSS
+Returns <script> and <style> sections for hiding functions and CSS. For
+internal use only.
=cut
sub ui_hidden_javascript
=head2 ui_hidden_start(title, name, status, thisurl)
Returns HTML for the start of a collapsible hidden section, such as for
-advanced options.
+advanced options. When clicked on, the section header will expand to display
+whatever is between this function and ui_hidden_end. The parameters are :
+
+=item title - Text for the start of this hidden section.
+
+=item name - A unique name for this section.
+
+=item status - 1 if it should be initially open, 0 if not.
+
+=item thisurl - URL of the current page. This is used by themes on devices that don't support Javascript to implement the opening and closing.
=cut
sub ui_hidden_start
=head2 ui_hidden_end(name)
-Returns HTML for the end of a hidden section
+Returns HTML for the end of a hidden section, started by ui_hidden_start.
=cut
sub ui_hidden_end
=head2 ui_hidden_table_row_start(title, name, status, thisurl)
Similar to ui_hidden_start, but for use within a table started with
-ui_table_start
+ui_table_start. I recommend against using this where possible, as it can
+be difficult for some themes to implement.
=cut
sub ui_hidden_table_row_start
=head2 ui_hidden_table_row_end(name)
-MISSING DOCUMENTATION
+Returns HTML to end a block started by ui_hidden_table_start.
=cut
sub ui_hidden_table_row_end
=head2 ui_hidden_table_start(heading, [tabletags], [cols], name, status, [&default-tds], [rightheading])
-A table with a heading and table inside, and which is collapsible
+Returns HTML for the start of a form block into which labelled inputs can
+be placed, which is collapsible by clicking on the header. Basically the same
+as ui_table_start, and must contain HTML generated by ui_table_row.
+
+The parameters are :
+
+=item heading - Text to show at the top of the form.
+
+=item tabletags - HTML attributes to put in the outer <table>, typically something like width=100%.
+
+=item cols - Desired number of columns for labels and fields. Defaults to 4, but can be 2 for forms with lots of wide inputs.
+
+=item name - A unique name for this table.
+
+=item status - Set to 1 if initially open, 0 if initially closed.
+
+=item default-tds - An optional array reference of HTML attributes for the <td> tags in each row of the table.
+
+=item right-heading - HTML to appear in the heading, aligned to the right.
=cut
sub ui_hidden_table_start
=head2 ui_hidden_table_end(name)
-Returns HTML for the end of table with hiding, as started by
-ui_hidden_table_start
+Returns HTML for the end of a form block with hiding, as started by
+ui_hidden_table_start.
=cut
sub ui_hidden_table_end
=head2 ui_tabs_start(&tabs, name, selected, show-border)
-Render a row of tabs from which one can be selected. Each tab is an array
-ref containing a name, title and link.
+Returns a row of tabs from which one can be selected, displaying HTML
+associated with that tab. The parameters are :
+
+=item tabs - An array reference of array refs, each of which contains the value and user-visible text for a tab.
+
+=item name - Name of the HTML field into which the selected tab will be placed.
+
+=item selected - Value for the tab selected by default.
+
+=item show-border - Set to 1 if there should be a border around the contents of the tabs.
+
+Example code :
+
+ @tabs = ( [ 'list', 'List services' ],
+ [ 'install', 'Install new service' ] );
+ print ui_tabs_start(\@tabs, 'mode', 'list');
+
+ print ui_tabs_start_tab('mode', 'list');
+ generate_service_list();
+ print ui_tabs_end_tab('mode', 'list');
+
+ print ui_tabs_start_tab('mode', 'install');
+ generate_install_form();
+ print ui_tabs_end_tab('mode', 'install);
+
+ print ui_tabs_end();
=cut
sub ui_tabs_start
return $rv;
}
-=head2 ui_tabs_end(border)
+=head2 ui_tabs_end(show-border)
-MISSING DOCUMENTATION
+Returns HTML to end a block started by ui_tabs_start. The show-border parameter
+must match the parameter with the same name in the start function.
=cut
sub ui_tabs_end
=head2 ui_tabs_start_tab(name, tab)
-Must be called before outputting the HTML for the named tab
+Must be called before outputting the HTML for the named tab, and returns HTML
+for the required <div> block.
=cut
sub ui_tabs_start_tab
=head2 ui_tabs_start_tabletab(name, tab)
-Behaves like ui_tabs_start_tab, but for use within a ui_table_start block
+Behaves like ui_tabs_start_tab, but for use within a ui_table_start block.
+I recommend against using this where possible, as it is difficult for themes
+to implement.
=cut
sub ui_tabs_start_tabletab
return "</table>\n".$div."<table width=100%>\n";
}
+=head2 ui_tabs_end_tab
+
+Returns HTML for the end of a block started by ui_tabs_start_tab.
+
+=cut
sub ui_tabs_end_tab
{
return &theme_ui_tabs_end_tab(@_) if (defined(&theme_ui_tabs_end_tab));
return "</div>\n";
}
+=head2 ui_tabs_end_tabletab
+
+Returns HTML for the end of a block started by ui_tabs_start_tabletab.
+
+=cut
sub ui_tabs_end_tabletab
{
return &theme_ui_tabs_end_tabletab(@_)
=head2 ui_max_text_width(width, [text-area?])
-Returns a new width for a text field, based on theme settings
+Returns a new width for a text field, based on theme settings. For internal
+use only.
=cut
sub ui_max_text_width
block of HTML when selected. &opts is an array ref to arrays containing
[ value, label, html ]
+XXX
+
=cut
sub ui_radio_selector
{