Sliding Notes Back On Air

I’m pleased to announce that my efforts to overcome the cross-browser issues have yielded a promissing new Sliding Notes version. I’m running it on this site alredy, and I’d be grateful for your feedback on how it works with different browsers.

Stay tuned while I’m running some more tests and prepare an official release.

Slinding Notes – 1.1 Series Withdrawal

I am terribly sorry to announce that I’m temporarily withdrawing the 1.1 series due to cross-browser problems. The 1.0rc5 version is now marked as the “stable version”, and it will remain so until I’ve found a reliable solution to the problem. (The 1.1.0 version is still available through “Other Versions “).

Again, I’m really sorry for the inconvenience, but I thought this is the only fair thing to do right now (next to resolving the issue).

YouTube Inside A Sliding Note

I’ve just received an email asking whether Sliding Notes support embedding YouTube videos inside.

I’m happy to confirm that they do! Here is a cool video» that proves it!

I used the Insights plug-in to embed the video object directly between the slider tags.

But: Using a video (or any other) shortcode in a Sliding Note is currently not supported.

Sliding Notes Major Upgrade

Today I’m releasing version 1.1.0 of Sliding Notes. This is a major rewrite of the plug-in and the beginning of the 1.1 series.

Read more >>

Shortcode Shortcomings

This post requires a certain degree of technical savvyness.

When experimenting with various shortcode locations in the post content, I noticed that under some conditions the shortcode behaved a bit strange with regard to paragraph arrangement. So I implemented a couple of “diagnostic” shortcodes and filters to further investigate the problem. But before I go into that, follow me on a short tour through what the Shortcode API is. Read more >>

Sliding Notes HowTo – Centered Button With 1.0 Series

Dan asked me today how to accomplish a centered slider button/title, while keeping the note content left-aligned. While I try to work out a neater solution, I’d like to present to the impatient a way to do it right away, with the current version of Sliding Notes (1.0rc5), taking Dan’s example as a foundation. It’s a bit involved in the sense that it takes editing some HTML first, but it’s a feasible way to go nonetheless (and after setting up the HTML structure, the visual editor can be used as well).

Read more >>

Sliding Notes – Scriptaculous Caveats

Last Tuesday, Jörg reported a problem where Sliding Notes didn’t work on hist site. It turned out quickly that the problem was not with Sliding Notes, but due to a javascript exception thrown when jQuery was loaded. I analyzed the effect nonetheless, and I’d like to share my insights with you, as I believe they might be of general interest.

Sliding Notes use the jQuery javascript library. There are known conflicts between jQuery and Scriptaculous, another widespread javascript library. The conflicts are particularly dramatic with older Scriptaculous versions (1.7 and less).1. Scriptaculous versions 1.8.0 and later2 still have some conflicts with jQuery, but not at a scale that they would stop each other from functioning. Read more >>

1. See for ex. this google group discussion or this post [↩]
2. 1.8.2 is the current Scriptaculous version as of this writing [↩]

Sliding Notes – 8 Bits Full Of Downloads

Last night I noticed that the number of downloads of my Hackadelic Sliding Notes has reached 256.

To a software engineer, it is one of the “magic” numbers. It corresponds to 2⁸ (2 to the power of 8), and is the first number whose memory representation exceeds the size of a single byte.

From now on, it’ll take at least 2 bytes to count the downloads.

O.K., this might not be as big an achievement as the moonlanding, but hey! – Why miss an oportunity to celebrate?1 😉

1. Besides, the next byte boundary crossing is at 65’536 downloads, so I’ve probably got a planty of time until the next such occasion. [↩]

Sliding Notes

After some warm-up time with WordPress, I decided it’s about time to write a WordPress plug-in.

Not that I’ve been keen to program in another half-backed spawn of C++ (the mother of all programming language abominations ;-))1 with all the curly braces and clumsy syntax. But, the itching in my fingers was stronger than that.

So here it is! Ladies and gentlemen, I proudly present: The Slider Shortcode! An easy way to add sliding notes» to your WordPress content!

Download the latest version

[toc]

Usage

In the simplest case, the shortcode is used like so:

