Scripts

The Scripting Plugin allows to use Groovy scripts to modify the content of the wiki before the generation.

The script will modify the content of the wiki source tree, which means that it will work with all kinds of inputs or outputs.

Use cases

Some uses cases for using scripts to modify the content of the wiki before the generation include automatically adding requirements to paragraphs for example.

Scripting property

To specify that you want to apply a script on the wiki source tree, you need to set the following command-line argument or configuration property:

• "scriptHandler" setting the path of the groovy script file specifying the script

Script implementation

A script is an implementation of the of the ElementHook interface, which will be used on then elements in the wiki source tree. This interface has the following methods:

public class org.docgene.plugins.ElementHook

Modifier and Type	Method and Description
public default void	createArticles() Create articles
public void	handleElement(ParagraphElement element) Handle an element
public default void	startArticle(XMLArticle article) Start the processing of an existing article
Set<String>	supportedElements() Return the set of elements declarations which will be handled by this ElementHook

• The supportedElements() method returns the Set of elements in the wiki source tree which will potentially be handled by the hook^[1]
  For example if you return "title", only syntax elements will be handled
  . See Elements declarations for more information
• The createArticles() method will be called after all exixting articles have been processed, and will allow to create new articles by scripting. See Creating an article through a script for more information
• The startArticle(XMLArticle) method will be called for all articles encountered by the script
• The handleElement(ParagraphElement) method will be called for all elements in the wiki source tree whose declaration ID is supported. For example, if supportedElements() returns a set with only "title", the method will be fired only for syntax elements

The script will be called exactly as any other ElementHook, so the tree visit will be performed exactly in the same way.

Modifying the tree content

To modify the wiki source tree content, the script have access to an instance of the DocJScriptContext (named context) which offer methods to modify the tree content. The methods include:

• Inserting a list of elements in the source tree before or after the current element
• Removing the current element

Creating an article through a script

The createArticles() method will be called after all exixting articles have been processed, and will allow to create new articles by scripting. For example:

   public void createArticles() {
      XMLArticle article = context.createArticle("myArticle");
      XMLParagraph par = context.addParagraph(article);
      par.addElement(new XMLTitle(1, "theTitle", false));
   }

Example

The following script will add a Requirement tag after each title:

   int indexReq = 0;

   public Set<String> supportedElements() {
      return context.getSupportedDeclarations("title");
   }

   public void handleElement(ParagraphElement element) {
      XMLTitle title = (XMLTitle)element;
      context.insertElementsAfter(new XMLSentence("Requirement: " + indexReq));
      indexReq++;
   }