usbutton()

The usbutton() function is a framework-independent function.

The usbutton() function decorates a plain button in a framework-independent fashion. It allows the addition of icons:

You can use this function to create a lookup button.

This function presents a regular HTML button in the look-and-feel of the current UI framework. It adds the necessary classes to the button element, and to any inner HTML needed by the UI framework.

Alternatively, it may be used to enable or disable the button, so that it is "clickable" or not "clickable".

Returns the HTML element.

Syntax

.usbutton( command )
.usbutton( options )
.usbutton(  )

command        ::= { "enable" | "disable" | "lookup" }

options        ::= { icons: icons-object }
icons-object   ::= { primary: class-list, secondary: class-list }
class-list     ::= { class class ... }

You must call .usbutton() with either a command keyword, an options struct, or no parameter at all.

Command is a string keyword that indicates how the state of the button is altered:

• "enable": enables the button (if it is in a disabled, "unclickable" state),
• "disable": disables the button (if it is in an enabled, "clickable" state),
• "lookup": alters the button so that it looks like a lookup button used for displaying lookup dialogs or lookup pages.

Options is an object with a required "icons" property. This property is a struct that can have two fields: 'primary' to denote the primary icon to be displayed in the button, and 'secondary' for a secondary icon to be displayed on a different location than the primary icon. 'Primary' is required and 'secondary' is optional.

Class-list is a string that is a space-separated list of class names that can be used to add an icon to the button.

You can call usbutton() with no parameter at all to cause USoft to add default classes as explained in Example 1 but that you do not name yourself.

Example 1

$(".SearchIcon").usbutton({icons: {primary: 'us-icon ui-icon-search'} })

If you make this call in an unload event, when the page loads, this will add a <span> child element to the DOM for each object with class SearchIcon. You can then place one or more icons and/or text labels on the button by styling this <span> element using standard CSS. For example, you can decorate the button with the search icon designated by Unicode \1F50D like so:

.us-icon.ui-icon-search::before{
    content: "\1F50D";
}

Example 2

$("#IconFolder").usbutton({icons: {primary: 'us-icon ui-icon-folder'} })

In CSS, you can now retrieve an icon from a file and place it on the button, like so:

.us-icon.ui-icon-folder{
  height: 16px;
  width: 16px;
  background-image: url(../images.folder.png) !important;
}

More examples

var $button = $("button#SearchButton");
$button.usbutton("disable");

var $button = $("button.aButton");
$button.usbutton();  // i.e., just add classes for styling

var $button = $("button#SearchButtonWithIcon");
$button.usbutton({icons: {primary: "ui-icon benchmark-icon-invoke"}});

$("button.lookup").usbutton("lookup");