You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 16 Next »

projectdoc Toolbox

A short introduction to use projectdoc services in the context of velocity to integrate with user macros.

Since
4.1

This Application Programming Interface (API) allows users of the projectdoc Toolbox to use a limited API to access projectdoc domain objects from User Marcos.

The services are registered in the Velocity context.

Prerequisites

Readers need to know how to write User Macros on Confluence and how to access services via the Velocity Context Module.

Services

This section lists services available in the velocity context to be used with user macros in Confluence.

projectdoc Document Manager

projectdoc documents are accessible via the projectdoc document manager by the key projectdocDocumentManager.

getDocumentByPageId

pageIdThe identifier of a Confluence page.

Provides access to a document with all properties set. The document is referenced by a page identifier.

#set ($document = $projectdocDocumentManager.getDocumentBasicsByPageId(819207)) 
#set ($property = $document.getProperty($paramName)) 
#set ($propertyValue = $property.getRenderedValue()) 

getDocumentByPage

pageA Confluence page.

Provides access to a document with all properties set. The document is referenced by a page.

#set ($page = $pageManager.getPage(819207)) 

#set ($document = $projectdocDocumentManager.getDocumentBasicsByPage($page)) 
#set ($property = $document.getProperty($paramName)) 
#set ($propertyValue = $property.getRenderedValue()) 

getDocumentBasicsByPageId

pageIdThe identifier of a Confluence page.

Provides access to a document with basic properties set. The document is referenced by a page identifier.

This version is faster in case only properties entered by a user are to accessed.

getDocumentBasicsByPage

pageA confluence page.

Provides access to a document with basic properties set. The document is referenced by a page.

This version is faster in case only properties entered by a user are to accessed.

projectdoc Document Property Manager

Properties of projectdoc documents are directly accessible via the projectdoc document property manager by the key  projectdocDocumentPropertyManager .

getDocumentPropertyAsString (by page)

pageA Confluence page.
nameThe name of the property.

Provides access to a document property by page and document property name.

#set ($page = $pageManager.getPage(819207)) 
#set ($propertyValue = $projectdocDocumentPropertyManager.getDocumentPropertyAsString($page, "Name")) 

getDocumentPropertyAsString (by page ID)

pageIdThe identifier of a Confluence page.
nameThe name of the property.

Provides access to a document property by page identifier and document property name.

#set ($propertyValue = $projectdocDocumentPropertyManager.getDocumentPropertyAsString(819207, "Name")) 

getDocumentPropertyByKeyAsString (by page)

pageA Confluence page.
nameThe name of the property.

Provides access to a document property value by page identifier and document property name key.

This allows to access a property dependent on the currently used locale.

#set ($page = $pageManager.getPage(819207)) 
#set ($propertyValue = 
  $projectdocDocumentPropertyManager.getDocumentPropertyByKeyAsString($page, "projectdoc.doctype.common.name")) 

getDocumentPropertyByKeyAsString (by page ID)

pageIdThe identifier of a Confluence page.
nameThe name of the property.

Provides access to a document property value by page identifier and document property name.

This allows to access a property dependent on the currently used locale.

#set ($propertyValue = 
  $projectdocDocumentPropertyManager.getDocumentPropertyByKeyAsString(819207, "projectdoc.doctype.common.name")) 

Domain Objects

The following domain objects are returned by the services.

ProjectdocDocument

typede.smartics.projectdoc.atlassian.confluence.api.domain.ProjectdocDocument

A view on a projectdoc document from the User Macro API.

interface ProjectdocPropertiesDocument
package de.smartics.projectdoc.atlassian.confluence.api.domain;

import com.atlassian.confluence.pages.Page;

import java.util.Date;

import javax.annotation.Nullable;

/**
 * A view on a projectdoc document for public access through the published API.
 */
public interface ProjectdocDocument {
  /**
   * Returns the page if the document refers actually to a page. If it is not a
   * page, <code>null</code> is returned.
   *
   * @return a reference to the page or <code>null</code>.
   */
  @Nullable
  Page getPage();

