When to Customize

Start with the built-in options whenever possible. Cover images, article structure, standard templates, and block settings are often enough to create a polished reading experience. Reach for custom Lava templates when you need behavior or layout that the built-in configuration cannot provide.

Book List

The page that shows all your books is fully customizable with a Lava template. But before you go and write your own Lava, know that books now have an attribute in which you can upload a custom cover image. If you do so then it will be displayed instead of the generic cover image. So even without writing any custom Lava you can make your books page look much nicer.

The book list template receives one main variable:

• Books - An array of all the books to be displayed.

Book View

The page that lets you actually read books has a number of block settings to let you customize the look.

First, under the normal block settings there are templates for both Article Header and Article Footer. These are displayed just before the article content and just after the article content. Both are rendered in the middle column between the two TOC sections on the left and right.

The Lava variables available to these templates are:

• Article - The article currently being rendered.
• Book - The book the article is a part of.
• IsPrinting - Will be true if the render is being performed as a multi-article print request.
• IsFirstArticle - Will be true if this is the first article being rendered.
• IsLastArticle - Will be true if this is the last article being rendered.

Some of those might be a completely new concept. First off, if you specify "print=1" in the query string then the system will enter print mode. Since that causes multiple articles to be rendered, we provide the last two values as well. Between these three you can decide how you want to handle any custom rendering options during printing.

Next, under the Advanced Settings tab of the block settings are some additional settings you might want to make use of.

The first is the Show Panel option. When enabled, this will enclose the entire article (including both TOCs) inside a standard block panel. The book name will be used for the heading text.

The other two settings you can make use of are Page Header Template and Page Footer Template. These allow you to customize what is displayed at the very top and very bottom of the page. These would, for example allow you to render your own custom paneled look.

The lava variables available on these templates are:

• Article: The main (first) article being rendered.
• Book: The book the article belongs to.
• IsPrinting: True when this is a print request.

Under the Advanced Settings tab you will also find a Template setting. This controls the entire book view page, including the table of contents. It is an advanced customization point, but it gives you full control over the final output. The following merge fields are available.

Two of those fields expose additional details:

• Navigation
  • NextArticle: The next article after the current one.
  • NextArticleLink: The full URL for the next article.
  • PreviousArticle: The previous article before the current one.
  • PreviousArticleLink: The full URL for the previous article.
• Versions
  • Value: A link to this same article in that version, when possible.
  • Text: The version label shown to the reader.

Browser Bus Messages

The Book View block supports a number of custom browser bus messages that can be used to customize the experience further.

• plugin.block.copyArticleSlug - This will copy the current article slug into the clipboard.
• plugin.block.editArticle - This will begin editing the current article.
• plugin.block.editArticleChildren - This will open the modal to edit the list of child articles.
• plugin.block.editArticleSecurity - This will open the modal to edit the security for the current article.
• plugin.block.printArticle - This will open the modal to print the current article.

Essentially, this is everything in the action menu. This allows you to hide the default action menu and create your own completely custom action menu.

Using Lava

Each article can have Lava enabled or disabled (the default). If you enable the article's Merge Content setting then the entire rendered article will have a Lava merge performed on it.

This allows you to make your articles dynamic. For example, you could check for a specific attribute value on the current person and add in some extra text or links to other pages that they should read.

While you can use Lava anywhere in the Structured Editor, some block behaviors can complicate more advanced templates. For example, line breaks in a paragraph block are converted into HTML line breaks, which may interfere with complex Lava. Simple inline merges such as {{ CurrentPerson.NickName }} are usually fine. For more advanced logic, use the Raw HTML / Lava block.