VPop - Pop-up Content for Proboards v5+ Feb 21, 2016 21:35:19 GMT -8 Chris, CåñåÐå™, and 3 more like this
Post by Virgil Sovereign on Feb 21, 2016 21:35:19 GMT -8
|VPop v1.0.5 |
Author: Virgil Sovereign
Plugin: VPop v1.0.5 Beta - Visit Proboards Plugin Library to Download
Keys Used: None
|Allows users to post pop-up content that appears when clicking or hovering. Pop-ups are also known as "tooltips", "rollovers", and "callouts".|
The default configuration adds a button to the post editor (and if present, the augmented Quick Reply) that inserts [pop] tags in BBCode mode and anchor/pop-up pairs in Visual mode that convert to pop-ups when viewed outside the editor.
When speaking about pop-ups, an anchor is the text or content in a post that is hovered over or clicked to show a pop-up. The content shown and hidden is called the pop-up content, or simply "the pop-up". See Fig. 1.
The plugin supports a broad range of options in its configuration section, including:
Pop-ups can be inserted into a post in one of three ways:
Method 1. When method 1 is used, a dialog will open to request text and/or an image to use as an anchor (see Fig. 2). Users can choose to override the default position, title, trigger, and maximum width of the pop-up if they wish.
When the pop-up is inserted, it will appear as a [pop] tag in the BBCode mode of the editor (see Fig. 3), and as two dotted boxes in the Visual mode of the editor: one surrounding the anchor and one surrounding the pop-up content (see Fig. 4 and 5). Depending on plugin settings, the content of a pop-up may appear beside its anchor (see Fig. 4) or at the bottom of the editor (see Fig. 5). Also depending on the settings, the anchor and content may have special formatting, and the content may have a title. The content for a newly-inserted pop-up will be the content placeholder specified in the plugin settings (see Fig. 6). The anchor and content of a pop-up can be modified in either editor mode at any time.
If an image URL is specified and a number is entered into the "Anchor Text" field of the "Insert Pop-up" dialog, the new pop-up will be a thumbnail. A thumbnail is a common type of pop-up where the anchor is a smaller (thumbnail-sized) version of the pop-up (see Fig. 6, 9, and 14 for examples). The width of the smaller image (in pixels) will be the number in the "Anchor Text" field. This allows thumbnail pop-ups to be inserted quickly without any additional steps.
Method 2. Insertion method 2 is identical to method 1 except that instead of opening a dialog, the plugin "wraps" the pop-up around the currently-selected content in the editor, making it the anchor of the new pop-up. This method will not work if the selected content contains only whitespace (characters that are invisible, like spaces) since anchors must contain at least one non-whitespace character.
Method 3. Insertion method 3 involves manually typing a [pop] tag into the BBCode mode of the editor (or QuickReply). The plugin presently supports four [pop] tag formats:
Pop-ups inserted with methods 1 and 2 use the preferred format specified in the plugin settings or else the closest allowable format if the anchor contains restricted characters or BBCode tags.
Pop-ups must not be nested, meaning the anchor or content of a pop-up may not contain other pop-ups inside. Nested pop-ups are automatically deleted by the plugin when a post is published or viewed in the Visual mode of the editor.
Also note that pop-ups must not have empty anchors or anchors containing only whitespace. Pop-ups with empty anchors or anchors containing only whitespace are automatically deleted by the plugin when a post is published or viewed in the Visual mode of the editor. The contents of a pop-up may be empty.
To remove a pop-up in the Visual editor mode, delete its anchor or delete all of the content in its anchor. When an anchor is deleted, its associated pop-up content is also deleted.
Editing and Moving Pop-ups
When editing either a pop-up's anchor or contents in the Visual editor mode, the borders of both its anchor and content boxes change colour to indicate which pop-up is being edited. This is useful in cases where pop-up content is placed at the bottom of the editor rather than beside its anchor.
Depending on the web browser being used, pop-up anchors can be moved in the Visual editor either by dragging them or by highlighting their contents and dragging them to a new location. The location of a pop-up's contents is automatically determined by the plugin; contents cannot be moved directly.
Switching Between Editor Modes
When switching between the BBCode and Visual editor modes, [pop] tags automatically convert to the preferred format in the plugin settings or else the closest allowable format if the anchor contains restricted characters or BBCode tags. Additionally, short form attributes will be converted to long form.
For example, if the preferred format is set to format 4, [pop] tags entered as
will convert to
when switching between editor modes.
A pop-up appears and disappears based on its trigger, which can be set to either click (clicking) or hover (hovering with the mouse). Regardless of the trigger, a pop-up can always be shown by clicking on its anchor and can always be hidden by clicking anywhere in the browser window (except on a link or interactive element inside the pop-up itself). Showing a pop-up will automatically hide all other pop-ups. If a pop-up's trigger is set to hover, it will stay open as long as the cursor remains over the anchor or, optionally, the pop-up itself.
Settings and Defaults
As of v1.0.0, the VPop UI (i.e. settings panel, see Fig. 7) has five tabs in addition to the usual "About" tab:
The "out of the box" settings for VPop yield pop-ups in the style of Fig. 8, having the same background colour and text colour as the post containing the pop-up, a bold title, rounded corners, a thin black border, a shadow, and a medium stem. Pop-up anchors appear in the style of hyperlinks.
Intermediate Stuff (you can handle it):
Each pop-up has five attributes that can be overridden in the "Insert Pop-up" dialog or by editing [pop] tags manually in the BBCode editor:
Legal pop-up attributes and their effects are:
Any pop-up with an invalid position will use the default pop-up position. Any pop-up with an invalid trigger will use the default pop-up trigger. Any pop-up with an invalid maximum width will use the default maximum width for the type of content in the pop-up. Unrecognized attributes will be ignored and deleted when a post is published or the editor is switched to Visual mode.
If an attribute is set more than once in a tag, all but the last value is ignored.
Proboards plugins can't be run in some circumstances. For example, plugins won't run on platforms such as Tapatalk and Facebook, or when a user has scripts disabled in their browser. Additionally, an admin may choose to disable or remove VPop. To help forum administrators deal with these issues gracefully, VPop publishes posts in placeholder mode where pop-up contents appear as placeholders rather than live pop-ups.
Placeholders are configurable in the plugin settings under the Formats tab. By default, pop-ups containing only text are expanded inside angular brackets (??) next to their anchors, and pop-ups containing non-textual content are placed at the bottom of a post (see Fig. 9 and 10). The plugin can be configured to show either type of content inline or at the bottom of the post, or to hide it entirely. For content placed at the bottom of a post, admins can choose whether to include titles, numbers, and/or a dividing line between the post and the pop-ups. Because pop-ups are inactive in placeholder mode, their anchors will have no special formatting or cursor applied to them by default. This setting can be changed in the plugin configuration.
Any page can be viewed in placeholder mode by either: i) disabling VPop, or ii) appending either &no-vpop or #no-vpop to the URL in the address bar and visiting/reloading the page. As a general rule, pop-ups containing non-textual content are usually disruptive enough to the content layout that they should be placed at the end of a post or hidden.
Note that settings for placeholder mode are independent of settings for viewing pop-ups in the Visual mode of the editor.
Advanced Settings (for the perfectionists):
Special classes are admin-defined classes that can be applied to pop-ups on a case-by-case basis. Each special class comes with its own default settings for pop-up attributes and content placeholder, and attaches a class to pop-ups and anchors that can be uniquely targeted by CSS selectors.
Special classes are mainly useful for letting users create different 'types' of pop-ups. For example, an admin might want a "Gardening Facts" pop-up with a flowery border and "insert gardening fact here" content placeholder; an "Image Rollover" pop-up with no border, a transparent background, and wider-than-usual default maximum width; and a "Basic Tooltip" pop-up with a smaller font, no title, and minimalist look. Special classes allow these kinds of case-by-case customizations.
Special classes are defined in the plugin settings under the Special Classes tab (see Fig. 11). Each class has the following parameters:
All special classes with human-readable names will appear in the "Special Classes" drop-down list in the "Insert Pop-up Dialog", which is the simplest way for users to apply special classes to pop-ups. If no special classes with human-readable name are defined, the "Special Classes" drop-down will not appear in the dialog.
VPop Element Structure
The element structure of a live pop-up is shown in Fig. 12.
Descriptions of the elements are as follows:
The element structure of pop-ups in the Visual mode of the editor is similar, but differs from the structure of live pop-ups in three ways:
As a general rule, do not modify the position, top, left, display, opacity, or float CSS properties of any VPop element unless you're certain you know what you're doing.
If the border radius of a pop-up is modified in any way besides modifying "Border Style" in the plugin settings, care should be taken to ensure that the element selected by
has properties border-top-right-radius and border-top-left-radius set to the border-radius of #vpop minus any space between the outer border and .vpop-wrapper's children. Similarly, the element selected by
should have its border-bottom-right-radius and border-bottom-left-radius set this way. If your eyes just glazed over, stick with the plugin settings if you want to modify border radius.
Advanced Style Overrides
VPop generates styles for pop-ups and anchors dynamically in a four-step process:
From a customization standpoint, the most important step is the application of Advanced Style Overrides (ASOs). Each ASO is a pair of data: a CSS Selector, and a set of CSS Properties (see Fig. 13). Adding an ASO to the set of Override Rules under "Advanced Style Overrides" in the Styles tab of the plugin settings is roughly equivalent to appending
to the end of both the live and editor style sheets after all basic styles have been merged in, with two important exceptions:
In every other respect, ASOs are identical to regular CSS rules and may make use of any valid CSS3 selectors and properties.
Some example sets of ASOs:
Known Issues and Limitations
Compatibility with Other Plugins
VPop converts pop-up placeholders to live pop-ups through excision, meaning that pop-up contents are excised (removed) from the DOM when a page is first loaded and stored in a DocumentFragment until needed. If another plugin that converts placeholders into live content is being run at the same time as VPop, the plugins may interfere with each other in two ways:
By default, VPop makes pop-ups accessible for editing and viewing by all users on all pages. VPop can be disabled on a theme- or group- conditional basis by editing its permissions in the Forum Plugins control panel. Disabling the plugin for specific themes/groups will prevent affected users from inserting pop-ups (even using BBCode tags) and cause them to see pop-ups in placeholder mode (as described in Pop-up Placeholders).
For greater control over the conditions under which VPop is run, admins may take the following steps:
For step 2, admins may make use of the Condition X plugin if desired. In this case, the steps become:
In this way, conditions on viewing and/or editing pop-ups can be precisely controlled.
To combine conditional launch with delayed launch, things get a bit tricky. Make inquiries in this thread and I can provide detailed instructions.
Figures (a.k.a. Screenshots):
Fig. 1 - A post containing numerous pop-up anchors and an open pop-up. The pop-up content "pops up" above the normal content of the webpage when triggered, hence the name "pop-up".
Fig. 2 - The "Insert Pop-up" dialog. The dialog can create text-only, text-and-image, image-only, and thumbnail anchors, and override the default pop-up attributes.
Fig. 3 - The BBCode editor when augmented with VPop. An additional "Insert Pop-up" button (with configurable graphic and title) appears on the editor control panel. Pop-ups are represented by [pop] tags in a variety of formats.
Fig. 4 - The Visual editor when augmented with VPop, in content-beside-anchor mode, with titles not shown. Pop-up anchors and content are surrounded by dotted boxes to indicate their status as pop-ups. The borders around the anchor and content of the pop-up being edited are blue to indicate which pair is being edited.
Fig. 5 - The Visual editor when augmented with VPop, in content-at-bottom mode, with titles shown and visual styles applied in editor. Rather than appearing inside the normal content flow, pop-up content is collected in a "Pop-ups" section at the bottom of the post and managed automatically by the editor.
Fig. 6 - A newly-inserted pop-up with a content placeholder. The content placeholder can contain any text, and can vary between special classes. It is automatically highlighted by the editor so that typing immediately after a pop-up is inserted will replace the placeholder with new text or content.
Fig. 7 - The Formats tab in the VPop UI (settings). The UI is extensively documented and provides descriptive tooltips, hence the purpose and usage of most settings should be reasonably clear.
Fig. 8 - Default look for live pop-ups. Pop-up content has the same background colour and text colour as the post containing the pop-up, a bold title, rounded corners, a thin black border, a shadow, and a medium stem. Pop-up anchors appear in the style of hyperlinks.
Fig. 9 - A post containing multiple pop-ups in "live mode", with a borderless, transparent image pop-up open to show a full-sized version of an avatar thumbnail. Pop-up anchors appear with formatting. Content is hidden unless a pop-up is open. Contrast with Fig. 10.
Fig. 10 - A post containing multiple pop-ups in "placeholder mode". By default, anchors appear with no special formatting in this mode. Content for a text-only pop-up is expanded beside its anchor, and content for a non-textual pop-up appears at the bottom of the post. Contrast with Fig. 9. In this screenshot, anchors appear with formatting even in placeholder mode due to "Preserve Anchor Formatting" being checked in the plugin settings under Placeholders in the Format tab.
Fig. 11 - A special class definition under the Special Classes tab in the VPop UI (settings). Special classes provide pop-ups with new styles and default attributes on a case-by-case basis.
Fig. 13 - An advanced style override (ASO) definition in the Advanced Style Overrides section under the Styles tab in the VPop UI (settings). ASOs facilitate creation/modification of pop-up styles in both the editor and live pop-ups. Each ASO contains a CSS selector and a set of CSS properties.
Fig. 14 - A live pop-up configured to look like a Proboards tooltip using a combination of plugin settings and ASOs.
Fig. 15 - A live "Harry Potter Fact" -themed pop-up using the harry special class. The special class imputes admin-defined attributes and styles to marked pop-ups' content and anchors. Styles shown here are realized with a combination of special class settings and ASOs.
Fig. 16 - A live "Warrior Cats" -themed pop-up using the warcats special class. The class has been "decked out" with ASOs to emphasize the great extent to which pop-up styles can be customized.
Bugs and Feedback:
|Astute readers will have noted that this plugin is marked BETA. Although I have tested it extensively on my home board, there will undoubtedly be a few problems still hiding out.|
Please notify me of any problems you experience in this thread and I will do my best to resolve issues promptly.
Aside from that, happy popping! (...not pooping. )