[slider title="slider button title"]sliding note content[/slider]

It will give you this: slider button title»

Other shortcode parameters are:

• bstyle=”CSS style directives” : Inline CSS style applied to the slider button
• nstyle=”CSS style directives” : Inline CSS style applied to the slider note
• type=”any-CSS-names” : The type(s) of the note. A type will be matched to a CSS class of the same name.
• type=auto-expand : A special type that forces automatic expansion of the note on page load.
• shortcodes=on : Enables recursive shortcode processing inside sliding notes. Omitting the parameter, or supplying any other value but “on” will disable recursive shortcode processing. Note however that recursive shortcode processing will not enable nested Sliding Notes.2
• hint=”hint text” : Specifies the text that will show when the mouse is being hovered over the slider button.
• group=”group name” : Specifies the group the sliding note belongs to. When a note belonging to a group is expanded, all other notes in that group are collapsed. Read more about this feature in the 1.5 release announcement.

The parameters are described in the release announcements in more detail.

Please visit the Sliding Notes Showcase and share your experiences, interesting applications, or typical (and less typical) problem and solution patterns with Sliding Notes.

Installation

To install, simply unpack the archive into wp-plugins.

Configuration

The plug-in relies on some CSS definitions which you’d definitely want to adjust to your theme:

• .hackadelic-sliderPanelThe class of the panel that contains the slider note content.
• .hackadelic-sliderButtonThe class of the slider button that opens and closes the slider.
• .hackadelic-sliderButton:hoverUsed to highlight the button when the mouse hovers over it.

A sample CSS is here (click on expand source to view, or copy to clipboard):

.hackadelic-sliderPanel {
	border: 1px solid #ccc;
	padding: 5px;
	-moz-border-radius: 1em; -webkit-border-radius: 1em;
}

a.hackadelic-sliderButton {
	border: 1px solid lightgrey;
	color: #B3960E;
	padding: 0 3px;
	-moz-border-radius: 1em; -webkit-border-radius: 1em;
}
a.hackadelic-sliderButton:hover {
	border: 1px solid #F0F0E0;
	background-color: #F0F0E0;
}
.entry .hackadelic-sliderPanel {
	background-color: #fcfcfc;
}
.textwidget .hackadelic-sliderButton {
	display: block;
	text-align: center;
	margin: .5em;
}
.textwidget .hackadelic-sliderPanel {
	background-color: #F0F0E0;
}

Integrate it into you own stylesheet, and use it as a starting point for further customization. I recommend using the brilliantly simple MyCSS plug-in, and modify it’s my.css stylesheet. Of course, you can also modify your theme’s style.css.

I decided against employing WordPress options for style definitions, simply because I didn’t want to add another database query at run-time, and add to lowering run-time performance. I might extend the plug-in to provide options other then pure CSS styling, if there’s justified request for it. Feel free to make suggestions.

Use-Cases

The most common use-case will probably be to add explanatory notes which you don’t want to obscure the main content with (by, say, putting them in parenthesis). As such, sliding notes are effectively a fancy substitute, or even a complement, for footnotes. Other use-cases will, hopefully, be shared on the Sliding Notes Showcase.

Also, there is a series of Sliding Notes advice articles:

• WordPress CSS Accordion Menu With Sliding Notes In 3 Easy Steps
• Sliding Notes HowTo's - Adding An Image To The Button
• Sliding Notes Self Aid - Overcoming Theme Footer Defects
• PassionDuo Theme Defect - And How To Fix It
• Sliding Notes Lessons - Beware of HTML Tags In Title

What’s New

Recent Releases

What’s In The 1.3 Version

This release is packed with features that greatly ease the integration into existing website styles and concepts, as well as the combination of different usage patterns on the same site.

• Many new shortcode arguments for easy integration into different website/usage concepts:
  • inline CSS styles
  • custom note types
  • auto-expanded notes
  • embedding shortcodes inside sliding notes
• Improved interoperability with other JavaScript/AJAX libraries
• Various cleanups and fixes

For details, see the release announcement.

What’s In The 1.2 Version

