Create Doctypes with a Model

...

Section

title	Our Solution to the Problem

We have defined a simple model for add-ons, spaces, and doctypes that can be specified with XML files. We provide XML schema files to support template authors in writing those models.

Let's have a look at an exmple.

Code Block

language	xml
title	Slightly modified Cheat Doctype

<doctype
  xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  id="cheat"
  base-template="standard"
  provide-type="standard-type"
  category="default">
  <resource-bundle>
    <l10n>
      <name>Cheat</name>
      <description>
        A brief solution to a problem.
      </description>
      <about>
        Cheats are brief solutions to a problem. They are short, to the point,
        and can be easily shared with your team.
      </about>
    </l10n>
  </resource-bundle>

  <properties>
    <property key="projectdoc.doctype.common.type">
      <value>
        <macro name="projectdoc-name-list">
          <param name="doctype">cheat-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.cheat.level-of-experience-required">
      <value>
        <macro name="projectdoc-name-list">
          <param name="doctype">experience-level</param>
          <param name="property" key="projectdoc.doctype.cheat.level-of-experience-required" />
          <param name="render-no-hits-as-blank">true</param>
        </macro>
      </value>
      <resource-bundle>
        <l10n>
          <name>Level of Experience</name>
          <description>
            The level of experience expected the cheat addresses.
          </description>
        </l10n>
      </resource-bundle>
    </property>
  </properties>

  <sections>
    <section key="projectdoc.doctype.common.description">
      <resource-bundle>
        <l10n>
          <description>
            Provide an optional overview over the context the cheat is applied
            in.
          </description>
        </l10n>
      </resource-bundle>
    </section>

    <section key="projectdoc.doctype.common.summary">
      <resource-bundle>
        <l10n>
          <name>Summary</name>
          <description>
            Provide a solution to the problem.
          </description>
        </l10n>
      </resource-bundle>
    </section>
    <section key="projectdoc.doctype.cheat.examples">
      <resource-bundle>
        <l10n>
          <name>Examples</name>
          <description>
            Provide some examples on how the cheat looks like when applied.
          </description>
        </l10n>
      </resource-bundle>
    </section>
  </sections>

  <related-doctypes>
    <doctype-ref id="asset" />
    <doctype-ref id="todo" />
    <doctype-ref id="event" />
  </related-doctypes>
</doctype>

In this example you see a very slightly simplifed version of the Cheat doctype (see the current version of the doctype on Bitbucket). It defines two properties and gets a lot of standard properties inherited due to the reference to the standard base template. It also defines two sections and again, inherits a number of standard sections from the standard base template.

Due to the value of the provide-type attribute, another doctype, called Cheat Type, will be created. This will allow authors to categorize cheats with a doctype-specific type.

The doctype is associated with a default category. Doctype categories are used for grouping doctypes and render lists of references in a space homepage. Related doctypes – as you can see on the bottom of the XML document – are links rendered on homepages and index pages. Both structures support navigation and help readers to find information by browsing.

...

Section

title	Limitations

This is just the start of a journey. There are still features that cannot yet be expressed with the XML models.

For instance the Module Type needs to list all documents with its type automatically. To specify such a section with a Display Table Macro running the query and listing the result set, you need to add plain XML of the storage format (xml element with the CDATA block inside).

Code Block

    <section key="projectdoc.doctype.module-type.modules-of-type">
      <xml><![CDATA[      <ac:structured-macro ac:name="projectdoc-section">
        <ac:parameter ac:name="title"><at:i18n at:key="projectdoc.doctype.module-type.modules-of-type"/></ac:parameter>
        <ac:rich-text-body>
          <ac:structured-macro ac:name="projectdoc-display-table">
            <ac:parameter ac:name="doctype">docmodule</ac:parameter>
            <ac:parameter ac:name="select"><at:i18n at:key="projectdoc.doctype.common.name"/>, <at:i18n at:key="projectdoc.doctype.common.shortDescription"/></ac:parameter>
            <ac:parameter ac:name="where">$&lt;<at:i18n at:key="projectdoc.doctype.common.type"/>&gt; = [${<at:i18n at:key="projectdoc.doctype.common.name"/>}]</ac:parameter>
            <ac:parameter ac:name="sort-by"><at:i18n at:key="projectdoc.doctype.common.sortKey"/>, <at:i18n at:key="projectdoc.doctype.common.name"/></ac:parameter>
            <ac:parameter ac:name="render-no-hits-as-blank">true</ac:parameter>
          </ac:structured-macro>
        </ac:rich-text-body>
      </ac:structured-macro>]]>
      </xml>
      <resource-bundle>
        <l10n>
          <name>Modules of this Type</name>
        </l10n>
        <l10n locale="de">
          <name>Dokumentationsmodule dieses Typs</name>
        </l10n>
      </resource-bundle>
    </section>

A second issue is controlling the wizard or adding validation using JavaScript. While there is a basic form with validation generated, more complex requirements need to be written to a plain Soy or JavaScript file and will override the generated code at the end of the process.

With this approach it is possible to use the plugin in a Maven build process and generate the required blueprints. Later new features can be added and the overriding parts can be replaced.

Section

title	How to get started

If you are interested to give the Doctype Maven Plugin a try, then

Start with Create a new Doctype Model – this will create a new project ready to add your descriptors for your add-on
Have a look at the projectdoc Model Descriptors – this will help you understand the configuration options
Checkout model projects on Bitbucket – see how things work
Get familiar with Prerequisites and Project Settings – understanding these will make your configuration life easier
Learn about Patching – to know how to work around limitations imposed by the plugin
Understand use cases with Usage

Section

title	Prerequisites

...

Space shortcuts

Page tree

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