Bartosz Dziewoński has uploaded a new change for review.
https://gerrit.wikimedia.org/r/209737
Change subject: Toolbar: Rework example and add 'menu' tool group example
......................................................................
Toolbar: Rework example and add 'menu' tool group example
* Remove some useless junk that we do not really need even if the
underlying code thinks we do.
* Add a second example where all the useless junk *is* actually
necessary for some unfathomable reason.
Change-Id: Ib0c75c9ccae8d77ca6582520c96808741d27fd14
---
M src/Toolbar.js
1 file changed, 142 insertions(+), 17 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/oojs/ui refs/changes/37/209737/1
diff --git a/src/Toolbar.js b/src/Toolbar.js
index 99e6150..f52fbff 100644
--- a/src/Toolbar.js
+++ b/src/Toolbar.js
@@ -1,9 +1,9 @@
/**
* Collection of tool groups.
*
- * @example
- * // Basic OOjs UI toolbar example
+ * The following is a minimal example using several tools and tool groups.
*
+ * @example
* // Create the toolbar
* var toolFactory = new OO.ui.ToolFactory();
* var toolGroupFactory = new OO.ui.ToolGroupFactory();
@@ -17,7 +17,7 @@
* // Create a class inheriting from OO.ui.Tool
* function PictureTool() {
* PictureTool.super.apply( this, arguments );
- * };
+ * }
* OO.inheritClass( PictureTool, OO.ui.Tool );
* // Each tool must have a 'name' (used as an internal identifier, see
later) and at least one
* // of 'icon' and 'title' (displayed icon and text).
@@ -27,12 +27,8 @@
* // Defines the action that will happen when this tool is selected
(clicked).
* PictureTool.prototype.onSelect = function () {
* $area.text( 'Picture tool clicked!' );
+ * // Never display this tool as "active" (selected).
* this.setActive( false );
- * };
- * // The toolbar can be synchronized with the state of some external
stuff, like a text
- * // editor's editing area, highlighting the tools (e.g. a 'bold' tool
would be shown as active
- * // when the text cursor was inside bolded text). Here we simply disable
this feature.
- * PictureTool.prototype.onUpdateState = function () {
* };
* // Make this tool available in our toolFactory and thus our toolbar
* toolFactory.register( PictureTool );
@@ -40,7 +36,7 @@
* // Register two more tools, nothing interesting here
* function SettingsTool() {
* SettingsTool.super.apply( this, arguments );
- * };
+ * }
* OO.inheritClass( SettingsTool, OO.ui.Tool );
* SettingsTool.static.name = 'settings';
* SettingsTool.static.icon = 'settings';
@@ -49,14 +45,12 @@
* $area.text( 'Settings tool clicked!' );
* this.setActive( false );
* };
- * SettingsTool.prototype.onUpdateState = function () {
- * };
* toolFactory.register( SettingsTool );
*
* // Register two more tools, nothing interesting here
* function StuffTool() {
* StuffTool.super.apply( this, arguments );
- * };
+ * }
* OO.inheritClass( StuffTool, OO.ui.Tool );
* StuffTool.static.name = 'stuff';
* StuffTool.static.icon = 'ellipsis';
@@ -65,12 +59,10 @@
* $area.text( 'More stuff tool clicked!' );
* this.setActive( false );
* };
- * StuffTool.prototype.onUpdateState = function () {
- * };
* toolFactory.register( StuffTool );
*
* // This is a PopupTool. Rather than having a custom 'onSelect' action,
it will display a
- * // little popup window (a PopupWidget). 'onUpdateState' is also already
implemented.
+ * // little popup window (a PopupWidget).
* function HelpTool( toolGroup, config ) {
* OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
* padded: true,
@@ -78,7 +70,7 @@
* head: true
* } }, config ) );
* this.popup.$body.append( '<p>I am helpful!</p>' );
- * };
+ * }
* OO.inheritClass( HelpTool, OO.ui.PopupTool );
* HelpTool.static.name = 'help';
* HelpTool.static.icon = 'help';
@@ -101,7 +93,140 @@
* include: [ 'settings', 'stuff' ]
* }
* // Note how the tools themselves are toolgroup-agnostic - the same
tool can be displayed
- * // either in a 'list' or a 'bar'. There is a 'menu' tool group too,
not showcased here.
+ * // either in a 'list' or a 'bar'. There is a 'menu' tool group too,
not showcased here,
+ * // since it's more complicated to use. (See the next example
snippet on this page.)
+ * ] );
+ *
+ * // Create some UI around the toolbar and place it in the document
+ * var frame = new OO.ui.PanelLayout( {
+ * expanded: false,
+ * framed: true
+ * } );
+ * var contentFrame = new OO.ui.PanelLayout( {
+ * expanded: false,
+ * padded: true
+ * } );
+ * frame.$element.append(
+ * toolbar.$element,
+ * contentFrame.$element.append( $area )
+ * );
+ * $( 'body' ).append( frame.$element );
+ *
+ * // Here is where the toolbar is actually built. This must be done after
inserting it into the
+ * // document.
+ * toolbar.initialize();
+ *
+ * The following example extends the previous one to illustrate 'menu' tool
groups and the usage of
+ * 'updateState' event.
+ *
+ * @example
+ * // Create the toolbar
+ * var toolFactory = new OO.ui.ToolFactory();
+ * var toolGroupFactory = new OO.ui.ToolGroupFactory();
+ * var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );
+ *
+ * // We will be placing status text in this element when tools are used
+ * var $area = $( '<p>' ).text( 'Toolbar example' );
+ *
+ * // Define the tools that we're going to place in our toolbar
+ *
+ * // Create a class inheriting from OO.ui.Tool
+ * function PictureTool() {
+ * PictureTool.super.apply( this, arguments );
+ * }
+ * OO.inheritClass( PictureTool, OO.ui.Tool );
+ * // Each tool must have a 'name' (used as an internal identifier, see
later) and at least one
+ * // of 'icon' and 'title' (displayed icon and text).
+ * PictureTool.static.name = 'picture';
+ * PictureTool.static.icon = 'picture';
+ * PictureTool.static.title = 'Insert picture';
+ * // Defines the action that will happen when this tool is selected
(clicked).
+ * PictureTool.prototype.onSelect = function () {
+ * $area.text( 'Picture tool clicked!' );
+ * // Never display this tool as "active" (selected).
+ * this.setActive( false );
+ * };
+ * // The toolbar can be synchronized with the state of some external
stuff, like a text
+ * // editor's editing area, highlighting the tools (e.g. a 'bold' tool
would be shown as active
+ * // when the text cursor was inside bolded text). Here we simply disable
this feature.
+ * PictureTool.prototype.onUpdateState = function () {
+ * };
+ * // Make this tool available in our toolFactory and thus our toolbar
+ * toolFactory.register( PictureTool );
+ *
+ * // Register two more tools, nothing interesting here
+ * function SettingsTool() {
+ * SettingsTool.super.apply( this, arguments );
+ * this.reallyActive = false;
+ * }
+ * OO.inheritClass( SettingsTool, OO.ui.Tool );
+ * SettingsTool.static.name = 'settings';
+ * SettingsTool.static.icon = 'settings';
+ * SettingsTool.static.title = 'Change settings';
+ * SettingsTool.prototype.onSelect = function () {
+ * $area.text( 'Settings tool clicked!' );
+ * // Toggle the active state on each click
+ * this.reallyActive = !this.reallyActive;
+ * this.setActive( this.reallyActive );
+ * // To update the menu label
+ * this.toolbar.emit( 'updateState' );
+ * };
+ * SettingsTool.prototype.onUpdateState = function () {
+ * };
+ * toolFactory.register( SettingsTool );
+ *
+ * // Register two more tools, nothing interesting here
+ * function StuffTool() {
+ * StuffTool.super.apply( this, arguments );
+ * this.reallyActive = false;
+ * }
+ * OO.inheritClass( StuffTool, OO.ui.Tool );
+ * StuffTool.static.name = 'stuff';
+ * StuffTool.static.icon = 'ellipsis';
+ * StuffTool.static.title = 'More stuff';
+ * StuffTool.prototype.onSelect = function () {
+ * $area.text( 'More stuff tool clicked!' );
+ * // Toggle the active state on each click
+ * this.reallyActive = !this.reallyActive;
+ * this.setActive( this.reallyActive );
+ * // To update the menu label
+ * this.toolbar.emit( 'updateState' );
+ * };
+ * StuffTool.prototype.onUpdateState = function () {
+ * };
+ * toolFactory.register( StuffTool );
+ *
+ * // This is a PopupTool. Rather than having a custom 'onSelect' action,
it will display a
+ * // little popup window (a PopupWidget). 'onUpdateState' is also already
implemented.
+ * function HelpTool( toolGroup, config ) {
+ * OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
+ * padded: true,
+ * label: 'Help',
+ * head: true
+ * } }, config ) );
+ * this.popup.$body.append( '<p>I am helpful!</p>' );
+ * }
+ * OO.inheritClass( HelpTool, OO.ui.PopupTool );
+ * HelpTool.static.name = 'help';
+ * HelpTool.static.icon = 'help';
+ * HelpTool.static.title = 'Help';
+ * toolFactory.register( HelpTool );
+ *
+ * // Finally define which tools and in what order appear in the toolbar.
Each tool may only be
+ * // used once (but not all defined tools must be used).
+ * toolbar.setup( [
+ * {
+ * // 'bar' tool groups display tools' icons only, side-by-side.
+ * type: 'bar',
+ * include: [ 'picture', 'help' ]
+ * },
+ * {
+ * // 'menu' tool groups display both the titles and icons, in a
dropdown menu.
+ * // Menu label indicates which items are selected.
+ * type: 'menu',
+ * indicator: 'down',
+ * include: [ 'settings', 'stuff' ]
+ * }
* ] );
*
* // Create some UI around the toolbar and place it in the document
--
To view, visit https://gerrit.wikimedia.org/r/209737
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ib0c75c9ccae8d77ca6582520c96808741d27fd14
Gerrit-PatchSet: 1
Gerrit-Project: oojs/ui
Gerrit-Branch: master
Gerrit-Owner: Bartosz Dziewoński <matma....@gmail.com>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
