HTML Helper Functions
Programming for Miva Merchant involves creating a lot of menus, checkboxes, and other form elements for user input. For many years, my most-used piece of MM documentation was the page that describes the functions DrawCheckbox and DrawRadio. Somehow I could never remember the parameter order for these functions. They're just different enough that I always had to refresh my memory on which one is written which way.
Eventually, I wrote my own "HTML helper" functions, and made the parameters as consistent as I could, given the inherent differences among the various types of inputs. For each function, the name parameter, if any, comes first, followed by the value or content-holding parameter, and then the "status" parameter that determines the current state of the input, such as checked/unchecked. Some functions don't need all three of these, but the order remains the same for whichever ones are present: name, value, status. After these come less-common parameters that are only used by one or two functions. As long as I can remember "name, value, status," I can write any of these functions correctly without looking at a document to get the parameter order.
All the functions have an additional, final parameter for custom HTML attributes, such as classes or event handlers. Since these aren't used very often, I also created shortcut versions of each function, with shorter names and one less parameter.
While I was at it, I threw in a few other enhancements. I wrote functions for creating more input types such as text boxes and dropdown menus. I wrote them to pass the generated HTML code to the caller as their return value; they don't contain any MvEVAL's or in-line HTML. This makes the code more concise, and makes it easy to store the HTML in a variable for later use, or write several of the function calls into a single string expression.
The complete set of function names and parameters is:
| Long version | Short version |
|---|---|
|
Checkbox(name, value, status, attrs) RadioButton(name, value, status, attrs) Option(value, status, prompt, attrs) DropdownMenu(name, options, attrs) TextBox(name, value, rows, columns, attrs) PasswordBox(name, value, columns, attrs) |
Chkbx(name, value, status) Radio(name, value, status) Opt(value, status, prompt) Menu(name, options) TxtBx(name, value, rows, columns) PassBx(name, value, columns) |
The parameter usages are similar to the functions from the MM utility library; you should find them familiar and easy to work with.
| Parameter | Function |
|---|---|
| name | The name for the HTML form element. |
| value | The data or content that the form element will send to the server when the form is submitted. |
| status | A value that determines the current state of the form element, such as checked or unchecked. Radio-button and menu-options elements will be selected if the status parameter is equal to the value parameter. Checkbox elements will be checked if status is "true," i.e. anything other than zero or the empty string. |
| prompt | Text that is displayed to users on the menu option. |
| options | HTML code for one or more menu options, possibly created by the Option() or Opt() functions. (See example below) |
| rows | The number of rows to display for a multi-line text box (textarea). |
| columns | The number of columns (characters) to display for a text box (single-line, multi-line, or password). |
| attrs | Additional HTML attributes to be included in the form element, such as CSS classes, Javascript event handlers, etc. |
None of these functions have a parameter for an optional text caption or label, as the MM functions do. I've found with experience that I usually prefer to write the caption separately; it gives me more flexibility about the layout. Also, nowadays, the caption is likely to include a <span> or <label> tag, which will have attributes with quotes. Writing that as a function parameter requires adding another layer of quotes, with backslashes to escape the nested quotes. That's too much typing for my taste, and too many chances for a mis-typed character to produce a weird syntax error for which the compiler will give a misleading error message.
For example, writing a basic checkbox with the helper function comes out about like this:
<MvEVAL EXPR="{ Chkbx('XXXX_enabled', 1, g.XXXX_enabled) }"> Click me
If you want to add an event handler to the checkbox, you can write it with the long-form function call that has one more parameter:
<MvEVAL EXPR="{ Checkbox('XXXX_enabled', 1, g.XXXX_enabled, 'onclick=\"DoSomethingWith(this);\"') }">
Here's another example of using these functions to simplify coding, in this case for a dropdown menu:
<MvEVAL EXPR="{ Menu('XXXX_color',
Opt('R', g.XXXX_color, 'Red') $ Opt('G', g.XXXX_color, 'Green') $ Opt('B', g.XXXX_color, 'Blue')
) }">
I hope these functions will help you with your projects. I should mention that, although I've been using them for some time, I haven't tested them exhaustively; there may still be a few bugs to be found.