Product Content Transfer

Overview

A product’s interactive content can be transferred into the site using a custom format - a single zipped archive with the following structure:

File	Description	Schema
product.json	A file which contains the core specification of a product, with links to all the relevant definitions inside this archive.	product_schema_v1_0_0.json
content/{filename}.json	Optional. A file which contains the definition of the product’s interactive content. There should be one file for each chapter in the product. The filename and order to read is defined in product.json, but we recommend either using the chapter code or a numbered system (e.g. Chapter{N}.json)	content_schema_v1_0_0.json
blobs/{filename}	Optional. A flat directory containing all the BLOBs in a product.A BLOB (Binary Large OBject) is a file containing arbitrary data and can be used to store e.g. the product’s figures, pictures and attachments.Filenames have to be unique but otherwise have any value - GUIDs are recommended.	N/A

An API is available at ~/api/v1/libraries/{libraryCode}/products/{productCode}/transfer to automatically upload content using this format.

product.json

Schema

This file contains the core specification of a product - its product code and product type. Additionally, it defines what content the product has by linking to relevant files.

A full json schema definition can be found at product_schema_v1_0_0.json.

Property	Description
version	The version number for this specification format - currently 1.0.0
productType	Either “Report” or “Briefing”
productCode	The code of the product being created or edited.
content	Optional. This property contains all the data to update the main content. If not present, the product content will not be modified.
content.updateMode	Defines how the product’s main content will be modified. “ignore” means the main content will not be modified. “replace” means all of the current content will be deleted and replaced with the content in this archive.
content.files	Contains references to content files, one per chapter. The order of this list defines the order of the chapters.

When the productType is Report then the content.files property can have multiple references to files, each of which must have the file type “Chapter”.

When the productType is Briefing then the content.files property can have only one reference to a file, which must have the file type BriefingContent.

Examples

{
   "version":"1.0.0",
   "productType":"Report",
   "productCode":"Product_code",
   "content":{
     "updateMode":"replace",
     "files":[
       "~/content/chapter1.json",
       "~/content/chapter2.json",
       "~/content/chapter3.json"
     ]
   }
 }

{
   "version":"1.0.0",
   "productType":"Briefing",
   "productCode":"Product_code",
   "content":{
     "updateMode":"replace",
     "files":[
       "~/content/briefingContent.json"
     ]
   }
 }

content/{filename}.json

Content is stored in iReports as Snippets - these are chunks of content such as a paragraph or a figure. A product’s content can be represented as an (almost) flat list of these snippets. Each content type at a minimum specifies the version and type of the content inside the file. Currently the type can be either “Chapter” or “BriefingContent”, which should match up with the productType specified in product.json.

A full json schema definition can be found at content_schema_v1_0_0.json.

Property	Description
version	The version number for this specification format - currently 1.0.0
type	Either “Chapter” or “BriefingContent”

Content File Type “Chapter”

The “Chapter” type can only be used when the product type is “Report”. Each chapter has a title and can optionally have a palette specified for its content. Palettes define the background and foreground colour of text, headings and borders. The palette property should be the name of one of the pre-defined palettes, which are currently called palette-{number}.

Property	Description
version	The version number for this specification format
type	Must be “Chapter”
title	An HTML string containing the text of the heading
layout.palette	Optional. A string containing the palette name (Defaults to ‘palette-1’)
snippets	An array containing the snippets in this chapter

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "layout":{
     "palette":"palette-7"
   },
   "snippets":[
     {
       "type":"Text",
       "content":".. some key findings .."
     }
   ]
 }

Content File Type “BriefingContent”

The “BriefingContent” type can only be used when the product type is “Briefing”. It can optionally have a palette specified for its content. Palettes define the background and foreground colour of text, headings and borders. The palette property should be the name of one of the pre-defined palettes, which are currently called “palette-{number}”.

