Help Info Overhaul

The “Help” info finally gets overhauled after arguably being kind of ignored since the initial public beta release.  It is going to be replaced with something similar to the Guided Tour “Bubble” presently being used on the Ryuzine Machine Demo.  The feeling is that the existing document in the “Help Panel” is just too much – it’s the proverbial “wall o’ text” that, frankly, nobody is probably ever going to read through.  The “Bubble Help” version is in the early stages, but it looks like it will only consist of about a dozen sentence-long descriptions and, of course, will bounce around pointing at what it is talking about.  This will be more in line with how mobile app help should be done – they should generally be pretty intuitive, and where you do include help it should be brief and to the point.

CSS Customizable Animations

The control bar is going to be switched to the same animation method used by the phone “navigation bar.”  This will fix some minor issues with it in certain specific browsers, but it also (potentially) opens it up to being more configurable – possibly with a method allowing publishers to add their own custom control buttons/bars to it.

The built-in Lightbox items will also have their animation method changed with the goal being the ability to easily set different animation methods.  Currently the “zoom in/out” animation is hard-coded.  The new method will make that configurable in the stylesheet.

Webcomic & Easel Support (Ryuzine Press)

The Ryuzine Press plugin for WordPress, in addition to the existing support for blogs using a ComicPress theme and ComicPress Manager, will also support those using the “Webcomic” plugin and either the “Inkblot” or “Archimedes” themes; and finally supports “Easel” themes as well (though it requires a tiny hack to one Easel file). That means support for all three of the most popular WordPress webcomics systems!

Dropped Support

As much as I don’t like to drop backwards-compatibility for anyone this next version will officially drop all support for Safari 3.x.  Ryuzine has never worked properly in this version of Safari and with this upcoming release and the previous release it worked in testing with the source code script but stopped working when using the obfuscated release script.  Realistically almost nobody is going to still be using – and really should not be still using – this version of Safari anyway.  On the off chance they are, they’d have to disable CSS and Javascript and view it as a straight HTML page or they’ll be stuck on the splash screen.

Maintaining backwards compatibility with ancient browsers really isn’t worth the effort, but I’ve tried my best to accommodate them where possible.  As I move forward to the release of Version 1.0, however, I’m going to be focusing my efforts on browsers most people are actually using – typically the current released, the previous major version, and I’m also testing in beta versions.  Expect support for other legacy desktop browsers to also fall away in future releases.  I’ll try to still keep things working in older mobile browsers since users often cannot update those, but there’s really no excuse for using an outdated browser on your desktop system unless the system is also a museum piece as well.

Other Additions

Multiple In-app Bookmarking is being considered.  This would actually be pretty easy to implement since the original (pre-release) version that introduced the bookmarking tool actually did set multiple bookmarks.  Ultimately, though, it was altered to only set and retrieve one bookmark per Ryuzine publication because multiple bookmarking really demands a management panel.  Well, creating that panel and adding the multiple bookmarking is back on the “To-Do List.”

Ryuzine Machine will also likely gain some additional options to bring it more in line with the options in Ryuzine Press Plugin for WordPress, so there will be pretty much no learning curve moving from WordPress to Ryuzine Machine authoring and vice versa.

Issue-specific stylesheet gets an update to accommodate “Retina” iPad screens.

The “Localization” plugin will also need to be overhauled in order to work with the new help content.

The “Font” control will do more than just adjust font size up and down.  Color scheme options will also be added: Default (black text on white), Sepia (dark brown text on light tan background), and High Contrast (white text on black background).  This seems pretty standard in e-reader apps so Ryuzine should probably follow that convention.

The add-ons from 0.9.4 should all be compatible, but themes for 0.9.5 may need to be updated to accommodate the new controls/options. When will that be?  I’m not going to predict.  Also, keep in mind these are the ideas for improving it, some of which are already under way, but there’s no guarantee all of these changes will be in 0.9.5.  Well, back to coding. . .

