---

This article is the xbRefs Plugins Documentation. This covers both the Content and the Button (editors-xtd) plugins. Details of the xbRefMan component will be in a separate article.

NB - do NOT copy and paste any of the example shortcodes on this site which are formatted as code samples - they include an invisible character (\u200b) between the "{" and the "xbref" which prevents the example being processed by the content plugin on this site so that you can see the code.

The format for a correctly formed xbRef shortcode to insert a reference is as follows (items in [brackets] are optional. | indicates alternatives) 

  {​xbref tag="N" [title="Text"] [desctext|desc="text"] [addtext="text"] [disp="pop|foot|both"] [trig="hover|focus|click"] }content{​/xbref} 

For a shortcode to insert a footnote area

  {​xbref [num="N"] [head="text"] } 

for detailed explanation see Shortcodes below

Contents:

1. Introduction
2. Installation
3. Uninstalling
4. Options
5. Shortcodes
   1. { xbrefs...}
   2. { xbrefs-here...]
6. Button Form
7. Hints,Tips and Quirks 

Introduction

xbRefs Plugins provide facilities to enter and display references in Joomla articles. References may be displayed in either a popover in the text, or a footnote at the bottom of the article, or both.

As well as traditional academic styles references or links to related articles/sources, references can also be used for definitions, TLAs, comments, footnotes^[1] or any other metadata relating to the article content.

References are either created as a 'one-off' text title and content, or can use the title and description from any Joomla tag. The use of tags allow references to easily be re-used across articles.

Footnote references are identified by a sequence number starting with [1] for the first reference in the article. The list of footnotes (the citations) will be added to the end of the article by default, although use of a special shortcode {​xbref-here} allows a partial list to be inserted at any point, with any subsequent references being displayed at the next  {​xbref-here}  or at the end of the article. This is useful if you are using page-breaks within a long article to break it up into separate webpages - using the special shortcode immediately before the page breaks will show the footnotes at the end of each page, with the numbering continuing on the next page.

This may also be useful if you are entering other information at the end of the article and want the footnotes to appear before this.

