Part 7 - Creating the homepage using Reporting

Overview

With the knowledge base populated with articles of different categories, it's time to build a homepage to allow users to easily find what they need, and to quickly make new articles too.

Introducing Reporting

Reporting allows you to display data from specific pages or spaces. It utilizes the keys and supplier concept to pull data anywhere in your Confluence instance to customize reports. For more information, check out our Reporting for Confluence documentation.

Getting started

Create a new blank page

set it as the root page of your knowledge base

In Page Layout

toggle the sections to build a layout

in the first one-column section
- insert a Livesearch block (to allow users to search for an article_

Showing Articles by Label Using Reporting

In the next two-column sections create Panel blocks to show the most recently modified articles from each category.

insert a Panel block for each column
customise Panel block
- add names based on each category

Inside the Panel block

insert a report-list block
edit the report-list block
- customise to your preferred bullet style
- set the maxResults parameter to the preferred number of articles to show per column

In the report-list block

insert a content-reporter and report-body block
edit the content-reporter block
- enter the label to filter articles with (for example, 'how-to' or 'issues')

In the content-reporter block

insert a date-sort block
edit the date-sort block
- set the key as content:modification date

This tells Reporting to sort the data based on the most recent modification date.

In the report-body block

insert a a report-info block
edit the report-info block
- set the key as content:title

This tells Reporting to display the title of each article.

check Link To Item so that the data displayed becomes a link

Adding a 'Create Article' link (optional)

For each column, a 'create new article' link can be added for user convenience in creating a new article of the same template.

The add-page macro from the Linking app is used.

insert an add-page macro
edit the add-page macro

enter the name of the link in Link Text
enter the name of the template you wish to render in Source

in Labels
- enter the name of the label you wish to attach to the new article

Understanding the Reporting structure

The following diagram explains the structure of the Reporting block we just created. Most Reporting blocks will follow a similar structure as this one.

The outermost wrapper determines how the Reporting block should be displayed

a list, table or plain text area can be chosen to display the data

Next, there is a header that defines where the data is fetched

within the header, we can also add conditions to the data such as filters or sorters

The header could be a content-reporter or local-reporter block.

Next up, the conditions are nested within the filter block

in this block, we insert a date-sort block to get the most recent modification date

Finally, the data is displayed in the body of our report, report-body

multiple report-info blocks can be added in report-body, that takes a key to display some sort of data.

Code

<ac:layout>
  <ac:layout-section ac:type="single">
    <ac:layout-cell>
      <ac:structured-macro ac:macro-id="4917616b-9d86-418d-a3a3-a0c60a378d6f" ac:name="report-list" ac:schema-version="1">
        <ac:parameter ac:name="maxResults">5</ac:parameter>
        <ac:rich-text-body>
          <ac:structured-macro ac:macro-id="2992a562-3516-491b-9dc3-8fdf6925e75c" ac:name="content-reporter" ac:schema-version="1">
            <ac:parameter ac:name="types">pages</ac:parameter>
            <ac:parameter ac:name="labels">systems</ac:parameter>
            <ac:rich-text-body>
              <p>
                <ac:structured-macro ac:macro-id="9127f3be-60c8-4c14-a659-f50de5a0f7c7" ac:name="date-sort" ac:schema-version="1">
                  <ac:parameter ac:name="order">descending</ac:parameter>
                  <ac:parameter ac:name="">content:modification date</ac:parameter>
                </ac:structured-macro>
              </p>
            </ac:rich-text-body>
          </ac:structured-macro>
          <ac:structured-macro ac:macro-id="da6a04bf-39ae-470c-acfa-9bdca2c289aa" ac:name="report-body" ac:schema-version="1">
            <ac:rich-text-body>
              <p>
                <ac:structured-macro ac:macro-id="25d4a2f0-f8f4-47af-9236-eb5814c9a5ca" ac:name="report-info" ac:schema-version="1">
                  <ac:parameter ac:name="link">true</ac:parameter>
                  <ac:parameter ac:name="separator">newline</ac:parameter>
                  <ac:parameter ac:name="">content:title</ac:parameter>
                </ac:structured-macro>
              </p>
            </ac:rich-text-body>
          </ac:structured-macro>
        </ac:rich-text-body>
      </ac:structured-macro>
      <p style="text-align: center;">
        <br/>
        <ac:structured-macro ac:macro-id="96a87d4e-3569-474b-b1f7-1ee94828a029" ac:name="livesearch" ac:schema-version="1">
          <ac:parameter ac:name="size">large</ac:parameter>
        </ac:structured-macro>
      </p>
      <h2>Articles in this KB by labels</h2>
    </ac:layout-cell>
  </ac:layout-section>
  <ac:layout-section ac:type="two_equal">
    <ac:layout-cell>
      <ac:structured-macro ac:macro-id="9ae2eca3-f6d4-494b-a83e-7a4b55468456" ac:name="panel" ac:schema-version="1">
        <ac:parameter ac:name="borderColor">#99D3DF</ac:parameter>
        <ac:parameter ac:name="borderWidth">1</ac:parameter>
        <ac:parameter ac:name="titleBGColor">#99D3DF</ac:parameter>
        <ac:parameter ac:name="title">How to</ac:parameter>
        <ac:rich-text-body>
          <ac:structured-macro ac:macro-id="a564fdf3-7270-4add-8f50-b11d4ee892b8" ac:name="report-list" ac:schema-version="1">
            <ac:parameter ac:name="maxResults">5</ac:parameter>
            <ac:rich-text-body>
              <ac:structured-macro ac:macro-id="683f94b3-dc4e-4299-ac9f-478c22a3c2c5" ac:name="content-reporter" ac:schema-version="1">
                <ac:parameter ac:name="types">pages</ac:parameter>
                <ac:parameter ac:name="labels">how-to</ac:parameter>
                <ac:rich-text-body>
                  <p>
                    <ac:structured-macro ac:macro-id="3c8690c4-4d60-4c63-8e6b-2b8b8080f82b" ac:name="date-sort" ac:schema-version="1">
                      <ac:parameter ac:name="order">descending</ac:parameter>
                      <ac:parameter ac:name="">content:modification date</ac:parameter>
                    </ac:structured-macro>
                  </p>
                </ac:rich-text-body>
              </ac:structured-macro>
              <ac:structured-macro ac:macro-id="d93d6d34-3b1f-4663-8ea9-5dc35e1b09ff" ac:name="report-body" ac:schema-version="1">
                <ac:rich-text-body>
                  <p>
                    <ac:structured-macro ac:macro-id="5fac74a3-1cd7-44c1-a05d-ba435a38007c" ac:name="report-info" ac:schema-version="1">
                      <ac:parameter ac:name="link">true</ac:parameter>
                      <ac:parameter ac:name="separator">newline</ac:parameter>
                      <ac:parameter ac:name="">content:title</ac:parameter>
                    </ac:structured-macro>
                  </p>
                </ac:rich-text-body>
              </ac:structured-macro>
            </ac:rich-text-body>
          </ac:structured-macro>
          <p>
            <ac:structured-macro ac:macro-id="fd6a175f-2e5b-4856-8578-8091c6161447" ac:name="add-page" ac:schema-version="1">
              <ac:parameter ac:name="parent">How To</ac:parameter>
              <ac:parameter ac:name="linkText">Create a new 'how to' article</ac:parameter>
              <ac:parameter ac:name="source">KB how to article</ac:parameter>
              <ac:parameter ac:name="live">true</ac:parameter>
              <ac:parameter ac:name="labels">how</ac:parameter>
            </ac:structured-macro>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:macro-id="344446eb-2e4e-4bd3-bde2-22d18e1dbe75" ac:name="panel" ac:schema-version="1">
        <ac:parameter ac:name="borderColor">#CDCDCD</ac:parameter>
        <ac:parameter ac:name="borderWidth">1</ac:parameter>
        <ac:parameter ac:name="titleBGColor">#CDCDCD</ac:parameter>
        <ac:parameter ac:name="title">FAQ</ac:parameter>
        <ac:rich-text-body>
          <p> <span>View the FAQ </span>
            <ac:link>
              <ri:page ri:content-title="FAQ"/>
              <ac:plain-text-link-body><![CDATA[here]]></ac:plain-text-link-body>
            </ac:link>
            <span>.</span>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
    </ac:layout-cell>
    <ac:layout-cell>
      <ac:structured-macro ac:macro-id="81fa6a95-622a-401b-ae67-1e2d88b76e56" ac:name="panel" ac:schema-version="1">
        <ac:parameter ac:name="borderColor">#88BBD6</ac:parameter>
        <ac:parameter ac:name="borderWidth">1</ac:parameter>
        <ac:parameter ac:name="titleBGColor">#88BBD6</ac:parameter>
        <ac:parameter ac:name="title">Issues and Solutions</ac:parameter>
        <ac:rich-text-body>
          <ac:structured-macro ac:macro-id="33fcb937-a234-476b-b01c-5fdc265afb71" ac:name="report-list" ac:schema-version="1">
            <ac:parameter ac:name="maxResults">5</ac:parameter>
            <ac:rich-text-body>
              <ac:structured-macro ac:macro-id="f648ce66-4a69-4e59-a4b0-124bf7cec3c5" ac:name="content-reporter" ac:schema-version="1">
                <ac:parameter ac:name="types">pages</ac:parameter>
                <ac:parameter ac:name="labels">issues-solutions</ac:parameter>
                <ac:rich-text-body>
                  <p>
                    <ac:structured-macro ac:macro-id="a40a6854-cc4c-4b23-81cc-3d9159554d7b" ac:name="date-sort" ac:schema-version="1">
                      <ac:parameter ac:name="order">descending</ac:parameter>
                      <ac:parameter ac:name="">content:modification date</ac:parameter>
                    </ac:structured-macro>
                  </p>
                </ac:rich-text-body>
              </ac:structured-macro>
              <ac:structured-macro ac:macro-id="91bc6f4c-26e5-409e-9344-411986eb7d96" ac:name="report-body" ac:schema-version="1">
                <ac:rich-text-body>
                  <p>
                    <ac:structured-macro ac:macro-id="dff88e78-da76-4d8b-a27d-0544c78f1194" ac:name="report-info" ac:schema-version="1">
                      <ac:parameter ac:name="link">true</ac:parameter>
                      <ac:parameter ac:name="separator">newline</ac:parameter>
                      <ac:parameter ac:name="">content:title</ac:parameter>
                    </ac:structured-macro>
                  </p>
                </ac:rich-text-body>
              </ac:structured-macro>
            </ac:rich-text-body>
          </ac:structured-macro>
          <p>
            <ac:structured-macro ac:macro-id="5f0501a3-5d0a-4661-ab5b-82399335467e" ac:name="add-page" ac:schema-version="1">
              <ac:parameter ac:name="parent">Issues and Solutions</ac:parameter>
              <ac:parameter ac:name="linkText">Create a new 'issues and solutions' article</ac:parameter>
              <ac:parameter ac:name="source">KB issues article</ac:parameter>
              <ac:parameter ac:name="live">true</ac:parameter>
              <ac:parameter ac:name="labels">issues-solutions</ac:parameter>
            </ac:structured-macro>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
      <ac:structured-macro ac:macro-id="62c7165a-ee8b-488e-b729-d930ffa2ffea" ac:name="panel" ac:schema-version="1">
        <ac:parameter ac:name="borderColor">#E9E9E9</ac:parameter>
        <ac:parameter ac:name="borderWidth">1</ac:parameter>
        <ac:parameter ac:name="titleBGColor">#E9E9E9</ac:parameter>
        <ac:parameter ac:name="title">Systems</ac:parameter>
        <ac:rich-text-body>
          <ac:structured-macro ac:macro-id="3d4ff1ff-bf3e-4350-878e-3b1b56f4a5bd" ac:name="report-list" ac:schema-version="1">
            <ac:parameter ac:name="maxResults">5</ac:parameter>
            <ac:rich-text-body>
              <ac:structured-macro ac:macro-id="892af040-6f45-4bd0-ae4e-bee4e9925006" ac:name="content-reporter" ac:schema-version="1">
                <ac:parameter ac:name="types">pages</ac:parameter>
                <ac:parameter ac:name="labels">systems</ac:parameter>
                <ac:rich-text-body>
                  <p>
                    <ac:structured-macro ac:macro-id="48f668d7-1f11-4607-a7fb-12127cca57fe" ac:name="date-sort" ac:schema-version="1">
                      <ac:parameter ac:name="order">descending</ac:parameter>
                      <ac:parameter ac:name="">content:modification date</ac:parameter>
                    </ac:structured-macro>
                  </p>
                </ac:rich-text-body>
              </ac:structured-macro>
              <ac:structured-macro ac:macro-id="d63ea60c-ea3d-4fa8-be19-e65ed8e40ace" ac:name="report-body" ac:schema-version="1">
                <ac:rich-text-body>
                  <p>
                    <ac:structured-macro ac:macro-id="0d766db1-4055-4649-96e8-b666b33c079f" ac:name="report-info" ac:schema-version="1">
                      <ac:parameter ac:name="link">true</ac:parameter>
                      <ac:parameter ac:name="separator">newline</ac:parameter>
                      <ac:parameter ac:name="">content:title</ac:parameter>
                    </ac:structured-macro>
                  </p>
                </ac:rich-text-body>
              </ac:structured-macro>
            </ac:rich-text-body>
          </ac:structured-macro>
          <p>
            <ac:structured-macro ac:macro-id="b2f9529e-a171-4d0e-b955-c48cbe17a9cc" ac:name="add-page" ac:schema-version="1">
              <ac:parameter ac:name="parent">Systems</ac:parameter>
              <ac:parameter ac:name="linkText">Create a new 'systems' article</ac:parameter>
              <ac:parameter ac:name="source">KB systems article</ac:parameter>
              <ac:parameter ac:name="live">true</ac:parameter>
            </ac:structured-macro>
          </p>
        </ac:rich-text-body>
      </ac:structured-macro>
    </ac:layout-cell>
  </ac:layout-section>
</ac:layout>