Versions Compared

Key

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

...

Section


Column


Document Properties Marker
overridefalse


Short DescriptionA short introduction to use projectdoc services in the context of velocity to integrate with user macros.
Doctypetopichide
NameUser Macro Integration
Short Name
Parent
Parent Property
property-nameName
hide
Audience
Name List
doctyperole
render-no-hits-as-blanktrue
property-restrict-value-rangetrue
propertyAudience
empty-as-nonetrue

Subject
Name List
doctypesubject
propertySubject

Categories
Name List
doctypecategory
property-restrict-value-rangetrue
propertyCategories

Tags
Tag List
propertyTags

Flagshide
Iteration

Iteration
valueproduction

hide
Type
Name List
doctypetopic-type
render-no-hits-as-blanktrue
property-restrict-value-rangetrue
propertyType

Level of Experience
Name List
doctypeexperience-level
render-no-hits-as-blanktrue
propertyLevel of Experience

Expected Duration
Sponsors
Name List
doctypestakeholder
render-no-hits-as-blanktrue
propertySponsors

Sort Keyhide
Since4.1



Section
show-titlefalse
titleDescription

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

Marcos

Macros.

Column
width40%

Table of Contents
indent15px
stylenone

The services are registered in the Velocity context.


Section
titleSummary


Section
titlePrerequisites

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



Column
width40%


Panel
titleContents

Table of Contents
indent15px
stylenone





Section
titleServices

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

Section
titleprojectdoc Document Manager

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

Section
titlegetDocumentByPageId


pageIdThe identifier of a Confluence page.

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

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



Section
titlegetDocumentByPage


pageA Confluence page.

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

Code Block
languagexml
#set ( $page = $pageManager.getPage(819207)) 

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



Section
titlegetDocumentBasicsByPageId


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.


Section
titlegetDocumentBasicsByPage


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.



Section
titleprojectdoc Document Property Manager

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

Section
titlegetDocumentPropertyAsString (by page)


pageA Confluence page.
nameThe name of the property.

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

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



Section
titlegetDocumentPropertyAsString (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.

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



Section
titlegetDocumentPropertyByKeyAsString (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.

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



Section
titlegetDocumentPropertyByKeyAsString (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.

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




...

Section
titleDomain Objects

The following domain objects are returned by the services.

Section
titleProjectdocDocument


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

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

Code Block
languagejava
titleinterface ProjectdocPropertiesDocument
package de.smartics.projectdoc.atlassian.confluence.api.domain;

import com.atlassian.confluence.pages.Page;

import java.util.Date;

import javax.annotation.Nullable;
 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);
}



Section
titleProjectdocDocumentProperty


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

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

Code Block
languagejava
titleinterface 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);
}



...

Section
titleResources

Information to related topic regarding APIs and User Macros.

Tour
render-no-hits-as-blanktrue
render-as-definition-listtrue
marker-column-property-nameTitle
replace-title-with-nametrue


TitleShort Description
Writing User MacrosUser 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 moduleVelocity 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 VelocityConfluence 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 SyntaxThis page provides information about the code you can enter in a user macro template.
Web API Extension
User Macros