The 1.1 series had some difficult cross-browser issues, which is why the 1.2 series is again an almost complete rewrite regarding both, code and concept. Besides resolving the cross-browser problem, there are several other improvements in 1.2:

• Foremost, now all of paragraph formatting should be usable in sliding notes (ex. centered, right-aligned or indented paragraphs). Before, only default paragraph formatting was supported.3
• Sliding notes are widget-ready! Again. All you need to do is enable shortcodes in text widgets, and put the shortcode there.
• There are several minor fixes.
• The code base has been streamlined and improved.

What’s In The 1.1 Version

Basically, the 1.1 series is a complete rewrite:

• Switch from a buggy Shortcode API to “good old” Filter API. (See this post on that.)
• Improved handling of multi-paragraph notes, enabling the following features:
  • Note paragraphs can be individually styled.
  • Note paragraph styles can differ from surrounding paragraph style.

Note: The styling is done the usual way in the visual editor. There’s no extra UI for writing sliding notes (yet). There’s an example in the 1.1 release announcement.

Motivation

This plug-in was born out of a wish to have a sliding functionality in my blog similar to the one built into TiddlyWiki. My search for such functionality revealed only one serious candidate, SmartSlider, which nonetheless was not to my exact liking.» Besides, it tempted my programmers heart to implement a WordPress plug-in of own, so here was my chance.

Challenges And Points Of Interest

Dear reader, this chapter gets into some quite technical background details, knowing which is not necessary if you are only interested in using the plugin. If this doesn’t scare you, then please, read on. 😉

Challenges And Points Of Interest In The 1.2 Series

The approach choses in the 1.1 series has been to embed the note as nested paragraphs to the surrounding text. Unfortunately, some browers, like Chrome, did not like that at all. My first idea to work around this was to use a late post filter and replace P element with equivalently CSS-styled DIV elements, which all browsers can render, nested or not. Alas, it turned out that WordPress keept messing up the HTML structure of a post in unforeseeable ways, eating opening or closing HTML tags at will, so it was impossible safely replace the P tags and hope to still come up with valid HTML when the whole process finished. So again, I resorted back to shortcodes, simply because that seemed the only way that WordPress and I could stay out of each others way. As a “bonus”, it’s possible to use Sliding Notes in a text widget again (provided you’ve enabled shortcode processing there). Anyway, the final solution to the cross-browser issue was to put the note contents into independent DIV‘s, where the browser would render them to a DOM-tree at its discretion, and then move the thus created DOM part to the actual sliding note position after the page is loaded. This way, the browser-specific HTML-to-DOM processing is “taken out of the equation”, leaving only the necessity for DOM manipulations (which, I believe, are much more “portable” across browsers).

Challenges And Points Of Interest In The 1.1 Series

I had to revise the approach to overcome overlapping elements (see next chapter), for two reasons:

1. It did not cover paragraphs with styles properly.
2. Flaws in the Shortcode API came in the way of properly handling the paragraph issue anyway.

Instead, I refrained from using the Shortcode API altogether, and rewrote the plug-in as a content filter.

Challenges And Points Of Interest In The 1.0 Series

A particularly challenging matter was the fact that the mixture of TinyMCE and WordPress encloses each paragraph in <P>...</P> tags.4 This is XHTML compliant, but gets painfully in the way how content within the [shortcode]...[/shortcode] tags is processed. In this particular case, the content within the shortcode tags needs to be enclosed in a <DIV> or a <SPAN> HTML tag, in order to slide it as a whole. But when the content contains line breaks (or some element which would denote the end of the preceding paragraph, like a bullet list, for example) it leads to a weird constellation. In detail, the HTML as the plug-in sees it is:

<p>surrounding paragraph [shortcode]shortcode content start</p>
<p>shortcode content end[/shortcode] surrounding paragraph continued</p>

When the shortcode is substituted by a DIV or a SPAN, it results in a HTML like this:

<p>surrounding paragraph <div>shortcode content</p>

<p>shortcode content end</div> surrounding paragraph continued</p>

