Reader 2.0 - Tizra/Tizra-Customer-Tracker GitHub Wiki

The 2.0 reader, like the earlier reader, uses jQuery mobile as its UI framework. This gives a modern look, Ajax prefetching and page transitions that improve performance, and nice set of UI elements. It also imposes some limitations, so be sure that you read the jQuery Mobile documentation. Currently the reader uses version 1.3.1 of jQM, and version 1.9.1 of jQuery.

The new reader, unlike the previous version uses more jQM built-in widgets and less custom Javascript.

Aside from a more modern version of the javascript framework, and a certain number of bugs squashed, the new reader has significant performance improvements due to greatly reduced data transmission. Link targets that can highlight regions on the page are now implemented. A new lightbox feature makes popup illustration expansion a snap -- and can be customized to create other kinds specialized presentations for other kinds of attachments like flash and HTML. The look, especially in the tables of contents, has been streamlined to be a bit more readable.

create a new true/false design property called useBetaReader, and set it to true.

The list of downloads now includes all attachments, including Free Attachments if there are any. The order of items is in terms of specificity and relevance, with content downloads, if present, taking first place. The contents of the downloads panel contain:

• Local Excerpts These are any excerpts that contain the current page. They are listed directly after the global header, with no additional header added to them. This is marked with two classes: t-attachment-list (this applies to all attachment lists) and t-downloads-list (which applies only to PDF excerpt downloads).
• All Excerpts This is a list of all the excerpts for a book. It will contain duplicates of any dominating excerpts. Container div is marked with t-attachment-list and t-all-downloads-list. The default rendering for this list is as a collapsible list (like tables of contents), as it can be long.
• Local Attachments These are any attachments for the Local Excerpts. The contents are unordered lists, with the style t-attachment-list on all lists. If different lists are to formatted differently, there is an source-specific class also attached t-${sourceName?lower_case}-list -- for instance t-attachments-list, t-freeattachments-list.
• Document Attachments These are the things attached directly to the document itself. Styles attached to these lists are the same as for Local Attachments
• Custom external URL prefix for a Source You can add a prefix for all links stored in a particular Source, by setting a design property. setting a parameter like: ${sourceName?lower_case}-url-prefix, will cause URLs referenced in that source to be prefixed by a string. For instance, defining a parameter like attachments-url-prefix would put a string in front of all the URLs the attachments area. This could be used if you need to link to externally-hosted items, but make it possible to change the base URL at a later date.

The addition of more attachment sources means that the design parameters used to override the default headers have changed. The list of parameters is now:

• downloadHeader is still the main header for the download block (H2)
• pdfDownloadHeader is the header for the list of all Excerpt downloads for the current publication.
• ${sourceName}Header Each type of attachment has its own default header and override parameter, for most sites these will be the AttachmentsHeader and FreeAttachmentsHeader Note the case and the lack of spaces.
• readerLogoLink if defined, this design parameter contains the home page link that should be included in the reader header. The default value is "/" the site home page. If the link is to a page within the Tizra-hosted pages, you should treat it like other intra-site links and use a URL that does not specify the server name. This way the link will also work properly on the staging and test sites. Of course, this does not apply if the appropriate home page is hosted elsewhere.

Custom markup elements in the reader can now be uploaded and managed as files. If the customCSS design parameter is a file parameter, it will be linked and downloaded as images are. This improves browser rendering speed by taking advantage of the cache. It may also make for easier site development with web design tools that can override a particular style sheet file during editing.

Don't forget to set the CSS content-type. As with graphics that cache timeout for CSS files is very short when you are on the staging or test site, but the live site may require a refresh before style changes take effect.

The new readerCustomScripts parameter can be defined, and the relevant javascript will be loaded into the reader, following jQueryMobile initialization and the Tizra reader initialization. Remember that the reader is a controlled environment where Tizra is managing the overall interface structure and scripting environment, for user interaction and performance reasons. Be careful in your scripting. The reader scripting and markup may change significantly in subsequent releases (as it already has), and bug-fixes or performance adjustments may lead to small changes at any time. Read the jQuery Mobile docs carefully if you are changing the reader, and try to avoid tricky overrides of the current behavior.

Link attachments and links within a PDF (see Customized-Links-In-PDFs) can now have values of the rel link attribute specified for them. Certain rel values have predefined meanings to Tizra. Other values can be used to activate special handling of link targets by means of javascript. Values that are currently significant to Tizra are:

