Contents |
User Guide
Overview
The wijribbon widget is a UI control that looks like a toolbar. The wijribbon can be used as the full ribbon UI or as a simple ribbon UI that allows you to save screen real estate.
The following image highlights some of the main aspects of the wijribbon widget:
NOTE: This documentation pertains to the latest Wijmo release. Please check the Version Histories for an outline of new features, improvements, and changes to the Wijmo widgets.
Markup and Scripting
The following HTML element will be used to create the full ribbon UI:
<div id="ribbon" >
<ul>
<li><a href="#C1Editor1Format">Format</a></li>
<li><a href="#C1Editor1insert">Customize Tab</a></li>
</ul>
<div id="C1Editor1Format">
<ul>
<li id="actiongroup">
<button title="Save" class="wijmo-wijribbon-bigbutton" name="save">
<div class="wijmo-wijribbon-save">
</div>
<span>Save</span></button><span class="wijmo-wijribbon-list">
<button title="Undo" class="wijmo-wijribbon-undo" name="undo">
</button>
<button title="Redo" class="wijmo-wijribbon-redo" name="redo">
</button>
</span><span class="wijmo-wijribbon-list">
<button title="Preview" class="wijmo-wijribbon-preview" name="preview">
</button>
<button title="Clean up" class="wijmo-wijribbon-cleanup" name="cleanup">
</button>
</span><span class="wijmo-wijribbon-list">
<button title="Cut" class="wijmo-wijribbon-cut" name="cut">
</button>
<button title="Copy" class="wijmo-wijribbon-copy" name="copy">
</button>
<button title="Paste" class="wijmo-wijribbon-paste" name="paste">
</button>
<button title="Select All" class="wijmo-wijribbon-selectall" name="selectall">
</button>
</span>
<div>Actions</div>
<li id="fontgroup" >
<div title="Font Name" class="wijmo-wijribbon-dropdownbutton">
<button title="Font Name" name="fontname">Font Name</button>
<ul>
<li>
<input type="radio" id="C1Editor1_ctl74" name="fontname"></input><label for="C1Editor1_ctl74" name="fn1" title="Arial">Arial</label></li>
<li>
<input type="radio" id="C1Editor1_ctl76" name="fontname"></input><label for="C1Editor1_ctl76" name="fn2" title="Courier New">Courier New</label></li>
<li>
<input type="radio" id="C1Editor1_ctl78" name="fontname"></input><label for="C1Editor1_ctl78" name="fn3" title="Garamond">Garamond</label></li>
<li>
<input type="radio" id="C1Editor1_ctl80" name="fontname"></input><label for="C1Editor1_ctl80" name="fn4" title="Tahoma">Tahoma</label></li>
<li>
<input type="radio" id="C1Editor1_ctl82" name="fontname"></input><label for="C1Editor1_ctl82" name="fn5" title="Times New Roman">Times New Roman</label></li>
<li>
<input type="radio" id="C1Editor1_ctl84" name="fontname"></input><label for="C1Editor1_ctl84" name="fn6" title="Verdana">Verdana</label></li>
<li>
<input type="radio" id="C1Editor1_ctl86" name="fontname"></input><label for="C1Editor1_ctl86" name="fn7" title="Wingdings">Wingdings</label>
</li>
</ul>
</div>
<div title="Font Size" class="wijmo-wijribbon-dropdownbutton">
<button title="Font Size" name="fontsize">Font Size</button><ul>
<li>
<input type="radio" id="C1Editor1_ctl104" name="fontsize"></input><label for="C1Editor1_ctl104" name="xx-small" title="VerySmall">VerySmall</label></li>
<li>
<input type="radio" id="C1Editor1_ctl106" name="fontsize"></input><label for="C1Editor1_ctl106" name="x-small" title="Smaller">Smaller</label></li>
<li>
<input type="radio" id="C1Editor1_ctl108" name="fontsize"></input><label for="C1Editor1_ctl108" name="small" title="Small">Small</label></li>
<li>
<input type="radio" id="C1Editor1_ctl110" name="fontsize"></input><label for="C1Editor1_ctl110" name="medium" title="Medium">Medium</label></li>
<li>
<input type="radio" id="C1Editor1_ctl112" name="fontsize"></input><label for="C1Editor1_ctl112" name="large" title="Large">Large</label></li>
<li>
<input type="radio" id="C1Editor1_ctl114" name="fontsize"></input><label for="C1Editor1_ctl114" name="x-large" title="Larger">Larger</label></li>
<li>
<input type="radio" id="C1Editor1_ctl116" name="fontsize"></input><label for="C1Editor1_ctl116"name="xx-large" title="VeryLarge">VeryLarge</label></li>
<li>
<input type="radio" id="C1Editor1_ctl117" name="fontsize"></input><label for="C1Editor1_ctl117" name="40pt" title="40pt">40pt</label></li>
</ul>
</div>
<span class="wijmo-wijribbon-list">
<button title="Background Color" class="wijmo-wijribbon-bgcolor" name="backcolor">
</button>
<button title="Font Color" class="wijmo-wijribbon-color" name="fontcolor">
</button>
</span><span class="wijmo-wijribbon-list">
<input type="checkbox" id="C1Editor1_ctl133"></input><label for="C1Editor1_ctl133" name="bold" title="Bold" class="wijmo-wijribbon-bold"></label>
<input type="checkbox" id="C1Editor1_ctl134"></input><label for="C1Editor1_ctl134" name="italic" title="Italic" class="wijmo-wijribbon-italic"></label><input type="checkbox" id="C1Editor1_ctl135"></input>
<label for="C1Editor1_ctl135" name="underline" title="Underline" class="wijmo-wijribbon-underline"></label>
<input type="checkbox" id="C1Editor1_ctl136"></input><label for="C1Editor1_ctl136" name="strike" title="Strikethrough" class="wijmo-wijribbon-strike"></label>
<input type="checkbox" id="C1Editor1_ctl137"></input><label for="C1Editor1_ctl137" name="subscript" Title="Subscript" class="wijmo-wijribbon-sub"></label>
<input type="checkbox" id="C1Editor1_ctl138"></input><label for="C1Editor1_ctl138" name="superscript" title="Superscript" class="wijmo-wijribbon-sup"></label>
</span>
<span class="wijmo-wijribbon-list">
<button title="Template" class="wijmo-wijribbon-template" name="template">
</button>
</span>
<span class="wijmo-wijribbon-list">
<button title="RemoveFormat" class="wijmo-wijribbon-removeformat" name="removeformat">
</button>
</span>
<div>Font</div>
</li>
</ul>
</div>
<div id="C1Editor1insert">
<ul>
<li>
<div title="Table" class="wijmo-wijribbon-splitbutton">
<button title="customize button" name="customcommand">
Click Me
</button>
</div>
<div>customize group</div>
</li>
</ul>
</div>
Now you need to initialize the widget, which you can do by adding the following script to the project:
<script id="scriptInit" type="text/javascript">
$(document).ready(function () {
$("#ribbon").wijribbon({click: function (e, cmd) {
alert(cmd.commandName);
}
})
});
</script>
The following markup and scripting can be used to create the simple ribbon UI:
<div id="ribbon">
<button title="Background Color" class="wijmo-wijribbon-bgcolor" name="backcolor"></button>
<div title="Font Name" class="wijmo-wijribbon-dropdownbutton">
<button title="Font Name" name="fontname">Font Name</button>
<ul>
<li>
<input type="radio" id="C1Editor1_ctl74" name="fontname"></input>
<label for="C1Editor1_ctl74" name="fn1" title="Arial">Arial</label></li>
<li>
<input type="radio" id="C1Editor1_ctl76" name="fontname"></input>
<label for="C1Editor1_ctl76" name="fn2" title="Courier New">Courier New</label></li>
<li>
<input type="radio" id="C1Editor1_ctl78" name="fontname"></input>
<label for="C1Editor1_ctl78" name="fn3" title="Garamond">Garamond</label></li>
<li>
<input type="radio" id="C1Editor1_ctl80" name="fontname"></input>
<label for="C1Editor1_ctl80" name="fn4" title="Tahoma">Tahoma</label></li>
<li>
<input type="radio" id="C1Editor1_ctl82" name="fontname"></input>
<label for="C1Editor1_ctl82" name="fn5" title="Times New Roman">Times New Roman</label></li>
<li>
<input type="radio" id="C1Editor1_ctl84" name="fontname"></input>
<label for="C1Editor1_ctl84" name="fn6" title="Verdana">Verdana</label></li>
<li>
<input type="radio" id="C1Editor1_ctl86" name="fontname"></input>
<label for="C1Editor1_ctl86" name="fn7" title="Wingdings">Wingdings</label></li>
</ul>
</div>
<input type="checkbox" id="C1Editor1_ctl133"></input>
<label for="C1Editor1_ctl133" name="bold" title="Bold" class="wijmo-wijribbon-bold">
</label>
<input type="checkbox" id="C1Editor1_ctl134"></input>
<label for="C1Editor1_ctl134" name="italic" title="Italic" class="wijmo-wijribbon-italic">
</label>
<input type="checkbox" id="C1Editor1_ctl135"></input>
<label for="C1Editor1_ctl135" name="underline" title="Underline" class="wijmo-wijribbon-underline">
</label>
<input type="checkbox" id="C1Editor1_ctl136"></input>
<label for="C1Editor1_ctl136" name="strike" title="Strikethrough" class="wijmo-wijribbon-strike">
</label>
<input type="checkbox" id="C1Editor1_ctl137"></input>
<label for="C1Editor1_ctl137" name="subscript" title="Subscript" class="wijmo-wijribbon-sub">
</label>
<input type="checkbox" id="C1Editor1_ctl138"></input>
<label for="C1Editor1_ctl138" name="superscript" title="Superscript" class="wijmo-wijribbon-sup">
</label>
<input type="checkbox" id="C1Editor1_ctl999"></input>
<label for="C1Editor1_ctl999" name="blockquote" title="BlockQuote" class="wijmo-wijribbon-blockquote">
</label>
<button title="Insert Code" class="wijmo-wijribbon-code" name="insertcode">
</button>
</div>
You can also add a little CSS styling to the wijribbon. This example specifies the width and the background color of the simple wijribbon:
<style type="text/css">
#ribbon
{
width:400px;
background-color:#242122
}
</style>
Now you need to initialize the widget, which you can do by adding the following script to the project:
<script id="scriptInit" type="text/javascript">
$(document).ready(function () {
$("#ribbon").wijribbon({click: function (e, cmd) {
alert(cmd.commandName);
}
})
});
</script>
The markup and script for the full ribbon results in the following:
Quick Start
In this quick start, you'll learn how to add the Ribbon widget to an HTML project and how to customize the widget.
- Create an .html page and add links to the dependencies to your project. To do this, just link to the content delivery network (CDN) file for each project:
<!--jQuery References--> <script src="http://code.jquery.com/jquery-1.9.1.min.js" type="text/javascript"></script> <script src="http://code.jquery.com/ui/1.10.1/jquery-ui.min.js" type="text/javascript"></script> <!--Theme--> <link href="http://cdn.wijmo.com/themes/aristo/jquery-wijmo.css" rel="stylesheet" type="text/css" /> <!--Wijmo Widgets CSS--> <link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css" rel="stylesheet" type="text/css" /> <!--Wijmo Widgets JavaScript--> <script src="http://cdn.wijmo.com/jquery.wijmo-open.all.3.20131.1.min.js" type="text/javascript"></script> <script src="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.js" type="text/javascript"></script>
- You can reference the latest dependencies from the CDN at http://wijmo.com/downloads/#wijmo-cdn.
- Place the following markup within the body of the .html document:
<div id="ribbon"> </div>
- To initialize the widget, you need to add some jQuery script:
<script id="scriptInit" type="text/javascript"> $(document).ready(function () { $("#ribbon").wijribbon({click: function (e, cmd) { alert(cmd.commandName); } }) }); </script> - If you run your application now, the wijribbon will resemble the following image:
- The ribbon has none of the buttons or dropdown lists that you expect from a ribbon, yet. This widget requires more robust HTML markup than the other widgets to create the ribbon groups and items, so we'll add some additional markup between the <div> tags.
- We're starting with the markup that creates the two ribbon tabs and the first ribbon group called Actions.
<ul> <li><a href="#C1Editor1Format">Format</a></li> <li><a href="#C1Editor1insert">Customize Tab</a></li> </ul> <div id="C1Editor1Format"> <ul> <li id="actiongroup"> <button title="Save" class="wijmo-wijribbon-bigbutton" name="save"> <div class="wijmo-wijribbon-save"></div> <span>Save</span> </button> <span class="wijmo-wijribbon-list"> <button title="Undo" class="wijmo-wijribbon-undo" name="undo"></button> <button title="Redo" class="wijmo-wijribbon-redo" name="redo"></button> </span> <span class="wijmo-wijribbon-list"> <button title="Preview" class="wijmo-wijribbon-preview" name="preview"></button> <button title="Clean up" class="wijmo-wijribbon-cleanup" name="cleanup"></button> </span> <span class="wijmo-wijribbon-list"> <button title="Cut" class="wijmo-wijribbon-cut" name="cut"></button> <button title="Copy" class="wijmo-wijribbon-copy" name="copy"></button> <button title="Paste" class="wijmo-wijribbon-paste" name="paste"></button> <button title="Select All" class="wijmo-wijribbon-selectall" name="selectall"></button> </span> <div>Actions</div> </li> </ul> </div> - If you run your application now, you'll see a widget that resembles the following image:
- Next, we'll begin the markup to create the font group:
<li id="fontgroup"> <div title="Font Name" class="wijmo-wijribbon-dropdownbutton"> <button title="Font Name" name="fontname">Font Name</button><ul> <li> <input type="radio" id="C1Editor1_ctl74" name="fontname"/> <label for="C1Editor1_ctl74" name="fn1" title="Arial">Arial</label> </li> <li> <input type="radio" id="C1Editor1_ctl76" name="fontname"/> <label for="C1Editor1_ctl76" name="fn2" title="Courier New">Courier New</label> </li> <li> <input type="radio" id="C1Editor1_ctl78" name="fontname"/> <label for="C1Editor1_ctl78" name="fn3" title="Garamond">Garamond</label> </li> <li> <input type="radio" id="C1Editor1_ctl80" name="fontname"/> <label for="C1Editor1_ctl80" name="fn4" title="Tahoma">Tahoma</label> </li> <li> <input type="radio" id="C1Editor1_ctl82" name="fontname"/> <label for="C1Editor1_ctl82" name="fn5" title="Times New Roman">Times New Roman</label> </li> <li> <input type="radio" id="C1Editor1_ctl84" name="fontname"/> <label for="C1Editor1_ctl84" name="fn6" title="Verdana">Verdana</label> </li> <li> <input type="radio" id="C1Editor1_ctl86" name="fontname"/> <label for="C1Editor1_ctl86" name="fn7" title="Wingdings">Wingdings</label> </li> </ul> </div> <div title="Font Size" class="wijmo-wijribbon-dropdownbutton"> <button title="Font Size" name="fontsize">Font Size</button> <ul> <li> <input type="radio" id="C1Editor1_ctl104" name="fontsize"/> <label for="C1Editor1_ctl104" name="xx-small" title="VerySmall">VerySmall</label> </li> <li> <input type="radio" id="C1Editor1_ctl106" name="fontsize"/> <label for="C1Editor1_ctl106" name="x-small" title="Smaller">Smaller</label> </li> <li> <input type="radio" id="C1Editor1_ctl108" name="fontsize"/> <label for="C1Editor1_ctl108" name="small" title="Small">Small</label> </li> <li> <input type="radio" id="C1Editor1_ctl110" name="fontsize"/> <label for="C1Editor1_ctl110" name="medium" title="Medium">Medium</label> </li> <li> <input type="radio" id="C1Editor1_ctl112" name="fontsize"/> <label for="C1Editor1_ctl112" name="large" title="Large">Large</label> </li> <li> <input type="radio" id="C1Editor1_ctl114" name="fontsize"/> <label for="C1Editor1_ctl114" name="x-large" title="Larger">Larger</label> </li> <li> <input type="radio" id="C1Editor1_ctl116" name="fontsize"/> <label for="C1Editor1_ctl116" name="xx-large" title="VeryLarge">VeryLarge</label> </li> <li> <input type="radio" id="C1Editor1_ctl117" name="fontsize"/> <label for="C1Editor1_ctl117" name="40pt" title="40pt">40pt</label> </li> </ul> </div> - The last section of markup creates the options to edit the font:
<span class="wijmo-wijribbon-list"> <button title="Background Color" class="wijmo-wijribbon-bgcolor" name="backcolor"></button> <button title="Font Color" class="wijmo-wijribbon-color" name="fontcolor"></button> </span> <span class="wijmo-wijribbon-list"> <input type="checkbox" id="C1Editor1_ctl133"/> <label for="C1Editor1_ctl133" name="bold" title="Bold" class="wijmo-wijribbon-bold"></label> <input type="checkbox" id="C1Editor1_ctl134"/> <label for="C1Editor1_ctl134" name="italic" title="Italic" class="wijmo-wijribbon-italic"></label> <input type="checkbox" id="C1Editor1_ctl135"/> <label for="C1Editor1_ctl135" name="underline" title="Underline" class="wijmo-wijribbon-underline"></label> <input type="checkbox" id="C1Editor1_ctl136"/> <label for="C1Editor1_ctl136" name="strike" title="Strikethrough" class="wijmo-wijribbon-strike"></label> <input type="checkbox" id="C1Editor1_ctl137"/> <label for="C1Editor1_ctl137" name="subscript" title="Subscript" class="wijmo-wijribbon-sub"></label> <input type="checkbox" id="C1Editor1_ctl138"/> <label for="C1Editor1_ctl138" name="superscript" title="Superscript" class="wijmo-wijribbon-sup"></label> </span> <span class="wijmo-wijribbon-list"> <button title="Template" class="wijmo-wijribbon-template" name="template"></button> </span> <span class="wijmo-wijribbon-list"> <button title="RemoveFormat" class="wijmo-wijribbon-removeformat" name="removeformat"></button> </span> <div>Font</div> </li> </ul> </div> <div id="C1Editor1insert"> <ul> <li> <div title="Table" class="wijmo-wijribbon-splitbutton"> <button title="customize button" name="customcommand"> Click Me </button> </div> <div>customize group</div> </li> </ul> </div> </div> </div> - Note that the widget uses checkboxes, radio buttons, and buttons to create the ribbon. The full wijribbon should look as in the following image:
Now you can set up a Wijmo application and add the appropriate HTML markup and script to your application to create and call your widget.
API
Events
The following event is available in the wijribbon widget:
wijribbonClick
- The wijRibbonClick event is a function that is called when the ribbon command button is clicked.
- Parameters:
- e: the jQuery event object.
- cmd: An Object that contains all the command information of the clicked command button.
- cmd.commandName: The command name of the button.
- cmd.name: The parent name of the button which means if the drop down item is clicked, then the name specifies the command name of the drop down button. If the VeryLarge font size is clicked, then the commandName = "verylarge", and the name = "fontsize".
- Type: Function
- Default: null
- Code Example:
// Supply a function as an option:
$("#wijribbon").wijribbon({click: function(e, cmd) { } });
// Bind to the event by type:
$("#wijribbon").bind("wijribbonclick", function(e, cmd) {} );
Methods
The following methods are available in the wijribbon widget:
setButtonChecked
- The setButtonChecked method sets a ribbon button as checked or not checked.
- Parameters:
- commandName (string): The command name of the button.
- checked (Boolean): The checked state of the button.
- name (string): The name of the parent button (optional).
- Code Example:
$("#element").wijribbon("setButtonChecked","superscript",false);
setButtonsChecked
- A function that sets the buttons as checked or not checked.
- Parameters:
- command (object): Contains command information that needs to change state.
- The key is the command name.
- The value is the button disabled state - true or false.
- command (object): Contains command information that needs to change state.
- Code Example:
var commands = {undo:true, redo:false}; $("#element").wijribbon("setButtonsChecked", commands);
setButtonDisabled
- The setButtonDisabled method sets the chosen button as enabled or disabled according to the command name.
- Parameters:
- commandName: The name of the command.
- disabled: The state of the button, true or false.
- Code Example:
$("#element").wijribbon("setButtonDisabled","undo",true);
setButtonsDisabled
- The setButtonsDisabled method sets the ribbon buttons as enabled or disabled according to the command name.
- Parameters:
- command: An Object that contains command information that needs to change state.
- The key is the command name.
- The value is the button disabled state - true or false.
- command: An Object that contains command information that needs to change state.
- Code Example:
var commands = {undo:true, redo:false}; $("#element").wijribbon("setButtonsDisabled",commands);