Property	Description
version	The version number for this specification format
type	Must be “BriefingContent”
layout.palette	Optional. A string containing the palette name (Defaults to ‘palette-1’)
snippets	An array containing the snippets in the briefing

Examples

{
   "version":"1.0.0",
   "type":"BriefingContent",
   "layout":{
     "palette":"palette-7"
   },
   "snippets":[
     {
       "type":"Text",
       "content":".. a short briefing about a particular topic .."
     }
   ]
 }

Sections

Section snippets are used to provide structure to the document, similar to HTML <H1>, <H2>, etc. elements. Each section has a level - either 1, 2, or 3 - which indicates the nesting of sections in the ToC. Sections are not allowed to “jump” up a level, but can “jump” down levels ; i.e., an S3 must be after an S2 and cannot be immediately after an S1. However, an S1 can immediately follow an S3.

A section’s content is defined as the content between one heading and the next heading of the same (or lower) level. e.g.

- S1 
- Text 1 
- S2 
- Text 2 
- Text 3 
- S3 
- Text 4 
- S1

The content of S2 would be Text 2, Text 3, S3 and Text 4

Each section can optionally specify a palette for its content. Palettes define the background and foreground colour of text, headings and borders. The palette property should be the name of one of the pre-defined palettes, which are currently called “palette-{number}”. Sections will inherit palettes from their parent section or chapter so they do not need to be specified unless you want a different palette.

Sections can also have a background image - The layout.background.image property should be a path from the root of the archive to the file location. The image itself should be stored in the _blobs_ folder. Only .jpg, .jpeg, .png and .gif images are allowed, and the image will be converted to a .png for displaying.

Property	Description
type	Must be “Section”
title	An HTML string containing the text of the section title
definition.level	A number indicating the level of the section
layout.background.image	Optional. A path to the background image
layout.background.opacity	Optional. A number between 0 and 1, where 0 is transparent and 1 is fully opaque
layout.palette	Optional. A string containing the palette name

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "snippets":[
     {
       "type":"Section",
       "title":"3.1: Using <abbr title=\"Hyper Text Markup Language\">HTML</abbr> in a title",
       "definition":{
         "level":1
       },
       "layout":{
         "palette":"palette-7",
         "background":{
           "image":"~/blobs/background-1.png",
           "opacity":1
         }
       }
     },
     {
       "type":"Text",
       "content":".. some key findings .."
     }
   ]
 }

Content blocks

Content blocks are used to add columns or apply different palettes to content. Content blocks can only contain content block columns, which in turn contain other snippets. They have a block type which indicates how many columns are in the block, and what their relative widths are:

OneColumn - This block has only one column, which takes up the entire width. This can be used to style paragraphs independently.
TwoColumn - This block has two columns, each taking up half of the available space.
TwoColumnOneThird - This block has two columns, with the first column taking one third of the space.
TwoColumnTwoThird - The opposite of TwoColumnOneThird - the first column takes up two thirds of the space.
ThreeColumn - This block has three columns, each taking up a third of the available space.

Each block can optionally specify a palette for its children. Palettes define the background and foreground colour of text, headings and borders. The palette property should be the name of one of the pre-defined palettes, which are currently called “palette-{number}”. Blocks will inherit palettes from the section it is in and so does not need to be specified unless you want a different palette.

Blocks can also have a background image - The layout.background.image property should be a path from the root of the archive to the file location.

The image itself should be stored in the _blobs_ folder.

Only .jpg, .jpeg, .png and .gif images are allowed, and the image will be converted to a .png for displaying.

Content block columns must have at least one snippet (an empty text snippet is allowed), and is allowed to contain any of the following snippets:

Text
Lists
Tables
Figures
Figures with tables
Pictures
Full size pictures

Content Blocks

Property	Description
type	Must be “ContentBlock”
definition.blockType	An enum indicating how many columns and what width the columns are
layout.background.image	Optional. A path to the background image
layout.background.opacity	Optional. A number between 0 and 1, where 0 is transparent and 1 is fully opaque
layout.palette	Optional. A string containing the palette name
snippets	A list containing 1, 2 or 3 ContentBlockColumns. The order of the ContentBlockColumns defines the order of the columns (from left to right) in the content block.