I found a couple of posts (post 1, post2) that sent me about 90% in the right direction, the first told me how to add TinyMCE to the meta boxes, the second showed me how to add the mode switches, but I absolutely could not get the jQuery events to attach to the “Visual” and “HTML” tabs, no matter how low I placed the script in the page or if I used the recommended jQuery “ready” function.  Thankfully, it turns out jQuery is not needed for this to work.

First things first, I added this code, which places the tabs above and wraps my textarea in a named DIV:

Yeah, yeah I know I’m using dreaded evil inline javascript, but it solved my problem with jQuery missing the opportunity to attach event listeners.  For each Meta Box I’d just advance the number from 1 to 2, 3, 4, etc. (note that we do not start with zero – the zero TinyMCE editor is the regular one).

The jQuery stuff did work for adding the TinyMCE controls to the Meta Box text areas.  Then I just added a regular ol’ Javascript function for swapping the tabs and turning the rich text editor on and off.  This goes in the footer of the page because it MUST come after TinyMCE has initialized, and the priority of “99″ helps do that:

By now you’ll see they are functional, but they look awful!  We need to add a little CSS to the head of our admin page to fix it:

And there it is!  Multiple instances of TinyMCE on multiple Meta Boxes, with tabs above each so users can toggle between “Visual” and “HTML” modes just like they are used to doing.

http://www.farinspace.com/how-to-create-custom-wordpress-meta-box/

http://shibashake.com/wordpress-theme/add-metabox-custom-post-type

http://codex.wordpress.org/Function_Reference/add_meta_box

I think the main reason I was having trouble wrapping my head around it all was because the samples use so many similar names for each part I wasn’t sure what was referring to the post_type, the database field, the input variable, or the input name.  Hopefully I can clear it up for anyone else who’s also struggling with implementing their own Meta Boxes.  Also the samples seem to assume you’re only adding ONE custom meta box, but I wanted to add three.  My specific application is to add these to the “edit.php” page for a custom post type, but the principles would also work if you were adding custom meta boxes to the regular post or page editors too.

I’m going to assume you’ve already set up your Custom Post_Type, and for my examples I’ll be using a custom post_type of “magazine.”  Now I will concentrate on just the Meta Box part.  First we need to create a function for each of our Meta Boxes:

Then I create two more functions, where the only things I change up are “first” for “second” and then “third.”  You’ll notice that my meta content name in the example above is “_myfirst” rather than “myfirst” (like you’d probably do with meta in a Custom Field).  I believe opening with an underscore was recommended for post meta data because some databases are prefixed with “ci” and if you fire up PHPadmin and look at the post_meta tables in the database you’ll notice all the built-in meta entries start with an underscore, so at the very least we’ll be consistent.  So, if you’re following along our functions should now look like this:

Those will only allow users to input the data.  We need to be able to collect it, authenticate it, check user permissions, and write the data into our database with the post.  We do that with our “save” function:

However, if you’ve been hopping back to look at your post editing page you’ve yet to see anything change.  That’s because we haven’t actually fired these functions off yet!  We need to do the typical WordPress thing of functions calling functions:

In case you’re wondering your options for “position” are “normal,” “advanced,” or “side” and the “priority” options are “high,” “core,” “default,” and “low” (note that none of these will position the meta box above the regular editing window).  Also, if you were doing this for the regular post or page editors you’d just change the custom post_type name to “post” or “page” respectively.

Now we just need to do two last little things.  We need to run that function above, which in turn runs all the functions for the meta boxes injecting them into the page, and then we need to set up a trigger for the save function:

That’s it!  Three custom meta boxes appended to the edit post just below the regular editing window (if your Custom Post_Type supported it), and ONLY appearing on the custom post_type “magazine” editing page.

I went on to add the TinyMCE Rich Text Editor to the Meta Boxes with functioning “Visual” and “HTML” edito mode tabs.  That code is in another post: http://www.kmhcreative.com/labs/2012/02/15/wordpress-meta-boxes-rich-text-mode-tabs/

