History | Edit

The oxy_button built-in form control is used for graphical user interface objects that invoke a custom Author mode action (defined in the associated Document Type) referencing it by its ID, or directly in the CSS.

The oxy_button form control supports the following properties:
  • actionContext - Specifies the context in which the action associated with the form control is executed. Its possible values are element (default value) and caret. If you select the element value, the context is the element that holds the form control. If you select the caret value, the action is invoked at the cursor location. If the cursor is not inside the element that holds the form control, the element value is selected automatically.
  • fontInherit - This value specifies whether or not the form control inherits its font from its parent element. The values of this property can be true or false (default value). To make the form control inherit its font from its parent element, set the fontInherit property to true.
  • color - Specifies the foreground color of the form control. If the value of the color property is inherit, the form control has the same color as the element in which it is inserted.
  • actionID - The ID of the action, specified in the document type association, that is invoked when you click the button.
    Note: The element that contains the form control represents the context where the action is invoked.
  • action - Defines an action directly, rather than using the actionID parameter to reference an action from the document type association. This property is defined using the oxy_action function.
    oxy_button(action, oxy_action(
              name, 'Insert', 
              description, 'Insert an element after the current one', 
              icon, url('insert.png'), 
              operation, 'InsertFragmentOperation', 
              arg-fragment, '<element>${caret}</element>',
              arg-insertLocation, '.',
              arg-insertPosition, 'After'
    ))
    Tip: You can also create a button form control directly from an oxy_action function.
  • action_list - Defines a sequential list of actions directly, rather than using the actionID parameter to reference actions from the document type association. This property is defined using the oxy_action_list function.
    oxy_button(
        actionContext, caret,
             actions,
             oxy_action_list(
                oxy_action(
                name, 'SB', 
                description, 'Surround fragment with multiple tags b -> i', 
                operation, 'SurroundWithFragmentOperation', 
                arg-fragment, '<b></b>'
    ),
              oxy_action(
                name, 'SI', 
                operation, 'SurroundWithFragmentOperation', 
                arg-fragment, '<i></i>'
            )
          )
    )
    Tip: When using the oxy_action_list function, the name and description of the first defined action will be what is displayed for the button. A code template is available to make it easy to add the oxy_action_list function.
  • visible - Specifies whether or not the form control is visible. The possible values of this property are true (default value) and false.
  • transparent - Flattens the aspect of the button form control, removing its border and background. The values of this property can be true or false (default value).
  • showText - Specifies if the action text should be displayed on the button form control. If this property is missing then the button displays the icon only if it is available, or the text if the icon is not available. The values of this property can be true or false.
    element {
      content: oxy_button(actionID, 'remove.attribute', showText, true);
    }
  • showIcon - Specifies if the action icon should be displayed on the button form control. If this property is missing then the button displays the icon only if it is available, or the text if the icon is not available. The values of this property can be true or false.
    element {
      content: oxy_button(actionID, 'remove.attribute', showIcon, true);
    }
  • enableInReadOnlyContext - To enable button form controls or groups of buttons form controls this property needs to be set to true. This property can be used to specify areas as read-only (by setting the -oxy-editable property to false). This is useful when you want to use an action that does not modify the context.
  • hoverPseudoclassName - Allows you to change the way an element is rendered when you hover over a form control. The value is the name of a CSS pseudo-class. When you hover over the form control, the specified pseudo-class will be set on the element that contains the form control.
    p:before {
      content: oxy_button(hoverPseudoclassName, 'showBorder')
    }
    p:showBorder {
      border: 1px solid red;
    }
Example: oxy_button Form Control
button:before {
  content: "Label:"
     oxy_button(
         /* This action is declared in the document type 
            associated with the XML document. */
         actionID, "insert.popupWithMultipleSelection");
}
Tip: To insert a sample of the oxy_button form control in a CSS file (or LESS file), invoke the Content Completion Assistant by pressing Ctrl + Space (Command + Space on OS X) and select the oxy_button code template. Also, an oxy_button_in_place_action code template is available that inserts an oxy_button function that includes an action parameter.

To see more detailed examples and more information about how form controls work in Oxygen XML Editor, see the sample files in the following directory: [OXYGEN_INSTALL_DIR]/samples/form-controls.

For more information about form controls, watch our video demonstration: