Difference between revisions of "User:King of Herdaz/Toolbar customization"

Revision as of 00:24, 27 October 2021

The editing toolbar is a versatile and very useful tool that can be used to make working on the wiki much easier. While the basic version (which is an option in your preferences) has some use, the main benefit comes when you customize your toolbar. In this guide there is a list of premade elements that you can use as well as guides to creating and modifying your own buttons, booklets, and dropdowns.

While modifying your toolbar can seem scary, once you get the hang of it, it really isn't a big deal. Also, anything you do can be easily undone so feel free to play around and experiment with different things.

Basic

Before you can customize your toolbar you need to have the "Enable the editing toolbar" option in your preferences selected. Once you have done this you are ready to begin.

Add the following to your /common.js page:

//customize toolbar
var customizeToolbar = function() {
  /* Your code goes here */

Followed by this:

};
/* 
 * Check if view is in edit mode and that the required modules are available. Then, customize the toolbar...
 * Don't touch below this line!
 */
if (['edit', 'submit'].indexOf(mw.config.get('wgAction')) !== -1) {
  mw.loader.using('user.options').then(function() {
    // This can be the string "0" if the user disabled the preference ([[phab:T54542#555387]])
    if (mw.user.options.get('usebetatoolbar') == 1) {
      $.when(
        mw.loader.using('ext.wikiEditor'), $.ready
      ).then(customizeToolbar);
    }
  });
}

You will place any modifications to the toolbar that you make between these two sections.

Removing default elements

This can be a little tricky since in order to remove an element you need to know what it is named. To find the name you will have to comb through the page source or look through the code for the default version.