• lightbox It is assumed that links with this attribute are links to images, and that the URLs are suitable for placement in an img tag. When clicked in the reader, a lightbox link will create a jQuery Mobile popup for the image and expose it. The Title attribute of the link, if present, will be used as a caption for the image popped up. The popup can be dismissed by clicking outside the image, but also has a close box for users who prefer that. The caption should be styled to a reasonable max-width if long captions are likely. There is currently not a way to specify the size of an image in advance, and so that popup will not be placed until the image has loaded (and the size is known), or until the load has failed (in which case the browser's default "broken image" will be used).
• external This rel value is used in the default jQuery Mobile fashion, to indicate a link that should not be loaded by Ajax linking. This should be be used if you want to load an external link into the current window.
• nofollow This rel value, used to signal search engines will never handled specially for display.

If you use another value for the rel attribute, it can be used to trigger a custom jquery widget (generally a popup), containing an iframe or other custom markup for interacting with an HTML quiz, video or Flash content, etc. That single element must be updated with the information from the link before it is activated. This is done by a javascript function called by the reader.

Special rel processing happens when a link with a rel attribute and the t-tizra-link class appears on a reader page (the class t-tizra-link is added to download links, as well as content links extracted from a PDF). To process such a link, a search is made for the element on the current page with id equal to the value of the rel attribute. (As noted above nofollow and external are ignored).

Once the link is clicked, a search is made in the current page for an element with an id equal to the value of the rel. For instance the standard rel="lightbox" behavior is linked to an element with id="lightbox". These elements must be initialized with a setup function, which is responsible for copying the relevant link information into the markup, before the link is activated. It is also responsible for setting any properties on the trigger link so that it will function properly. The element setup function is called with a javascript record containing the fields url, title, and trigger.

The href of the triggering link will have been changed to the hash value before your setup function is called, so that each trigger link will be properly associated with the target.

The popup element itself can be put in the custom markup area, along with the header, as it will not be visible or otherwise affect the formatting. This is the markup for the built-in rel="lightbox":

<div data-role="popup" id="lightbox" data-position-to="window"
			data-transition="fade" class="t-lightbox">
	<a href="#" data-rel="back" data-role="button"
			data-theme="a" data-icon="delete" data-iconpos="notext"
			class="ui-btn-right">Close</a>
	<img />
	<h2 class="popup-title"> </h2>
</div>

The setup script must added to the element at the correct time. This code template shows the, from the default lightbox implementation, should serve as a template:

$(document).on("pagebeforecreate", function (event) {
	var page = event.target;
	// In jQM the page is an element in the "real" page. That means you must use it as a search context
	// for all selectors, even ID selectors.
	$('#my-rel', page).each(function(index, relElement) {
		// Store the setup function as a data attribute on the "main element"
		// if you prefer to define the function separately, you could do that.
		$(relElement).data('setup', function(data) {
			// setup markup for my-rel, using jQuery
			
			//Set any attributes you need to on the trigger, generally 'data-rel', e.g. 
			// $(data.trigger).attr('data-rel', 'popup');
			
			// Return true if your markup wants to continue normal jquery event handling
			// for the click, which will normally activate the UI element whose markup just changed.
			return true;
		});
	});
});

You may find the event handling aspect a bit puzzling. Why would you ever return false? The sufficient answer is that this is really just an event handler, and you might have to do something more complicated. Here's an example, from the reader implementation. The setup function for the original image lightbox looked like this:

function (data) {
	// modify the children.
	$('img', relElement).attr("src", data.url).height('auto').width('auto');
	$('.popup-title', relElement).html(data.title);
	
	// set the trigger link to activate a popup
	$(data.trigger).attr("data-rel", "popup");
	
	// continue click processing now that the right image is linked
	return true;
}

This turned out to be buggy, because even if an image is cached the browser does not update the size of the img element right away when you change the URL, so the popup was not properly positioned in the window -- the first time it was popped up. So we have to handle the action ourselves.

The modification was to abort the normal click processing and activate the popup only once the image had loaded, leading the following (code). Notice that we don't have to set a data-rel on the trigger element, as we are handling the click entirely ourselves:

function(data) {
	$('img', relElement).attr("src", data.url).height('auto').width('auto');
	$('.popup-title', relElement).html(data.title);
	
	// Since we updated the image we can't show it until it's either loaded (or failed to load).
	// in either case, we just activate the popup, showing either the image or the browsers "broken image" icon.
	$('img', relElement).on({
		load: function() { $(relElement).popup("open");},
		error: function() { $(relElement).popup("open");}
	});
	
	// tell jQuery not to handle the click further.
	return false;
}