| new_ml_form - monolith form widget |
#include <ml_form.h> ml_form new_ml_form (pool pool); |
| A monolith form widget is a low-level widget for handling input of text fields, check buttons, radio buttons and so on, collected together into a single form on a page. |
| A form should contain a mixture of input widgets and ordinary widgets. Since the form widget itself can only be packed with a single widget, normally you would pack a layout widget directly into the form, and then a mixture of labels and input widgets into the layout widget. |
| One or more of the widgets packed into the form can be a submit button (see new_ml_form_submit(3)). Pressing on the submit button causes the form's callback function to be called, and in this function the values entered into the other input widgets can be read. It is recommended that all forms contain at least one submit button, because the effect of creating a form with no submit buttons is browser-dependent, and can mean that the form cannot be submitted. |
| Forms cannot be nested (a form widget cannot contain another form widget inside itself). This is a limitation of HTML. |
| Forms are low-level entities. To do seriously interesting things with forms such as self-validation, use one of the higher-level form-type abstractions that monolith provides (XXX will provide, not now - RWMJ). |
| new_ml_form creates a new form widget. |
| ml_form_set_callback sets the callback function which is called when the form is submitted. The callback function is invoked as void callback_fn (ml_session session, void *data). The values that the user entered in the input fields are available by calling (for example) ml_form_input_get_value(3) on each input widget within the form. |
| ml_form_pack packs a widget into the form. A form can only store a single widget, so if you call pack subsequent times, the earlier widgets are forgotten. |
| Richard Jones <rich@annexia.org> |
| GNU LGPL (see http://www.gnu.org/) |
| monolith-1.0.0 |
| new_ml_form_input(3), new_ml_form_textarea(3), new_ml_form_submit(3). |