Popovers are displayed over the word(s) from the article enclosed   {​xbref ...}between{​/xbref}  the shortcodes (the text selected when the xbRef button is used in the editor. Using the built-in stylesheet  popovers are hinted by a dotted or dashed underline.

The button plugin provides an easy way of inserting correctly formatted shortcodes. In addition it has an option to place a pale yellow highlight around the shortcode (as seen in the example above) 

 

↑ Contents

Installation

xbRefs-Plugins is provided as a package containing both editor button and content processing plugins. Although they are installed s a package it is not essential to use the editor button - you can enter shortcodes manually from the keyboard. However if xbRefs shortcodes are present in any article it is essential that the Content plugin is enabled or the raw shortcode, possibly including highlighting will appear in the article like {​xbref tag="0" title="Plugin Disbled" desctext="This is how a shortcode would appear if the content plugin was absent or disabled." disp="pop" }this {/​xbref}

Install in the usual way - by downloading the zip file from https://crosborne.uk/component/phocadownload/file/21-xbrefs-plugins and uploading it to Extensions-|-Manage-|-Upload Package tab on your site admin, or from the direct link https://crosborne.uk/downloads?download=21 in the Install from URL tab

Immediately after installing it is recommended you review the Options for both button and content plugin. 

 

↑ Contents

Uninstalling

Uninstall will by default remove all xbRefs shortcodes from articles. If you wish to preserve them (eg if you are planning to reinstall) then there is a xbRefs-Content plugin option to disable this function before uninstalling. After uninstall the page will show a list of all articles that have had a shortcode removed with links to edit in a new tab so that if you have made a mistake you could restore them using the last saved Joomla version for the article. 

 

↑ Contents

Setting Options

The Button plugin has only three options which you can change:

• Whether or not to highlight the shortcode in the editor and the colour used for the highlight. The default is 'Yes' and a pale yellow colour.
• Which tags to make available for references and whether or not to include the children of the selected tags. There is no default so if you do not set this no tags will be available to use. Typically you will create a placeholder tag (eg "References") and include children of this tag. Then create all your tags for use as references as children of "References" and you only need to make the one selection in the option. Multiple tags can be selected.
• Whether to enforce the default options for reference parameters which are set in the Content plugin options to be used (Reference Display, Bracket Numbers, Popover Trigger). Default is No. If set to Yes then the optional settings on the button modal form are not shown. This would ensure that all references on your site will have a common format (probably a good thing) but would also mean that any subsequent changes to the options will retrospectively affect all existing references (may be a good or bad thing depending on your point of view)

The Content plugin has more options allowing default settings for new shortcodes to be set, and also allowing the styling of both popovers and footnotes to be altered - see the section on Styles below.

 

Plugin Tab

Styling Tab

Remove Shortcodes on Uninstall. Default is "Yes" - be sure to set to "No" before uninstalling if you wish to preserve the shortcodes. Reference Display - Popover | Footnote | Both. Default is both. Sets how references will be displayed [ ] around Ref Number. Default "Yes". Whether to enclose the sequence number for footnote references in square brackets. This makes them more visible in superscript and an easier target to click on to jump to the footnote. Popover Trigger action. Hover | Focus | Click. Default "hover". Sets action that will cause a popover to be displayed. Focus requires a click on (or tab to) the linked word to open the popover and then a click (or tab) elsewhere to close it. This may be better for touchscreens. Click (coming in v2) requires a second click on the link which can be confusing for the user, but does allow the text in the popover to be selected and copied.  Popover Class. (coming in v2) Only shown if not using built-in CSS - default hasPopover which will use template defaults to style popovers.

Footnote Area Header Text. Default "References & Footnotes". Allows you to change the header text used on the footnote area. If you are using {​xbref-here} to insert a footnote area then there is an option to change the header for that occassion. Styles options Font Size for the footnote area. Specify in em, px or pt. The footnote area header will be in bold, as will the reference names Text colour for the footnote area Background colour for the footnote area Borders (each edge) for the footnote area. Border will be solid, 1px, and use the text colour.  The popover style will be the bootstrap or template default - in Joomla it looks like this (hover over the word this - note there is no cue hint so in xbRefs a dotted underline is added like this)

 

 

↑ Contents

Shortcode

There are two shortcodes used by xbRefs. The main one creates a reference link and a citation as either/or/both popover and footnote. A secondary one will cause any pending footnotes to be inserted at a particular point in the article - typically immediately above a page break.

The insert footnotes shortcode is very simple

 {​xbref-here}  .

The format for a correctly formed full xbRef reference shortcode is as follows (items in [brackets] are optional. | indicates alternatives) 

  {​xbref tag="N" [link="N"] [title="Text"] [desctext|desc="text"] [addtext="text"] [disp="pop|foot|both"] [trig="hover|focus|click"] }content{​/xbref} 

Shortcode elements. All text following an = sign is enclosed in double quotes. If a reuired element has an invalid value (eg a non-existant tag id, or missing title text with a tag id of zero) then the shortcode will simply be silently removed leaving the content text in the article. If any optional values are invalid or not present then the default set in the content plugin options will be used

• opening (required) : a curly brace ( followed immediately by xbref and a space
• tag= (required) : the id number of a valid tag or zero, enclosed in double quotes. The button plugin will automatically generate the right id from a list of selected tags, or you can manually insert any tag id.
• link= (valid if tag="0") : id of a weblink component item to use for the citation. Only works if the weblink component is installed. Will use the title and description from the weblink item and provide a link to the webpage in the citation. Popovers will require "click" trigger so that link in popover can be activated.
• title= (required if tag="0" and link= not present) : this will be the title of the popover or the name of the footnote citation if no tag is specified. Plain text only, by default will be displayed as bold in the footnote area.
• desc= : description text for the body of the popover or footnote citation if no tag is specified. Can include basic html tags (only <b> and <i> at present)
• addtext= (only used if a valid tag is specified) : additional plain text which will be appended to the tag description. Allows per-occasion addition to citation.
• disp= ; the type of display for the reference. Must be one of "pop", "foot" or "both". If "pop" or "both" are specified and no content text is included then a popover cannot be displayed.
• trig= : the type of trigger for any popover. Must be one of "hover" or "focus" or "click"
• close element (required) : closing curly brace for the elements shortcode
• content : any text from the article which is selected when the button is used. This will become the action link for a popover. If no content text is included then there is nothing to trigger a popover on so it will not work.
• closing shortcode (required) : {/xbref} 

 

↑ Contents

Button Form

Details of button form including screenshot 

↑ Contents

 Hints, Tips & Queries

•  to set a start number for references for the whole article insert a  {​xbref-here num="N" }  .shortcode at the top of the page before any references where N is the number to be used for the first reference.
•  to set the header text for the footnote area at the bottom of the article insert a   {​xbref-here head="New Header Text" } shortcode at the end of the article. This will override the default header text set in the options. 

↑ Contents