Documentation

Creating button via JavaScript API

Start

Library ui.buttons allows creating buttons not only by layout, but via JavaScript API.

Connecting at the page

\Bitrix\Main\UI\Extension::load("ui.buttons");

hello, button!

To show button at the page, create an object BX.UI.Button and call the method renderTo.

<div id="container"></div>

<script>
(function() {
	var button = new BX.UI.Button({ text: "Hello, button!" });
	var container = document.getElementById("container");
    button.renderTo(container);
})();
</script>

Method getContainer returns link to DOM button element. Use it for flexible interface building.

var button = new BX.UI.Button({ text: "Hello, button!" });
var layout = BX.create("div", {
	props: {
		className: "container"
	},
	children: [button.getContainer()]
});

Dimensions

Button dimension is specified by the option size with enumerated BX.UI.Button.Size.

var button = new BX.UI.Button({
	text: "Hello, button!",
	size: BX.UI.Button.Size.LARGE
});

Available BX.UI.Button.Size values:

  • BX.UI.Button.Size.LARGE — large button (47px)
  • BX.UI.Button.Size.MEDIUM — medium button (39px), default value
  • BX.UI.Button.Size.SMALL — small button (33px)
  • BX.UI.Button.Size.EXTRA_SMALL — maximum small button (26px)

Colors

Option color is responsible for button color. This option is defined by enumeration BX.UI.Button.Color.

var button = new BX.UI.Button({
	text: "Hello, button!",
	color: BX.UI.Button.Color.SUCCESS
});

Available BX.UI.Button.Color: values:

  • BX.UI.Button.Color.DANGER
  • BX.UI.Button.Color.DANGER_DARK
  • BX.UI.Button.Color.DANGER_LIGHT
  • BX.UI.Button.Color.SUCCESS
  • BX.UI.Button.Color.SUCCESS_LIGHT
  • BX.UI.Button.Color.PRIMARY_DARK
  • BX.UI.Button.Color.PRIMARY
  • BX.UI.Button.Color.SECONDARY
  • BX.UI.Button.Color.LINK
  • BX.UI.Button.Color.LIGHT
  • BX.UI.Button.Color.LIGHT_BORDER

Statuses

Button can have a status. For example, it can be active or blocked. Option state and enumeration BX.UI.Button.State manage this feature.

var button = new BX.UI.Button({
	text: "Hello, button!",
	state: BX.UI.Button.State.DISABLED
});

Available BX.UI.Button.State values:

  • BX.UI.Button.State.HOVER — status when hovered on by a mouse
  • BX.UI.Button.State.ACTIVE — status when clicked
  • BX.UI.Button.State.DISABLED — blocked
  • BX.UI.Button.State.CLOCKING — standby as a "ticking timer"
  • BX.UI.Button.State.WAITING — standby as a "spinner"

Button tag

Button by default is displayed via the tag <button>. Parameter tag and enumeration BX.UI.Button.Tag are used to convert button into a link or input element.

var button = new BX.UI.Button({
	text: "Hello, button!",
	tag: BX.UI.Button.Tag.LINK
});

Available BX.UI.Button.Tag values:

  • BX.UI.Button.Tag.BUTTON — tag <button>
  • BX.UI.Button.Tag.LINK — tag <a>
  • BX.UI.Button.Tag.SUBMIT — tag <input type="submit">
  • BX.UI.Button.Tag.INPUT — tag <input type="button">

Icon

To create buttons with icon, use the parameter icon and enumeration BX.UI.Button.Icon.

var button = new BX.UI.Button({
	text: "Hello, button!",
	icon: BX.UI.Button.Icon.INFO
});

Available BX.UI.Button.Icon values:

  • BX.UI.Button.Icon.UNFOLLOW
  • BX.UI.Button.Icon.FOLLOW
  • BX.UI.Button.Icon.ADD
  • BX.UI.Button.Icon.STOP
  • BX.UI.Button.Icon.START
  • BX.UI.Button.Icon.ADD_FOLDER
  • BX.UI.Button.Icon.PAUSE
  • BX.UI.Button.Icon.SETTING
  • BX.UI.Button.Icon.TASK
  • BX.UI.Button.Icon.INFO
  • BX.UI.Button.Icon.SEARCH
  • BX.UI.Button.Icon.PRINT
  • BX.UI.Button.Icon.LIST
  • BX.UI.Button.Icon.BUSINESS
  • BX.UI.Button.Icon.BUSINESS_CONFIRM
  • BX.UI.Button.Icon.BUSINESS_WARNING
  • BX.UI.Button.Icon.CAMERA
  • BX.UI.Button.Icon.PHONE_UP
  • BX.UI.Button.Icon.PHONE_DOWN
  • BX.UI.Button.Icon.BACK

HTML attributes

Option props allows installing arbitrary button HTML attributes. For example, href for button0link or data-attributes.

var button = new BX.UI.Button({
	text: "Connect",
	size: BX.UI.Button.Size.LARGE,
	tag: BX.UI.Button.Tag.LINK,
	color: BX.UI.Button.Color.LIGHT_BORDER,
	props: {
		href: "/",
		id: "my-link-id",
		"data-role": "action"
	}
});

Also, your own CSS modifier class is available.

var button = new BX.UI.Button({
	text: "Connect",
	className: "my-button"
});

Event handling

The button's main purpose is to execute a specific action after button is clicked. When button is a link, requires only the attribute href (see. example above). In the rest of cases, requires a specified click handler in the parameter onclick.