But the problem with this is it is an “all or nothing” deal.  You either show all shortcodes or hide all shortcodes.  What if you want to selectively show some shortcodes and hide others?  Let’s say you have three custom shortcodes you created.  As you may have found out, if you don’t register your shortcodes in the functions.php file then the actual [shortcode]…[/shortcode] code itself will show up in your posts, which you obviously don’t want.  Let’s say we have three custom shortcodes:

[shortcode_a] you want to show pretty much everywhere, except on your home page.

[shortcode_b] you ONLY want to show when posts are being shown in your archives.

[shortcode_c] should show up on both single posts and on your home page, but not in archives.

Ok, so how would you do that?  Well one method is to set up your shortcodes in functions.php (or your plugin functions) with conditional statements checking the current page:

That sort of structure will handle most of your conditional shortcode needs. Also, if you wanted it to return the content of the shortcode without the wrapper you could make the “else” paret read “$C= $content” and it would just echo back whatever is in between the [shortcode]..[/shortcode].  All you need to do is swap out the conditional tags in the “if” statement and those pesky shortcodes will dance to whatever tune you play.

But what if they don’t?  I ran into an issue with a custom post type where, because it wasn’t a “template” or an “archive” but a post itself AND it was pulling in other posts in the same category, the conditional function logic above wouldn’t work!  If I used the shortcode in the body of the custom post itself, then adding something like “mytype” == get_post_type()  to the “if” statement worked, but ONLY for the shortcodes actually attached to the custom post itself.  If I tried to use that same shortcode on a regular post being displayed within the custom post, so far as WordPress was concerned the post_type was “post” and NOT “mytype.”  I had a secondary problem that I needed to run two loops with the custom post_type content, and in the first extract only [shortcode_a] content but not [shortcode_b] and in the second loop vise versa.  Which meant I needed to redefine the conditional selection mid-page as well.  So, how would I go about doing that?

Well, as it turns out you aren’t restricted to placing your shortcode functions in your functions.php or plugin functions files.  They CAN be placed in code on the front-facing template pages, which means we can define or redefine shortcodes on a local basis!  I know I was talking about doing it in a custom post_type page, but you can actually do it with any of the front-facing pages:

In functions.php:

Ok, what that does is is creates [shortcode_a] so it works by default.  [shortcode_b] and [shortcode_c], however, are set to return nothing by default (this prevents the actual bracketed code from showing).  Now, for each of the aforementioned conditions we add shortcode functions to the pages. . .

In index.php:

Now on the Home page [shortcode_a] content is hidden, [shortcode_b] is still set to be hidden by functions.php so we don’t need to change it, and [shortcode_c] content will now show up.

In my single.php file:

In this case [shortcode_a] will use the default “include” setting in functions.php, [shortcode_b] will also use the default “exclude” setting in functions.php, so we only need to “include” [shortcode_c] and our single posts will now show content from both shortcodes “a” and “c” but not “b.”

In my archive.php file:

Here [shortcode_a] will appear because that’s the default setting in functions.php, [shortcode_c] will not be included because that is the default setting in functions.php, so we only need to “include” [shortcode_b] content.

And, lastly, you can redefine them “on the fly” in the same page if you repeat the loop and want to change your selectors.  Just switch the “add_shortcode” to the “include” or “exclude” function as needed.

Then I created a custom shortcode intended to run Javascript code that is ONLY loaded on pages of my custom post_type.  So the shortcode is basically useless everywhere else on the blog, and consequently I don’t want it to show the custom shortcode wrapper around that content.  In fact I want the user, in my plugin’s admin page, to decide whether they want the shortcode content to show up at all when the regular posts are viewed outside of my custom post_type.

My first thought was to simply use Conditional Tags to limit showing the shortcodes to my custom post_type pages.  It works if the shortcode is in the body text of the custom post_type page itself, but if the shortcode is inside a regular post being displayed on a custom post_type page it doesn’t work (because as far as it’s concerned it is “in” a regular post type, not a custom post type).

