Creating Blueprints is fun!

...

After about two year of writing a number of blueprints for the PDAC1, we finally came to the conclusion that we need to have some tool support to write blueprints. We want to come to the point where writing blueprints and create new add-ons with blueprint sets is no longer a great deal.

projectdoc-box-note

title	Blueprint 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.

projectdoc-section

title	Principles

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

Have sets of blueprints that work together, using existing blueprints
Have at least one space that provides a basic structure for the domain of the blueprint set
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

After the creation of a new space, everything should be ready to work.

...

Section

title	The Tool

We created a first beta version of a plugin for maven the DTSMP that should make it a lot easier to create these three kinds of pages. 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
and finally a number of edits to the atlassian-plugin.xml file.

To simplify this process, 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).

this by specifying descriptors for the blueprints we want to create. Here is the example of a doctype (it-system) with it own type category (it-system-type).

Expand

title	Click here to expand the System Descriptor

Code Block

language	xml
title	System 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

title	Click here to expand the Lifecycle Phase Descriptor

Code Block

language	xml
title	Lifecycle 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>

Section

title	Limitations

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

title	What 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 for the DTSMP and do not hesitate to get in touch!

Blog

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 3

New Version 4

Key

About

Keep up-to-date!

Powered by