var button = new BX.UI.Button({
	text: "Activate",
	size: BX.UI.Button.Size.LARGE,
	color: BX.UI.Button.Color.SUCCESS,
	onclick: function(button, event) {
		if (button.isActive())
		{
			button.setText("Activate");
			button.setActive(false);
		}
		else
		{
			button.setText("Deactivate");
			button.setActive();
		}
	}
});

Handler receives two arguments: button button object (class instance BX.UI.Button) and a mouse click object event.

To set other browser events, use the option events.

var button = new BX.UI.Button({
	text: "Click me",
	size: BX.UI.Button.Size.LARGE,
	color: BX.UI.Button.Color.SUCCESS,
	events: {
		click: function(button, event) {
			button.setActive(!button.isActive());
			console.log("click", button, event);
		},
		mouseenter: function(button, event) {
			console.log("mouseenter", button, event);
		},
		mouseout: function(button, event) {
			console.log("mouseout", button, event);
		}
	}
});

Round-shape button

Set the parameter round as true to create a round button.

var button = new BX.UI.Button({
	text: "Round shape button",
	color: BX.UI.Button.Color.PRIMARY,
	round: true
});

Capital letters

Button text is capitalized by default. Option noCaps=true allows cancelling this behavior.

var button = new BX.UI.Button({
	text: "Standard text",
	color: BX.UI.Button.Color.SUCCESS,
	noCaps: true
});

Dropdown button

Option dropdown=true adds an icon as a pointer next to the button text on the right side. Such appearance shows menu after clicking.

var button = new BX.UI.Button({
	text: "Dropdown",
	color: BX.UI.Button.Color.PRIMARY,
	dropdown: true
});

Menu

One of standard scenarios for button use is to show context menu after clicking. Parameter menu defines the same settings as the class BX.PopupMenuWindow. The button automatically becomes active after opening the menu and becomes inactive after the menu is closed.

var button = new BX.UI.Button({
	text: "Menu",
	color: BX.UI.Button.Color.PRIMARY,
	dropdown: true,
	menu: {
		items: [
			{ text: "Detail description", href: "/path/to/page" },
			{ text: "Edit", disabled: true },
			{
				text: "Move",
				onclick: function(event, item) {
					alert("Item click processing");
				}
			},
			{ delimiter: true },
			{
				text: "Close",
				onclick: function(event, item) {
					item.getMenuWindow().close();
				}
			}
		],
		closeByEsc: true,
		offsetTop: 5,
	},
});

Split button

To create a split button, use the button BX.UI.SplitButton. Its descended from class BX.UI.Button, that's why dimensions, colors and icons settings correspond to standard button settings.

var splitButton = new BX.UI.SplitButton({
	text: "Add",
	color: BX.UI.Button.Color.PRIMARY,
	size: BX.UI.Button.Size.LARGE,
	icon: BX.UI.Button.Icon.BUSINESS
});

However, the split button is defined by enumeration BX.UI.SplitButton.State.

var splitButton = new BX.UI.SplitButton({
	text: "Add",
	color: BX.UI.Button.Color.PRIMARY,
	size: BX.UI.Button.Size.LARGE,
	icon: BX.UI.Button.Icon.BUSINESS,
	state: BX.UI.SplitButton.State.MENU_ACTIVE
});

Available values BX.UI.SplitButton.State:

  • BX.UI.SplitButton.State.HOVER
  • BX.UI.SplitButton.State.MAIN_HOVER
  • BX.UI.SplitButton.State.MENU_HOVER
  • BX.UI.SplitButton.State.ACTIVE
  • BX.UI.SplitButton.State.MAIN_ACTIVE
  • BX.UI.SplitButton.State.MENU_ACTIVE
  • BX.UI.SplitButton.State.DISABLED
  • BX.UI.SplitButton.State.MAIN_DISABLED
  • BX.UI.SplitButton.State.MENU_DISABLED
  • BX.UI.SplitButton.State.CLOCKING
  • BX.UI.SplitButton.State.WAITING

Parameters can be specified for both target button as well as its components. The options mainButton and menuButton are define individual settings for main and additional button.

var splitButton = new BX.UI.SplitButton({
	text: "Add",
	color: BX.UI.Button.Color.PRIMARY,
	size: BX.UI.Button.Size.LARGE,
	icon: BX.UI.Button.Icon.BUSINESS,
	mainButton: {
		props: {
			href: "/"
		},

		tag: BX.UI.Button.Tag.LINK
	},

	menuButton: {
		onclick: function(button, event) {
			button.setActive(!button.isActive());
		},

		props: {
			"data-abc": "123"
		},

		events: {
			mouseenter: function(button, event) {
				console.log("menu button mouseenter", button, event);
			}
		},
	},
});

Event handlers in the first argument get the class object BX.UI.SplitSubButton.

Standard buttons

Standard button types "Save", "Apply", "Cancel" and etc. have helper classes. These classes pre-set button's color and text.

Helper classes of the standard button (descendants of BX.UI.Button):

  • BX.UI.SaveButton
  • BX.UI.CreateButton
  • BX.UI.AddButton
  • BX.UI.SendButton
  • BX.UI.ApplyButton
  • BX.UI.CancelButton
  • BX.UI.CloseButton

Helper classes for split buttons (descendants of BX.UI.SplitButton):

  • BX.UI.SaveSplitButton
  • BX.UI.CreateSplitButton
  • BX.UI.AddSplitButton
  • BX.UI.SendSplitButton
  • BX.UI.ApplySplitButton
  • BX.UI.CancelSplitButton
  • BX.UI.CloseSplitButton

Any preset value can be re-defined.

var button = new BX.UI.SaveButton({
	color: BX.UI.Button.Color.PRIMARY
});


© «Bitrix24», 2001-2024
Up