The resulting HTML would contain overlapping elements – clearly not a valid XHTML. Different browsers render such HTML in different ways, none of which may match the writer’s intention. The core problem here is that when the HTML contains overlapping elements, it cannot be represented by a regular tree data structure, which the X(H)ML DOM model is. A browser that works by first building a DOM model from the raw HTML page, then rendering it to the display, would need to “guess” the tree structure. Firefox 3 for example will implicitly close the DIV element at the closing </P> tag, and ignore the explicit closing </DIV> tag, effectively resulting in:

<p>surrounding paragraph <div>shortcode content</div></p>
<p>shortcode content end surrounding paragraph continued</p>

Interestingly, Internet Explorer 7 seems to correctly process (at least simple) overlapping constructs (but don’t take this as a browser recommendation 😉 ). To circumvent this problem, the plug-in uses a late post-filter which transforms <P>-enclosed paragraphs (of the form <P>content</P>) into old-fashioned paragraph breaks (of the form content<P></P>, to be exact). The transformation is performed only for those posts and pages that actually contain a slider shortcode.

Limitations And Incompatibilities

Currently, I know of these – easily resolvable – incompatibilities:

Incompatibility with WP-Footnotes

The WP-Footnotes plug-in seems to have trouble when the slider shortcode is used within a footnote. The slider displays and behaves correctly in the footnote itself, but WP-Footnotes displays part of the slider-generated HTML where the footnote reference mark should go normally. To resolve it, you need to increase WP-Footnotes’ priority to above 10. The option can be set at the bottom of the Settings?Footnotes page in your WordPress admin panel. Here is an example:5 ? This footnote reference mark is not spoiled, because I changed the aforesaid priority.

Incompatibility with Some Themes

Some themes erroneously omit to trigger the so-called wp_footer action. I’ve submitted a defect description and a workaround on a separate post.

Current Implementation Limitations

The CSS definitions must be manually integrated into the site’s stylesheet(s). This is a deliberate decision: For a typical blog site, the CSS definitions are unlikely to change, or change frequently, so it is basically a one-time effort for the administrator. Instead, the hereby avoided performance decrease from extra queries on each page view, adds to the benefit of your (hopefully many) blog visitors.

Showcases And Feature Requests

I welcome everybody who takes pride in his particular application of Sliding Notes to share his experiences, as well as typical (and less typical) problem and solution patterns with Sliding Notes on the Sliding Notes Showcase. If there’s a feature you’d like to suggest for Sliding Notes, feel free to add it to the Sliding Notes Wish List.

Summary

As with all my endeavors, I tried to keep things as simple as possible, while – as I trully hope – providing a useful and visually attractive functionality. Should there be problems or suggestions, please feel free to post them below. Cheers and happy sliding!

If you use this plug-in, please consider making a donation to support the further development. Donate whatever you feel appropriate. Any amount is appreciated. Thank you.

Please note: technical support will be provided to donators only.

1. As a former expert C/C++ programmer, I’m allowed to say that. Simply because… Well, simply because I know what I’m talking about. [↩]
2. This is not a limitation of the plugin, but rather a limitation of how WordPress processes shortcodes: WP does not allow nesting the same shortcode. [↩]
3. This was also the goal of the 1.1 series, alas… [↩]
4. I first thought it’s a TinyMCE behaviour, but it turned out that it’s a WordPress filter that causes the effect. [↩]
5. This is a a WP-Footnotes coexistence test,» examine the footnote mark above. [↩]

Sliding Notes Plugin Is Here

After some warm-up time with WordPress, I decided it’s about time to write a WordPress plug-in.

Not that I’ve been keen to program in another half-backed spawn of C++ (the mother of all programming language abominations ;-))1 with all the curly braces and clumsy syntax. But, the itching in my fingers was stronger then that.

So here it is! Ladies and gentlemen, I proudly present: The Slider Shortcode! An easy way to add sliding notes» to your WordPress content!

Read the whole story on the plugin homepage.2

1. As a former expert C/C++ programmer, I’m allowed to say that. Simply because… Well, simply because I know what I’m talking about. 🙂 [↩]
2. Note that comments are closed on this post in favor of the plugin homepage. [↩]