Fortunately, the names of many of the elements are known. Here are premade sections (I think there's a better word for this) of code for many of the elements in the default toolbar. Paste any one of them into your Common.js page within the two #Basic sections to remove that element.

<ref> Button

  //Remove the default <ref> button
   $( '#wpTextbox1' ).wikiEditor( 'removeFromToolbar', {
 	  'section': 'main',
 	  'group': 'insert',
 	  'tool': 'reference'
   });

Bulleted List Button

  //remove the bulleted list button
  $( '#wpTextbox1' ).wikiEditor( 'removeFromToolbar', {
        'section': 'advanced',
        'group': 'format',
        'tool': 'ulist'
  });

Numbered List Button

  //remove the numbered list button
  $( '#wpTextbox1' ).wikiEditor( 'removeFromToolbar', {
        'section': 'advanced',
        'group': 'format',
        'tool': 'olist'
  });

Default Break Tag Button (<br>)

  //remove the default <br> button (to replace it with a <br/> button which is preferred on the Coppermind)
  $( '#wpTextbox1' ).wikiEditor( 'removeFromToolbar', {
        'section': 'advanced',
        'group': 'format',
        'tool': 'newline'
  });

Table Button

  //remove table button
  $( '#wpTextbox1' ).wikiEditor( 'removeFromToolbar', {
        'section': 'advanced',
        'group': 'insert',
        'tool': 'table'
  });

[[File:]] Button

  //remove File button
  $( '#wpTextbox1' ).wikiEditor( 'removeFromToolbar', {
        'section': 'main',
        'group': 'insert',
        'tool': 'file'
  });

Fancy Link Button

  //remove original link button
  $( '#wpTextbox1' ).wikiEditor( 'removeFromToolbar', {
        'section': 'main',
        'group': 'insert',
        'tool': 'link'
  });

Others

For elements not on this list take this code and replace XXXX with the name of the section the element is in, replace YYYY with the name of the group the element is part of, and replace ZZZZ with the name of the element. You you can find these names by looking through the code for the default version.

  $( '#wpTextbox1' ).wikiEditor( 'removeFromToolbar', {
        'section': 'XXXX',
        'group': 'YYYY',
        'tool': 'ZZZZ'
  });

Buttons

Premade Buttons

Simply paste any of these premade buttons into your /common.js page between the two #Basic sections to add it to the left side of the main section of your toolbar (which is the top row that is always showing).

Image template

Clicking this button will paste the {{image}} template on to the page, encapsulating your cursor or whatever you have highlighted.

For example, if you have Shallan.jpg highlighted when you press the button it will result in this: {{image|Shallan.jpg|side=|width=|caption}}

  // Adding image template button to the "main" section
  $('#wpTextbox1').wikiEditor('addToToolbar', {
    section: 'main',
    group: 'insert',
    tools: {
      "image": {
        label: 'Image template',
        type: 'button',
        icon: '//upload.wikimedia.org/wikipedia/commons/d/d8/Vector_toolbar_insert_image_button.png',
        action: {
          type: 'encapsulate',
          options: {
            pre:  '{' + '{image|',
            post: '|side=|width=|caption}}'
          }
        }
      }
    }
  });

Wikipedia Link

This button will paste [[Wikipedia: and |]] around your highlighted text. This generates a link to that Wikipedia page and hides the prefix. For example, if you highlight Brandon Sanderson and click this button it will generate this: [[Wikipedia: Brandon Sanderson|]] which produces Brandon Sanderson on the page.

  //  Adding Wikipedia link button to the "main" section
  $('#wpTextbox1').wikiEditor('addToToolbar', {
    section: 'main',
    group: 'insert',
    tools: {
      "wikipedia": {
        label: 'Wikipedia',
        type: 'button',
        icon: '//upload.wikimedia.org/wikipedia/commons/c/cb/Button_wikipedia.png',
        action: {
          type: 'encapsulate',
          options: {
            pre:  "[[Wikipedia: ",
            post: "|]]"
          }
        }
      }
    }
  });

Signature

Pastes ~~~~ into the page to generate your signature with a timestamp. This useful for commenting on talk pages.

  // Adding signature button to the "main" section
  $('#wpTextbox1').wikiEditor('addToToolbar', {
    section: 'main',
    group: 'format',
    tools: {
      "signature": {
        label: 'Signature',
        type: 'button',
        icon: '//upload.wikimedia.org/wikipedia/commons/6/6d/Button_sig.png',
        action: {
          type: 'encapsulate',
          options: {
            pre:  '~~' + '~~'
          }
        }
      }
    }
  });

Break Tag

Inserts <br /> into the page. This is the preferred syntax on the Coppermind for creating line breaks.

  // Adding <br/> button to the "main" section
  $('#wpTextbox1').wikiEditor('addToToolbar', {
    section: 'main',
    group: 'insert',
    tools: {
      "break": {
        label: 'Break tag',
        type: 'button',
        icon: '//upload.wikimedia.org/wikipedia/commons/1/13/Button_enter.png',
        action: {
          type: 'encapsulate',
          options: {
            pre:  '<' + 'br />',
          }
        }
      }
    }
  });

Simple Link

Simply encases the highlighted text within [[ and ]] to generate a link.

  // Adding link button to the "main" section
  $('#wpTextbox1' ).wikiEditor( 'addToToolbar', {
    section: 'main',
    group: 'format',
    tools: {
     "link": {
	label: 'Link',
	type: 'button',
	icon: '//upload.wikimedia.org/wikipedia/commons/9/97/Button_int_link.png',
	action: {
	  type: 'encapsulate',
	  options: {
	    pre: "[[",
	    post: "]]"
	  }
	}
      }
    }
  });

Hidden Text

Encases the highlighted text between  to prevent it from appearing in the viewable page.

  // Adding hidden text button to the "main" section
  $('#wpTextbox1' ).wikiEditor( 'addToToolbar', {
    section: 'main',
    group: 'format',
    tools: {
     "hidden": {
	label: 'Hidden text',
	type: 'button',
	icon: '//upload.wikimedia.org/wikipedia/commons/1/1b/Button_hide_wiki_tag.png',
	action: {
	  type: 'encapsulate',
	  options: {
	    pre: "<!--",
	    post: "-->"
	  }
	}
      }
    }
  });

Columns

Encases your text, which should a bulleted (*) or numbered (#) list, inside of the {{columns}} template to columnize the list.

  // Adding columns button to the "main" section
  $('#wpTextbox1' ).wikiEditor( 'addToToolbar', {
    section: 'main',
    group: 'format',
    tools: {
     "columns": {
	label: 'Columns',
	type: 'button',
	icon: '//upload.wikimedia.org/wikipedia/commons/2/25/Vector_toolbar_bulleted_list_button.png',
	action: {
	  type: 'encapsulate',
	  options: {
	    pre: '{' + '{columns|' + '\n',
	    post: '\n' + '}}'
	  }
	}
      }
    }
  });

<code>

Encases your highlighted text between <code> and </code>.

  // Adding a <code> button to the "main" section
  $('#wpTextbox1' ).wikiEditor( 'addToToolbar', {
    section: 'main',
    group: 'format',
    tools: {
     "code": {
	label: 'Code',
	type: 'button',
	icon: '//upload.wikimedia.org/wikipedia/commons/2/23/Button_code.png',
	action: {
	  type: 'encapsulate',
	  options: {
	    pre: '<' + 'code>',
	    post: '</' + 'code>'
	  }
	}
      }
    }
  });

Creating Your Own Buttons

To create your own button paste the code at the end of this section into your /common.js page between the two #Basic sections and change the following things:

If you want, you can put a description on the first line after the // as a comment. Whatever you write after a // will not affect your code.
Replace AAAA with the name of the section you would like to put the button.
Replace BBBB with the name of the part of that section where you would like your button to go.
Replace CCCC with what you want to name the button internally. The text that you put here does not actually affect anything and only matters for stylistic purposes.
Replace DDDD with what you want to name the button. Unlike the previous item, this actually makes a difference. The text you put here will be shown when you hover your cursor over this button's icon on your toolbar.
Replace EEEE with a link to the file that you would like to use as the icon for your button. This needs to be a full link starting after https:. For example, you can use //upload.wikimedia.org/wikipedia/commons/2/23/Button_code.png. While you can use any file as your icon it is recommended that you use one of the icons listed on Mediawiki's list of toolbar icons since they are all of a size and shape that works.
Replace FFFF with the first snippet of text. Follow the #General Guidelines.
Replace GGGG with the second snippet of text. Follow the #General Guidelines. If you do not want to have a second snippet you can delete this line.

  // Optional Description
  $('#wpTextbox1' ).wikiEditor( 'addToToolbar', {
    section: 'AAAA',
    group: 'BBBB',
    tools: {
     "CCCC": {
	label: 'DDDD',
	type: 'button',
	icon: 'EEEE',
	action: {
	  type: 'encapsulate',
	  options: {
	    pre: 'FFFF',
	    post: 'GGGG'
	  }
	}
      }
    }
  });

Adding New Sections

To add a new section to the toolbar paste the following code into your toolbar and change the following things:

Replace AAAA with the internal name that you want to give the section. This will be used to identify elements that go in this section.
Replace BBBB with the type of section you want to create. This can be either toolbar or booklet. Both of them will be explained below.
Replace CCCC with the name of the section. This will be displayed on the toolbar as the section's name.

  $( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
 	'sections': {
 		'AAAA': {
 			'type': 'BBBB',
 			'label': 'CCCC'
 		}
 	}
  } );

General Guidelines

Here are some rules and tips for writing code on your common.js page:

Inserting ' + ' between two pieces of text can have effects on your common.js page (as will be discussed below), but will not appear on a page when the action is called. For example, both <br /> and <' + 'br /> will produce the same result (<br />) on the page when they are called.
When writing out templates, whether as the label for an action or as part of the action itself, you must insert ' + ' between the first two curly brackets. For example, instead of writing {{Stormlight}} you should write {' + '{Stormlight}}. This prevents the template from applying categories to your common.js page and also prevents it from being listed on the relevant template's list of pages that use it.
For the same reason you must also do this when writing category tags. For example, instead of writing [[Category: Stormlight]] you should write [' + '[Category: Stormlight]].
When writing code for substitutions this is even more important, since if you do not do it then the substitution will be performed when you save your common.js page. For example, instead of writing {{SUBST:PAGENAME}} you should write {' + '{SUBST:PAGENAME}}.
To have an action include a line break insert \n into the snippet at the place you want it to be. For stylistic reasons some people will put ' + ' between instances of \n and other text in their snippets, but this does not have any effect on the output of the action and can be omitted if you want.

Actions

While there are other types of actions that you can do with buttons, in this guide we focus on the encapsulate action as it is the easiest to understand and use. This action pastes one snippet of text before the highlighted text (or you cursor) and a second snippet after the highlighted text. The second snippet (post:) can be deleted if you only want to insert one snippet of text.

The code for this action is as follows, and this format is the same for both dropdowns and buttons.

	action: {
	  type: 'encapsulate',
	  options: {
	    pre: 'XXXX',
	    post: 'YYYY'

XXXX is replaced by the snippet that goes before the highlighted text/cursor, and YYYY is replaced by the snippet that goes after the highlighted text/cursor.