Quickstart template - Tizra/Tizra-Customer-Tracker GitHub Wiki
The Tizra Quickstart template is designed to support "simple setup" scenarios out of the box:
-
pervasively responsive and usable on mobile devices
-
colors and nav configurable in site properties
-
per-user bookshelf supports books, excerpts and collections
-
redemption codes available via properties
-
search app with default config
-
tested on Chrome, Firefox, Safari, Edge, IE11
v2.8 — better thumbnails
-
Offer an option for lower-profile homepage headers #68 - reduced extraneous whitespace around intro text and overall
-
Improve UX for video access #85
-
In 2.7.4 Cart, Buy Now link is small and Remove button is BIG #97
-
Clean Up Virtual Collection Browse? #100
-
Logo Link presentation property is empty #104
-
Register link not obvious on registration pop-up #105
-
Fixed a display issue with the hamburger menu on mobile. (no GitHub issue)
-
Search: Query Term Quoting search #174
-
Cubchicken: new approach to thumbnail zooming cubchicken #453
v2.7.3 — YouTube
-
Make jumbotron tinting configurable #60
-
Add YouTube support #87
-
Use oembed-proxy for all case #86
-
Search hits under wrong ToC heading search #168
-
Browse blocks missing video thumbnails search #165
-
EnableIE7Compatibility: No
-
Enable logical page numbers: Yes
-
Generate old-style Tizra markup: No
-
Support old
<div class="wrapper">: No
The Tizra Quickstart template provides three configurable colors in site properties:
-
colorPrimaryis used for buttons and links (except in the nav) -
colorAccentis used for the short accent line under headings -
colorNavLinkis used for buttons and links in the nav
In the typical configuration, colorPrimary and colorNavLink will be set
to the same color, though this isn’t required. For example, here are the
Tizra default colors:
The template calculates hovers and text colors automatically based on the site properties you provide. For example, button text will be white on a dark button and black on a light button. The calculation uses the YIQ colorspace to account for human perception of color contrast.
|
💡
|
If you’re getting a button text color that you didn’t expect, it might
be that colorPrimary or colorNavLink is on the edge of contrast and
accessibility. Try using this tool to make small adjustments to your colors
until they work as you’d like: http://contrast-finder.tanaguru.com/
|
The jumbotron image is configurable using the Jumbotron site property.
For best results:
-
the image should have a landscape format, at least 3:1 ratio
-
the image should be at least 1920 pixels wide to accommodate retina screens
-
the image should be a jpeg rather than png
Note that the full height of the image will always show, but the scaling algorithm will crop evenly from the sides for mobile devices. See how the default jumbotron image is wide on desktop and narrow on mobile, but always full-height:
| Desktop | Mobile |
|---|---|
|
|
The text overlay on the jumbotron is configured using the Home Page Intro
site property. If you need to override the text color, the easiest way is
by using the HTML editor widget to directly set the color you want.
|
💡
|
For sites without a jumbotron, there’s a substitute master block available that omits the jumbotron image. |
The navbar consists of logo, quick search, nav buttons (right side) and nav links (gray strip).
The nav buttons and nav links are configurable using the navButtons and
navLinks site properties, respectively. The HTML is sensitive to changes
in markup and class names, so be careful—it’s a good idea to save aside the
original content for comparison. When making changes, be sure to test on
mobile since the markup is reused there with a mobile presentation.
The cart icon is included by default but can be disabled for sites
without e-commerce. To disable the cart, comment it out in the
navButtons site property.
By default "Browse Titles" is shown and links to the alphabetical book index. There are two other links available but commented by default: "Browse Authors" and "Browse Topics."
To enable "Browse Authors," first create a virtual collection based on
Authors, with the custom URL "authors." Then uncomment the link in the
navLinks site property.
To enable "Browse Topics," you will need at least one collection, then you
can uncomment the link in the navLinks site property. By default Tizra
JavaScript will automatically set the link to the first collection
alphabetically. To use a different target, change the link from "#" to the
proper target.
|
💡
|
If you only want some of your collections to appear in the "Browse Topics" list, you can give those collections a metadata tag (e.g. "topic") and then modify the "Sidebar - Collections" master block to filter the list by the same admin tag. |
The "My Bookshelf" and "My Account" nav items link to ~userLicenses and
~userInfo respectively. Note that because the ~userLicenses URL needs
a Tizra id for context, the HTML has href="#" and is updated by Tizra
JavaScript automatically.
The per-user bookshelf provides a gallery list of the books and excerpts for which the user has a license. By default these are titled "My books" and "My chapters" on the bookshelf, and the content of their sections is controlled by an attribute on the div. If your site has different nomenclature, you can change the titles and adjust the metatype in the Free HTML blocks on the User Licenses page:
|
|
|
💡
|
data-metatype can be a comma-separated list in case you want to put books and excerpts together under one heading. |
By default, collections are shown in their own "My collections" section of
the bookshelf. If the user doesn’t have any collection licenses, the
section is omitted. The inclusion of the "My collections" section is
controlled by the site property Bookshelf Has Collections Section
In the "My collections" section, the Quickstart template looks for a cover image as a property on the collection. If there is no cover image, the template falls back to a book icon on a gray background.
Collections are also enumerated by default in the other sections of the bookshelf: "My books" and "My chapters." If you need to change this behavior, it can be controlled by disabling "Enumerate the contents of collections" in the "User Account Licenses" block on the "User Licenses" layout.
This section applies to the following pages:
-
Document ToC (book details)
-
Excerpt ToC (excerpt details)
-
Access Denied (details relevant to a specific page)
Each of these pages—as well as the bookshelf—includes a cover image for a book or excerpt. The cover image can optionally be supplied explicitly in the book or excerpt metadata
If there’s no cover image supplied then the first page of the PDF will be used automatically. In the case of an excerpt, the first page of the excerpt range will be used.
On the book and excerpt detail pages, the abstract is displayed long-form and the rest of the metadata is displayed in a combined "Details" section. The details will be shown using the sort order defined on the metadata for the publication, see http://support.tizra.com/tizra_help_manual_v2-9/379
|
You can control which metadata is shown long-form versus which is contained
in the "Details" section, by adjusting the layouts. There are Free HTML
blocks with markers (classes starting with js-) that help the JavaScript
to know what to put where:
For example, if you have a property AboutAuthor that should be displayed
long-form, you could create an additional Free HTML block as shown below.
The JavaScript will know to fill the block because the wrapper div has the
class js-prop-value and inner div has class="js-content"
data-prop="AboutAuthor"
The Quickstart template has built-in support for redemption codes, however it is disabled by default. To enable it, first make sure that redemption codes are enabled in site settings, then adjust these site properties:
RedemptionLinkEnabled shows a link on the user’s bookshelf to initiate
the process of activating a redemption code.
RedemptionOnToC shows a button on the detail pages which behaves in the
same way as the link on the bookshelf page. (The button will only show if
the signed-in user doesn’t have access to the content already.)
|
ℹ️
|
Quickstart v2.7 and later supports access-controlled videos from Vimeo. |
|
ℹ️
|
Quickstart v2.7.3 and later supports semi-access-controlled videos from YouTube. |
To enable video support on a site, the steps are:
-
Enable the site admin API by adding a random JSON API token in site settings.
-
Call the admin API to add the Video meta-type as follows, replacing SITE-NAME and SITE-TOKEN appropriately:
site=SITE-NAME token=SITE-TOKEN curl -X POST https://$site.tizrapublisher.com/admin-api/_/types/Title \ -H 'content-type: application/json' \ -H "tizra-authentication-token: $token" \ -d '{"name":"Video","is-user-defined":true}' curl -X PUT https://$site.tizrapublisher.com/admin-api/_/types/Video \ -H 'content-type: application/json' \ -H "tizra-authentication-token: $token" \ -d '{"display-name":"Video"}' -
At this point, you’re done with the JSON API token so by default you should remove it from site settings.
-
In site settings, add the Video ToC to
typeCustomViews:
-
In the content browser, create an empty Video object so that you can add the
oEmbedUrlproperty, which should have a display name ofVideo URL.❗Make sure that the visibility settings for the oEmbedUrlproperty are all disabled, because the URL needs to be kept secret from unauthorized users.
-
Create a Video with the proper Video URL. For Vimeo, it should be vimeo.com followed by numbers, like this:
https://vimeo.com/347381378. For YouTube, cutting and pasting the URL from the browser location bar works.
Vimeo’s built-in access-control uses domain-level white-listing. To protect videos on Tizra from unauthorized use, you’ll need to set things up properly in Vimeo first. Follow the directions for Enabling domain-level privacy to set Vimeo to serve the video to your Tizra site.
When a video in Tizra is licensed, then only authorized users will see the player on Tizra. Other users will see a thumbnail image and their options for purchasing the video.
If you don’t set up domain-level privacy in Vimeo, the Tizra portion will still show the player only to authorized users, but anybody will be able to find your video to watch on the Vimeo site.
YouTube doesn’t provide an option to disable the player on the YouTube site or using native apps. So while you can set up domain white-listing similar to Vimeo, it only prevents other domains from embedding your video, but it doesn’t prevent users from sharing the YouTube URL with other users.
The default search config only search books, but you can add video with this search config:
[metaTypes]
metadata = ['Book', 'Video']Similarly, browse blocks don’t include video by default. You can configure a browse block to include videos:
<div id="t-smartblock-abcdef">
</div>
<script>
jQuery(function() {
window.tizra.smartBlocks.browse({
target: document.getElementById('t-smartblock-abcdef'),
config: {
metaTypes: {
metadata: ['Book', 'Video'],
},
},
})
})
</script>|
ℹ️
|
In both cases above, search and browse, videos will appear but without their Vimeo- or YouTube-hosted thumbnail images. You can work around that by uploading a cover image as a free attachment and setting the CoverImage property as usual. |