I went off searching for other conditional tag and filtering options and the search wasn’t bearing any fruit.  However I did stumble upon some posts about using a conditional tag to set a global variable and then using the variable as a stand-in check inside the shortcode function.  With that I was able to only execute the shortcode function on my custom post_type pages except then the actual shortcode text (i.e., [myshortcode]….[/myshortcode]) would display around the content on every other part of the blog.  Yuck!

Next I tried moving my shortcode function and registration off the plugin.php page and into the single-custom.php which also worked in the sense that the shortcode ONLY processed on my custom post_type pages, but again left the actual shortcode code text in the post everywhere else.

Then it occurred to me that maybe I could declare how the shortcode works generally in my plugin file and redefine it in my custom page file.  So in my plugin.php file:

function my_custom_shortcode( $atts, $content = null ) {
 return $content;
}
add_shortcode(‘myshortcode’, ‘my_custom_shortcode’);

You might wonder “What is the point of that?!”  Well, it prevents the actual shortcode code (the stuff in square brackets) from showing up on pages elsewhere on the blog.  Essentially it is a shortcode that just echoes the content of the shortcode back to the page untouched.

Then in my single-custom.php page I redefine it locally:

function my_shortcode_in_page( $atts, $content = null ) {
extract(shortcode_atts(array(
‘link’ => ‘#’,
‘id’ => ”
), $atts));
$wrapped =’<div class=”shortcode” id=”‘.$id.’”><span class=”shorty”><a href=”‘.$link.’”>’.$content.’</a></span></div>’;
return $wrapped;
}
add_shortcode(‘myshortcode’, ‘my_shortcode_in_page’);

Now it shows the  unaltered content in regular blog pages but shows my shortcode wrapper on my custom post_type pages – and ONLY those pages!  But then what if the $content is something that, itself, is kind of useless or odd on pages that won’t use the shortcode?  For example if you use an image thumbnail for the shortcode link it wouldn’t be a link at all on other pages, so why have it there at all?  So I added a field to my plugin’s Options page to let the end user decide if they wanted [myshortcode] content to be hidden elsewhere on the blog.  All that does is set up a variable in the database that is part of the plugin initialization (it checks for the value and sets the global variable).  Then the function in my plugin.php only needs a simple check:

function my_custom_shortcode( $atts, $content = null ) {
if ( $hide_myshortcode === “1″ ) {
// do nothing //
} else {
return $content;
};
}

Now, if the user set $hide_myshortcode variable to “1″ the shortcode returns nothing, which hides whatever is inside the shortcode tag.  If the variable equals some other number (the Options page toggles it between “0″ and “1″) then the content inside the shortcode is returned.

If you head on over to ryumaru.com you can demo and download version 0.9.3 of the “Ryuzine” and “Ryuzine Machine” web apps.

This update represents a significant performance boost to the reader app and some new features/options in the authoring app:

Ryuzine Web App

• Views preference now persistently stored in a cookie file so it automatically restores the last used view setting.
• Can now send custom themes to BlackBerry tablets and Windows Phones.
• Send different themes to Android 2.x and 3.x+
• +300% faster loading time
• 30-50% reduction in memory usage (depending on content)
• 26% reduction in main script file size
• Improved stability on iOS platform
• Android 2.x page turn bug fixed (requires Android is not spoofing User Agent string)
• “Widescreen” Android phones now correctly fill content in landscape orientation
• Fully compatible with 0.9.2 Themes
• Compatible with existing 0.9.2 Ryuzine HTML files*

Ryuzine Machine Authoring App

• 19% reduction in main script file size
• Simulator devices can now be skinned
• Simulator devices can be zoomed in/out
• Ability to add Custom Device profiles to the configuration file
• Option to over-ride WYSIWYG loading even on supported browsers (if you prefer to hand-code everything)

Now for a little development background on this update.  I was at an electronics store recently where I was playing around with both the iPhone 4s and iPad 2 and was disappointed to see Safari would often crash when loading my apps.  Clearing the browser cache and making sure no multi-tasking was going on helped, but iOS typically just kills any process that uses “too many” resources, including Safari, rather than letting one rogue process bring down the whole OS.  That makes sense I suppose, but if you go check the user forums at Apple’s web site you’ll see some complaints about Safari crashing even with relatively simple “rich” web sites.  Obviously how iOS handles resource issues is out of my hands, but the app I’ve built is not.

