Blog

  • 2024
  • 2023
  • 2022
  • 2021
  • 2020
  • 2019
  • 2018
  • 2017
  • 2016
  • 2015
  • 2014
  • 2013
  • 2012

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Image ModifiedPage and Space blueprints are a great tool to structure information in Confluence. They support teams to create pages and spaces with focusing on the content, less on the structure, not on the layout. With this tool new pages and whole spaces can be created with wizards in very little time.

...

Note Box
titleBlueprint Add-ons

There are a number of blueprint add-ons for the projectdoc Toolbox. A list of blueprints, we call document types - or doctypes for short, shows what we have already created.

These are available on the Atlassian Marketplace and on Bitbucket.

Section
titlePrinciples

In the past we have come up with some simple observations that we like when using blueprints.

  1. Have sets of blueprints that work together, using existing blueprints
  2. Have at least one space that provides a basic structure for the domain of the blueprint set
  3. Create navigation by dynamic linking
    1. Provide a type blueprint for most of the blueprints
    2. Show pages of a given type
    3. Show child pages and a reference to the parent
    4. After the creation of a new space or new page, everything should be ready to work - no remove this, paste that
Section
titleThe Mission

To create a blueprint you need to touch a number of files.

  1. There is the XML file containing the template,
  2. the Soy file to specify the wizard.
  3. A JavaScript file for the validators for the wizard,
  4. probably a Java file to manipulate the blueprint context.
  5. Add localized resource files for one or more languages,
  6. create one or more index pages,
  7. and finally a number of edits to the atlassian-plugin.xml file.
Note Box

For projectdoc we also generate blueprints to create index pages (should you get lost of the doctypes homepage), special pages (such as - and currently the only one) content management homepage, which is a view for authors on the documents, and finally a blueprint that creates all pages of a space in an already existing page.

Since these are considered as basic support they are created automatically.

So the basic course of events is this:

Code Block
languagetext
themeMidnight
> mvn doctype:create 
  -DshortId=services 
  -DprojectName="Service Management Doctypes" 
  -DprojectDescription="Provides Blueprints for System Management."
  -DcreateExamples=false
> [add your descriptor files]
> mvn doctype:generate
> atlas-run
Tip Box

If you start from new you probably would like to have some example files and your are probably not that fancy to specify a nice name and description. In this case use the following:

Code Block
languagetext
themeMidnight
> mvn doctype:create -DshortId=my-sandbox
> mvn doctype:generate
> atlas-debug

The project has configured quick reload.

projectdoc-section
titleTypes of Pages

To make this simplification we define some constraints.

First, we think of pages as documents with properties (key-value pairs) and sections (a title with text, possibly nested). We call this a projectdoc document. With this in mind, we define a document type with a doctype descriptor (there is also a descriptor for spaces and one for the context of the add-on).

When we create new doctype add-ons there are typically three kind of pagesdocuments:

  1. Pages Documents that contain information of a given type (e.g. a doctype to document systems)
  2. Pages Documents that categorize this type (e.g. system type documents)
  3. Pages Documents that categorize this and other types (e.g. documents that specify phases in a lifecycle)
Example Box
titleA System, a System Type, and a Type

With this a team may document a system (e.g. a JIRA instance), associate it with a system type (e.g. issue management system), and set a lifecycle phase (e.g. In-service). On the issue management page there will automatically be listed all issue management systems and on the In-service lifecycle page, all systems (and maybe other entities with a lifecycle) that are actually servicing will be shown. Only one document is added, but two indexing pages will automatically reference it.

Section
titleThe Tool

We created a first beta version of the DTSMP that should make it a lot easier to create these three kinds of pages.

Note Box

We say 'should' since we just started the journey.

Everything starts with the archetype project. But you control the archtetype for doctype add-ons with the doctype:create goal which sets some defaults and makes creating new add-on projects quite easy.