Content block columns

Property	Description
type	Must be “ContentBlockColumn”
snippets	A list containing one or more snippets

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "snippets":[
     {
       "type":"ContentBlock",
       "definition":{
         "blockType":"TwoColumnOneThird"
       },
       "layout":{
         "palette":"palette-9",
         "background":{
           "image":"~/blobs/background-2.png",
           "opacity":1
         }
       },
       "snippets":[
         {
           "type":"ContentBlockColumn",
           "snippets":[
             {
               "type":"Picture",
               "attachments":[
                 "~/blobs/picture2.jpg"
               ]
             }
           ]
         },
         {
           "type":"ContentBlockColumn",
           "snippets":[
             {
               "type":"Text",
               "content":"Some text to describe an employee, who's picture is to the left"
             },
             {
               "type":"Table",
               "title":"Personal references",
               "content":"<table><tr><td>A table of references</td></tr></table>",
               "metadata":{

                }
             },
             {
               "type":"Text",
               "content":"Columns can have as many snippets as you like, as long as there is at least one!"
             }
           ]
         }
       ]
     }
   ]
 }

Text

A text snippet is used for a single paragraph of content. Its content can contain inline HTML styling - e.g. bold or italic elements. Paragraphs can optionally have certain styles applied:

Glossary
Quote
Summary

These styles affect the way the paragraph displays within the report. Quotes are italic and justified, summaries are indented and have an arrow at the start and glossaries can be given additional space between each paragraph. Text snippets can contain Internal links.

Property	Description
type	Must be “Text”
content	An HTML string containing the text of the paragraph
definition.style	Optional. The style to apply to this paragraph

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "snippets":[
     {
       "type":"Text",
       "content":"Some <b>key</b> findings"
     },
     {
       "type":"Text",
       "content":"<a href=\"ireports://reports/ExampleReport\">Click here to see ExampleReport.</a>"
     },
     {
       "type":"Text",
       "content":"A quote about the key findings",
       "definition":{
         "style":"Quote"
       }
     }
   ]
 }

Lists

A list snippet can contain multiple Text snippets, which are rendered as paragraphs with bullet points. The Text snippets must not specify a style in their definition. Text snippets within lists can contain Internal links.

Property	Description
type	Must be “List”
snippets	A list of Text snippets

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "snippets":[
     {
       "type":"List",
       "snippets":[
         {
           "type":"Text",
           "content":"bullet point 1 text"
         },
         {
           "type":"Text",
           "content":"a <i>second</i> bullet point"
         }
       ]
     }
   ]
 }

Tables

A table is used to display tabular data. Its content is a single, standard, well-formed HTML table element. Tables can have merged cells and headings using the standard HTML rowspan and colspan attributes. Table cells and notes can contain Internal links.

Property	Description
type	Must be “Table”
title	An HTML string containing the exhibit title.
content	A single HTML table element. Can contain links to other reports, see above. Please note that <h1> to <h6> tags contained in table headers will be removed.
metadata.notes	An optional HTML string containing any notes to be displayed beneath the exhibit. Can contain links to other reports, see above.
metadata.source	An optional HTML string containing the source of the exhibit
metadata.keywords	A list of keywords used to boost the exhibit in search

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "snippets":[
     {
       "type":"Table",
       "title":"Table 2: title",
       "content":"<table><thead><tr><th>Heading 1</th><th>Heading 2</th></tr></thead><tbody><tr><td colspan=2>Cell 1.1 & 1.2</td></tr><tr><td>Cell 2.1</td><td>Cell 2.2</td></tr></tbody></table>",
       "metadata":{
         "notes":"Table 2 contains a merged cell in the first row.",
         "source":"Publish Interactive",
         "keywords":[
           "cells",
           "table",
           "merged",
           "example"
         ]
       }
     }
   ]
 }