So I set about trying to find things that would reduce the resource footprint.  What I hit on is actually something you’re not really supposed to do – at least according to various web design/developer resources I’ve read over the years:  continuously reflow the page.  Yep, you’re not supposed to constantly be changing the styles and causing CSS to reflow, but it turned out that was exactly the medicine my web app needs (and leads me to believe some of the “rules of thumb” may be a bit outdated concerning how modern browsers adapt).  What I ended up doing was completely rewriting the page-turning function so it selectively displays the contents of an individual Ryuzine page (flips between display: none; and display: block).  By default the contents of all pages (except the cover) are set to “display:none;” so when the web app first loads it only grabs the contents of the cover page, rather than ALL the pages (as it did up to 0.9.2).  As you turn pages it sets pages you are going to see to “display: block” which – in the mobile browsers in which I tested it – caused a request to the server for any image on that page.  In other words it didn’t load them with the page initially, it requests them a la carte.   Pages you’re not seeing are set back to “display:none;” and removed from the page flow.  Any images are still in the cache, of course, so going back to that page pulls them from there, but the real key seems to be to take it out of the page flow.

What I’ve learned in trying to optimize my web apps is that Javascript isn’t the problem, as the “engine” for that keeps getting faster and better in pretty much every browser release.  It’s the CSS Renderer, which is only now starting to get the same sort of performance-related attention,  that tends to get overwhelmed when you layer a lot of CSS effects (particularly CSS3 stuff like shadows, gradients, and rounded corners, and especially when they are literally layered with z-index one atop another).  Thus, taking objects out of this flow when they aren’t needed makes the CSS renderer work more efficiently.  So despite the fact I’m making it reflow constantly it has fewer objects to reflow so it becomes a net gain.

Now, this wasn’t true in older browsers.  Constantly overworking the CSS renderer was bad and some older browsers request everything from the server (everything in the stylesheets – even if it was for a different media-query case – and everything in the page even if it was set to “display:none;”) which obviously would increase load time, request a lot of items you may not even use, and hold a lot of data in memory you may not need.  It’s easy to see with misbehaving browsers in the Days of Yore how you wouldn’t want to put all your media-query cases in a single stylesheet, how you’d want to dynamically write in case-specific content (ideally from the server-side) as much as possible, and have it render the CSS only once.  Thankfully, in my testing across modern browsers, these issues all appear to have been addressed.  For example, to see what items were actually being requested from my web server I opened Safari’s “Activity Window” and also looked at my web server log file and determined that Safari 3.x would pretty much request every image for every media query while Safari 5 does not.  Which is why it is good to go back from time to time and fact-check the “rules of thumb” and see if they still hold true or not.  What it boils down to is I’m giving the CSS renderer more to do with fewer objects instead of more to do with more objects, which makes the performance enhancements pretty obvious when I put it that way.

Ryuzine Web App

• Added more keyboard controls for panels and add/remove in-app bookmark
• Added support for BlackBerry Playbook (BB Tablet OS 1.0.7)
• Two-Page Spreads and Portrait views now available in Legacy Browsers
• Added Internet Explorer 7 support (requires legacy_ie addon)
• Page numbering position changes with binding/orientation
• Phone Nav Page Count Limit bug fixed.

Ryuzine Machine Web App

• Pop-Out option for Simulator (fills browser)
• Added Output Options Panel
• Automatically corrects for uneven page counts
• Fixed bug that prevented custom styles not in “thisissue.css” to be cleared by alt views.

This is a major code overhaul that does away with the “slider” at the bottom of the player and the legacy “mouse over image map” method. Users now interact with OVR images directly, hold/touch dragging left and right to rotate the object without it resetting (rotation always begins from the last position). Better compatibility with modern browsers and touch-enabled devices, but less compatibility with legacy browsers (particularly Opera).