To create a blueprint you need to touch a number of files.

  • There is the XML file containing the template,
  • the Soy file to specify the wizard.
  • A JavaScript file for the validators for the wizard,
  • probably a Java file to manipulate the blueprint context
  • Code Block
    languagetext
    themeMidnight
    > mvn doctype:create 
      -DshortId=services 
      -DprojectName="Service Management Doctypes" 
      -DprojectDescription="Provides Blueprints for System Management."
      -DcreateExamples=false
    and finally a number of edits to the atlassian-plugin.xml file.

    To simplify this process of blueprint creation, we do specify one descriptor and then generate all the blueprint related stuff.We think of pages as documents with properties (key-value pairs) and sections (a title with text, possibly nested). We call this a projectdoc document. With this in mind, we define a document type with a doctype descriptor (there is also a descriptor for spaces and one for the context of the add-on).per document and space type (currently there can only be one space).

    Example Box
    titleSystem, System Type, and Lifecycle Phase

    Here is the example of a doctype (it-system) with it own type category (it-system-type).

    Expand
    titleClick here to expand the System Descriptor
    Code Block
    languagexml
    titleSystem doctype (with a type)
    <doctype
      xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      id="it-system"
      base-template="standard"
      provide-type="standard-type"
      category="operations">
      <resource-bundle>
        <l10n>
          <name>IT System</name>
          <description>
            Provide information on an IT system to be deployed to.
          </description>
          <about>
            IT systems are part of environments where products are deployed to.
          </about>
        </l10n>
        <l10n locale="de">
          <name>IT-System</name>
          <description>
            Erstellen Sie eine Akte zu einem IT-System.
          </description>
          <about>
            IT-Systeme stellen Funktionalität bereit, die von Services genutzt werden.
          </about>
          <type plural="IT-Systemtypen">IT-Systemtyp</type>
        </l10n>
      </resource-bundle>
    
      <properties>
        <property key="projectdoc.doctype.common.type">
          <value>
            <macro name="projectdoc-name-list">
              <param name="doctype">it-system-type</param>
              <param
                name="property"
                key="projectdoc.doctype.common.type" />
              <param name="render-no-hits-as-blank">true</param>
            </macro>
          </value>
        </property>
    
        <property key="projectdoc.doctype.it-system.lifecycle-phase">
          <value>
            <macro name="projectdoc-name-list">
              <param name="doctype">lifecycle-phase</param>
              <param
                name="property"
                key="projectdoc.doctype.it-system.lifecycle-phase" />
              <param name="render-no-hits-as-blank">true</param>
            </macro>
          </value>
          <resource-bundle>
            <l10n>
              <name>Lifecycle Phase</name>
            </l10n>
            <l10n locale="de">
              <name>Lifecycle-Phase</name>
            </l10n>
          </resource-bundle>
        </property>
      </properties>
    </doctype>

    If you are looking for the declaration if the it-system type, its here:

    Code Block
    provide-type="standard-type"

    The type doctype provides a section to dynamically list all documents that are associated to this type.

    The it-system blueprint does not only provide the two properties explicitly stated. Since it derives from the standard template, all standard properties and sections are automatically generated.

    Expand
    titleClick here to expand the Lifecycle Phase Descriptor
    Code Block
    languagexml
    titleLifecycle Phase (a type)
    <doctype
      xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      id="lifecycle-phase"
      base-template="type"
      provide-type="none"
      category="reference">
      <resource-bundle>
        <l10n>
          <name>Lifecycle Phase</name>
          <description>
            Define a lifecycle phase.
          </description>
          <about>
            Lifecycle Phases define phases that are bound to a lifecycle.
          </about>
        </l10n>
        <l10n locale="de">
          <name>Lifecycle-Phase</name>
          <description>
            Definieren Sie eine Phase.
          </description>
          <about>
            Phasen von Lifecycles dokumentieren einen Abschnitt im Zyklus von Ressourcen.
          </about>
          <type plural="Lifecycle-Phasentypen">Lifecycle-Phasentyp</type>
        </l10n>
      </resource-bundle>
    
      <properties>
        <property key="projectdoc.doctype.lifecycle-phase.lifecycle">
          <value>
            <macro name="projectdoc-name-list">
              <param name="doctype">lifecycle</param>
              <param
                name="property"
                key="projectdoc.doctype.lifecycle-phase.lifecycle" />
              <param name="render-no-hits-as-blank">true</param>
            </macro>
          </value>
          <resource-bundle>
            <l10n>
              <name>Lifecycle</name>
            </l10n>
            <l10n locale="de">
              <name>Lifecycle</name>
            </l10n>
          </resource-bundle>
        </property>
      </properties>
    </doctype>

    Then generate all the blueprint related stuff (note there are XML schema files to support writing these). And startup Confluence with the Atlas SDK.

    Code Block
    languagetext
    themeMidnight
    > mvn doctype:generate
    > atlas-run
    Section
    titleLimitations

    We started our internal beta (although the sources are already published on Bitbucket) to check how it is working. Needless to say that at this early stage it has some limitations:

    • The syntax for defining sections is not final - property values (with alternate forms as seen above) and whole sections (without alternatives if you need to specify more than a placeholder) are specified in their storage format within an xml element
    • Only one space blueprint can be defined
    • There are grammatical problems with the boiler plate texts (especially in German), so there is the need to run over the generated localization bundles
    • No roundtrip: You should not need to edit the generated files (or if you do, should not use the descriptor again)
    • Very simple wizards currently
    • No support to add CSS or JavaScript
    • Currently the localized resources need to be written to the descriptor
    • There is also a redundancy specifying the central base templates - but you won't see this until you need to create your own base template

    We'll work to improve the tools to remove these limitations.

    Section
    titleWhat is next?

    As stated above the tools have some rough edges. So we need to run this internally first. If you are interested to use this tool, it is available at Bitbucket and available from our Nexus server.

    Please check out the documention documentation for the DTSMP and do to get everything set up. Do not hesitate to get in touch, if you have questions or are being interested in this topic!

    Hopefully we can soon truthfully say: Creating Blueprints is fun!