Figures

A figure is used to display a static chart or infographic.

The attachment property should be a list of strings, where each string is a path from the root of the archive to the file location. The image itself should be stored in the _blobs_ folder. Only .jpg, .jpeg, .png and .gif images are allowed, and the image will be converted to a .png for displaying. Figure notes can contain Internal links.

Property	Description
type	Must be “Figure”
title	An HTML string containing the exhibit title
attachments	A list containing a single path to the image
metadata.notes	An optional HTML string containing any notes to be displayed beneath the exhibit. Can contain links to other reports, see above.
metadata.source	An optional HTML string containing the source of the exhibit
metadata.keywords	A list of keywords used to boost the exhibit in search

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "snippets":[
     {
       "type":"Figure",
       "title":"Figure 2: title",
       "attachments":[
         "~/blobs/figure2.jpg"
       ],
       "metadata":{
         "notes":"Figure 2 is a pie chart.",
         "source":"Publish Interactive",
         "keywords":[
           "pie",
           "example"
         ]
       }
     }
   ]
 }

Figures with tables

When a figure has backing data, it can be grouped together.

Please refer to the documentation for both figures and tables for more detail about what is allowed. Notes on figures with tables can contain Internal links.

Property	Description
type	Must be “FigureWithTable”
title	An HTML string containing the exhibit title
attachments	A list containing a single path to the image
content	A single HTML table element
metadata.notes	An optional HTML string containing any notes to be displayed beneath the exhibit
metadata.source	An optional HTML string containing the source of the exhibit
metadata.keywords	A list of keywords used to boost the exhibit in search

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "snippets":[
     {
       "type":"FigureWithTable",
       "title":"Figure 2: title",
       "attachments":[
         "~/blobs/figure2.jpg"
       ],
       "content":"<table><thead><tr><th>Heading 1</th><th>Heading 2</th></tr></thead><tbody><tr><td>Cell 1.1</td><td>Cell 1.2</td></tr></tbody></table>",
       "metadata":{
         "notes":"Figure 2 is a pie chart with backing data.",
         "source":"Publish Interactive",
         "keywords":[
           "pie",
           "example"
         ]
       }
     }
   ]
 }

Pictures

A picture is used to display a decorative image to the reader, without any surrounding metadata. They are contained inline within the content (unlike full-size pictures).

Property	Description
type	Must be “Picture”
attachments	A list containing a single path to the image

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "snippets":[
     {
       "type":"Picture",
       "attachments":[
         "~/blobs/picture2.jpg"
       ]
     }
   ]
 }

Full size pictures

Full size pictures are the same as pictures - used to display a decorative image to the reader, without any surrounding metadata. However, they take up the full-width of the content area and will ‘escape’ the normal margins.

Property	Description
type	Must be “FullSizePicture”
attachments	A list containing a single path to the image

Examples

{
   "version":"1.0.0",
   "type":"Chapter",
   "title":"3. Key findings",
   "snippets":[
     {
       "type":"FullSizePicture",
       "attachments":[
         "~/blobs/picture2.jpg"
       ]
     }
   ]
 }

Internal links

Various snippets can contain links to other products on the system. These are represented with normal HTML a tags but with href=”ireports://reports/{ProductCode}”. Replacing {ProductCode} with the code of the product you want to link to. An example is shown below:

<a href="ireports://reports/ExampleReport">Click here to see ExampleReport.</a>

Product Content Transfer

The following article will outline how to transfer your interactive content using various custom formats.

Overview

product.json

Schema

Examples

content/{filename}.json

Content File Type “Chapter”

Examples

Content File Type “BriefingContent”

Examples

Sections

Examples

Content blocks

Content Blocks

Content block columns

Examples

Text

Examples

Lists

Examples

Tables

Examples

Figures

Examples

Figures with tables

Examples

Pictures

Examples

Full size pictures

Examples

Internal links