With this version scripts and styles need to be updated, images do not.

1. Added ability to target webOS devices with custom theme
2. Set up optional features as “add-ons”
3. Fixed Share bubble for third party widgets
4. Added Configurable Zoom & Pan capability for mobile devices
5. Added User Configurable Options Panels with Cookie Preference storage
6. Meta Viewport now added dynamically based on device and settings
7. Rewrote page animation function to disable it for legacy browsers for better performance
8. Rewrote page flip function so links can contain anchor targets
9. Added ability to share link to specific page within magazine
10. Added In-App Bookmark feature
11. Separated page curves from themes as optional add-on
12. Switched UI animations from JS to CSS so themes can now change animation effects
13. Added more keyboard controls
14. Added support for Windows Phone 7.5 devices

Ryuzine Machine Web App

1. Touch-enabled web app so it can be used on mobile devices
2. Added meta viewport data compatible with webOS
3. Added Toggle Button for Editor Panels
4. Added code to hide disabled toolbar buttons in Text Edit mode
5. Custom Device Profiles now persistent (stored in Cookie)
6. Option to import custom stylesheet for “My Styles” panel
7. Option to change default issue-specific style
8. In-Page Styles can now be preserved

That certainly doesn’t mean iOS devices are any less challenging! The real underlying problem is that the devices LIE about the screen size. They can lie because the pixels reported by the browser are not actual device pixels. There’s this little thing called a “device independent pixel” (or “dip”) and it has nothing to do with the “dots per inch” (or “dpi”) by which I mean the actual pixel count of the screen. The former is the “pixel density” and the latter is the “pixel resolution.”

Furthermore mobile devices tend to do a lot of scaling of web sites that desktop browsers do not. For example, if you look at a web site that has no coding in it aimed at mobile devices then iOS devices will zoom the page out and pretend the screen (regardless of how big it actually is, the resolution, or the pixel density) is 960 pixels wide. On an iPhone 3G it is actually 320 physical pixels in portrait and 480 in landscape, on an iPad it is 768 physical pixels wide in portrait and 1024 in landscape. But either way it will pretend that it is 960 pixels wide. However, if you add a viewport tag and tie the width to “device-width” you STILL aren’t going to get the actual physical pixel width. An iPhone will report 320 pixels wide in either orientation and an iPad will say 768 in either orientation. So they’re only truthful about device-width in portrait orientation.

So you think you’ll address that problem with media queries in your stylesheets? Nope. Even with media query conditions for widths of 1024 and 768 you’ll only ever see the one for 768 used because the device is lying about its width in landscape mode.   You can try to create two different media queries for 768 pixels by adding (orientation: landscape) to one, but the viewport will STILL only be 768 pixels wide (because that’s the fake “device-width” it says it is) so you’ll see your 1024 layout sure enough, but if you rotate from portrait to landscape it will be slightly zoomed in and the remaining 256 pixels will be off the right of the screen.

You could also try forgetting about the whole “device-width” thing since it’s a lie and just change your meta tag to:

<meta name=”viewport”  content=”initial-scale=1.0,minimum-scale=1.0″ />

Which will allow the page to use your media queries for 768 and 1024 but still causes the zoom-in problem when rotating from portrait to landscape.  You can zoom out, of course, to see the whole width but this is hardly a desirable user experience.

Ok, so how do you get it to show the different layout for 1024 pixels wide AND zoom out to show it all on changing orientation?  Well, you apparently have to sacrifice user functionality to do it.

<meta name=”viewport” content=”initial-scale=1.0,minimum-scale=1.0,maximum-scale=1.0,user-scalable=no” />

That will force it to zoom out, but it also means users can no longer pinch/spread zoom in/out.  The “user-scalable” part is kind of redundant since the maximum-scale is set to 1.0 anyway, but it drives home the point that user functionality is being sacrificed (and if I recall Android will ignore the rest if that isn’t there).

A better option is to accept that your 768 pixel layout will be used in landscape mode too and just design for that, ideally by using a fluid layout that can just adapt to whatever width the device is going to insist it has.