  /**
   * Returns the unique identifier of the Confluence document.
   *
   * @return the unique identifier of the Confluence document.
   */
  long getDocumentId();

  /**
   * Returns the key of the space the document is part of.
   *
   * @return the key of the space the document is part of.
   */
  String getSpaceKey();

  /**
   * Returns the title of the document in Confluence.
   *
   * @return the title of the document in Confluence.
   */
  String getTitle();

  /**
   * Returns the display title of the document in Confluence.
   *
   * @return the display title of the document in Confluence.
   */
  String getDisplayTitle();

  /**
   * Returns the path to the document within Confluence.
   *
   * @return the path to the document within Confluence.
   */
  String getUrlPath();

  /**
   * Returns the last modification date of the document in Confluence.
   *
   * @return the last modification date of the document in Confluence.
   */
  Date getLastModificationDate();

  /**
   * Returns the rendered property.
   *
   * @param the name of the property to return. <code>null</code> will be
   *        returned, if the property is unknown to the document.
   */
  @Nullable
  ProjectdocDocumentProperty getProperty(String propertyName);

  /**
   * Returns the rendered property identified by the property key. The property
   * key is the I18n resource key.
   *
   * @param propertyKey the key to the name of the property to return.
   *        <code>null</code> will be returned, if the property is unknown to
   *        the document.
   */
  @Nullable
  ProjectdocDocumentProperty getPropertyByKey(String propertyKey);
}

ProjectdocDocumentProperty

typede.smartics.projectdoc.atlassian.confluence.api.domain.ProjectdocDocumentProperty

A view on a projectdoc document property from the User Macro API.

interface ProjectdocDocumentProperty
package de.smartics.projectdoc.atlassian.confluence.api.domain;

/**
 * A view on a projectdoc document property for public access through the
 * published API.
 */
public interface ProjectdocDocumentProperty {
  /**
   * Returns the name of the property.
   *
   * @return the name of the property, never <code>null</code>.
   */
  String getName();

  /**
   * Returns the rendered value as based on the storage format found in the
   * projectdoc document.
   * <p>
   * This is the value with style information. For instance, if the value is
   * boxed in a div element with class attributes, this structure is returned.
   * </p>
   *
   * @return the rendered value of the property.
   */
  String getRenderedValue();

  /**
   * Returns the normalized version of the rendered property value.
   * <p>
   * This is the text representation of the property value.
   * </p>
   *
   * @return the normalized rendered value of the property.
   */
  String getNormalizedRenderedValue();

  /**
   * Returns the original value as found in the projectdoc document in storage
   * format.
   *
   * @return the original value of the property.
   */
  String getOriginalValue();

  /**
   * Returns the normalized version of the original property value.
   * <p>
   * This is the text representation of the property value.
   * </p>
   *
   * @return the normalized original value of the property.
   */
  String getNormalizedOriginalValue();

  /**
   * Checks if the property is actually a section.
   *
   * @return <code>true</code> if the property is actually a section,
   *         <code>false</code> if it is actually a property.
   */
  boolean isSection();

  /**
   * Checks whether or not the property is associated with the given control.
   *
   * @param controlName the name of the control to check.
   * @return <code>true</code> if the property has this control attached,
   *         <code>false</code> otherwise.
   */
  boolean hasControl(String controlName);
}

Resources

Information to related topic regarding APIs and User Macros.

Writing User Macros
User macros are useful if you want to create your own custom macros. These can be to perform specific actions, apply custom formatting and much more. 
Velocity Context module
Velocity Context plugin modules enable you to add components to Confluence's velocity context, making those components available in templates rendered from decorators, themes, XWork actions or macros.
Confluence objects accessible from Velocity
Confluence has a few distinct Velocity contexts for different purposes in the application (user macros, email templates, and exports), but the most commonly used context is called the "default context".
User Macro Template Syntax
This page provides information about the code you can enter in a user macro template.
Web API Extension
Add-on to extend projectdoc with an API to access on the web.
  • No labels