DocGenerator API: creating the wiki content

This article presents how to create the wiki content through docJGenerator API.

Creating an article

You can create an article through one of the following methods:

• DocGeneratorAPI.createArticle(String) create an article with the specified description
• DocGeneratorAPI.createArticle(String, boolean, boolean) create an article with the specified description. The second argument specifies if the article should have a table of content, and the last one if the case should be kept

These methods return a XMLArticle.

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
         
   XMLArticle article = api.createArticle("the first article");

Creating an opaque article

Several methods allow to create an opaque article, which is an article which can be used in references, but is not generated in the wiki:

• DocGeneratorAPI.createOpaqueArticle(String) create an opaque article with the specified description
• DocGeneratorAPI.createOpaqueArticle(String, boolean) create an opaque article with the specified description

Getting the index

The index article can be retrieved through the DocGeneratorAPI.getIndex() method.

Categories

Adding a category

You can add a category though the DocGeneratorAPI.createCategory(String, String) method.

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
      
   api.createCategory("general", "Deals about general subjects");

Applying categories to an article

You can put an article in one or several categories through the DocGeneratorAPI.setCategories(XMLArticle, String...) method.

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
      
   api.createCategory("general", "Deals about general subjects");
   api.createCategory("user", "Deals about user features");      
         
   XMLArticle article = api.createArticle("the first article");
   api.setCategories(article, "general", "user");

Setting a custom search category to an article

If you have set a custom search for the wiki, you can set a custom search category for an article.

For example:

  DocGeneratorAPI api = new DocGeneratorAPI();
      
  CustomSearchCategories categories = api.getCustomSearchCategories();
  categories.addCategory("Bird");
  categories.addCategory("Mammal");  
           
  api.createModel();   
         
  XMLArticle article = api.createArticle("an article about birds");
  categories.addArticle(article, "Bird");

Paragraphs

The content in articles must be added through AbstractParagraph.

To add a paragraph in an article, you can either use:

• DocGeneratorAPI.addParagraph(XMLParent) create a new paragraph in the article
• DocGeneratorAPI.getLastParagraph(XMLParent) return the last paragraph in the article, or creates one if there is no paragraph in the article yet

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an article and add a paragraph in this article
   XMLArticle article = api.createArticle("the first article");
   XMLParagraph par = api.addParagraph(article);

Paragraphs in the internal article structure

It is necessary to have at least one paragraph in an article, but you don't need to create sub-paragraphs in the internal article structure. For example the following code is valid:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an article and add a paragraph in this article
   XMLArticle article = api.createArticle("the first article");
   AbstractParagraph par = api.getLastParagraph(article);
      
   // add a title and text under the title
   api.addTitle(article, par, "the title");
   api.addSentence(par, "the text under the title");      

Use the last article paragraph

All the methods which accept a paragraph to put an element also accept directly the XMLArticle parent. In that case the API will create a paragraph if there is none, of use the last paragraph in the article.

For example:

  DocGeneratorAPI api = new DocGeneratorAPI();
  api.createModel();
  api.setOutputDirectory(<the wiki directory>);

  // create an article and add a paragraph in this article
  XMLArticle article = api.createArticle("the first article");
      
  // add a title and text under the title, a paragraph will be automatically created and added to the article
  api.addTitle(article, "the title");
  // the last paragraph will be used
  api.addSentence(article, "the text under the title");      

Sentences

To add a sentence, you can either use^[1]

There are equivalent methods using a ParagraphElement parent, for example: DocGeneratorAPI.addSentence(ParagraphElementParent, String)

:

• DocGeneratorAPI.addSentence(XMLArticle, String) adds a regular sentence
• DocGeneratorAPI.addSentence(XMLArticle, String, int) adds a regular sentence, and sets its font type

For example:

  DocGeneratorAPI api = new DocGeneratorAPI();
  api.createModel();
  api.setOutputDirectory(<the wiki directory>);

  // create an article
  XMLArticle article = api.createArticle("the first article");
      
  // add a sentence
  api.addSentence(article, "the regular sentence");      

Titles

To add a title, you can use one of the following methods^[2]

There are equivalent methods using a ParagraphElement parent, for example: DocGeneratorAPI.addTitle(XMLArticle, ParagraphElementParent, String)

:

• DocGeneratorAPI.addTitle(XMLArticle, String) is a basic method to create a title at the default level
• DocGeneratorAPI.addTitle(XMLArticle, int, String) is a basic method to create a title at a specified level
• DocGeneratorAPI.addTitle(XMLArticle, int, String, boolean) creates a title at a specified level, and sets if the character case of the first character must be kept
• DocGeneratorAPI.addTitle(XMLArticle, int, String, boolean, boolean) creates a title at a specified level, sets if the character case of the first character must be kept, and specifies if the title is searchable

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an article and adds a paragraph to this article
   XMLArticle article = api.createArticle("the first article");
      
   // add a title at the default level (1)
   api.addTitle(article, "the first title");                
   // add a sub-title at level 2, keeping the case for the title text
   api.addTitle(article, 2, "sub-title", true);                      

Setting a custom search category to a title

If you have set a custom search for the wiki, you can set a custom search category for a title.

For example:

  DocGeneratorAPI api = new DocGeneratorAPI();
      
  CustomSearchCategories categories = api.getCustomSearchCategories();
  categories.addCategory("Bird");
  categories.addCategory("Mammal");  
           
  api.createModel();   
         
  XMLArticle article = api.createArticle("an article about animals");
  XMLTitle title = api.addTitle(article, "the birds");        
  categories.addTitle(article, "Bird", title);

References

To add a reference, you can use one of the following methods^[3]

There are equivalent methods using a ParagraphElement parent, for example: DocGeneratorAPI.addReference(XMLArticle, ParagraphElementParent, String)

:

• DocGeneratorAPI.addReference(XMLArticle, String) will make a reference to the anchor identified by the refID argument
• DocGeneratorAPI.addReference(XMLArticle, String, String) does the same thing, but specifies the description of the reference
• DocGeneratorAPI.addReference(XMLArticle, XMLParentArticle) will make a reference to another article
• DocGeneratorAPI.addReference(XMLArticle, XMLParentArticle, String) does the same thing, but specifies the description of the reference
• DocGeneratorAPI.addReference(XMLArticle, AnchorElement) will make a reference to an anchor
• DocGeneratorAPI.addReference(XMLArticle, AnchorElement, String) does the same thing, but specifies the description of the reference

For example:

  DocGeneratorAPI api = new DocGeneratorAPI();
  api.createModel();
  api.setOutputDirectory(<the wiki directory>);

  // create an article 
  XMLArticle article = api.createArticle("the first article");
      
  // create a second article and adds a paragraph
  XMLArticle article2 = api.createArticle("the second article");
      
  // add a reference
  api.addReference(article2, "the first article", "the reference");      
  // could also be done with:
  api.addReference(article2, article, "the reference");            

Images

To add a image, you can use one of the following methods^[4]

There are equivalent methods using a ParagraphElement parent, for example: DocGeneratorAPI.addImage(XMLRootElement, ParagraphElementParent, BufferedImage, boolean)

:

• The DocGeneratorAPI.addImage(XMLArticle, BufferedImage, boolean) method adds an image coming from a BufferedImage instance
• The DocGeneratorAPI.addImage(XMLArticle, URL, boolean) method adds an image coming from an URL
• The DocGeneratorAPI.addImage(XMLArticle, File, boolean) method adds an image coming from a File

The API will take care not to add the same image to the resources more than once. For example, in the following example, there will be only one image resource referenced twice by the two articles:

  DocGeneratorAPI api = new DocGeneratorAPI();
  api.createModel();
  api.setOutputDirectory(<the wiki directory>);

  // create an article and adds a paragraph to this article
  XMLArticle article = api.createArticle("the first article");
  // add an image
  api.addImage(article, "d:/my/image.png", true);   
      
  // create a second article and adds a paragraph to this article
  article = api.createArticle("the first article");   
  // add the same image
  api.addImage(article, "d:/my/image.png", true);           

Tables

To add a table, you can use one of the following methods^[5]

There are equivalent methods using a ParagraphElement parent, for example: DocGeneratorAPI.addTable(XMLArticle, ParagraphElementParent, boolean)

:

• The DocGeneratorAPI.addTable(XMLArticle) method adds a table
• The DocGeneratorAPI.addTable(XMLArticle, boolean) method adds a table and specifies if it is sortable

It is possible to set a caption to the table, setting the width of the table, set the alignement of the table using the methods of the resulting XMLTable.

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an article and adds a paragraph to this article
   XMLArticle article = api.createArticle("the first article");
            
   // add a table      
   XMLTable table = api.addTable(article);
   table.setWidth(50, true); // set the width of the table as 50% of the width of the page
   table.setAlignment(Alignment.LEFT); // align the table to the left
   table.setCaption("List of birds"); // add a caption to the table     

Columns

To specify the columns of the table, you can use one of the following methods:

• The DocGeneratorAPI.addTableColumn(XMLTable) method adds a column
• The DocGeneratorAPI.addTableColumn(XMLTable, String) method adds a column with a title
• The DocGeneratorAPI.addTableColumn(XMLTable, String, SentenceStyle) method adds a column with a title with a style

It is possible to set the width of the resulting column with the following method:

• The XMLTableColumn.setWidth(int, boolean) specifies the width of the column

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an article and adds a paragraph to this article
   XMLArticle article = api.createArticle("the first article");
            
   // add a table      
   XMLTable table = api.addTable(article); 
   api.addTableColumn(table, "Classification");  

Rows

To add a row to the table, you can use one of the following methods:

• The DocGeneratorAPI.addTableRow(XMLTable) adds a new row
• The DocGeneratorAPI.addTableRow(XMLTable, boolean, int...) adds a new row with specified widths for the columns. Note that you don't need to use this method if you specified table columns with widths. It is only useful if you want to have rows with differents sizes for each columns per row

These methods return a XMLTableRow.

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an article and adds a paragraph to this article
   XMLArticle article = api.createArticle("the first article");
            
   // add a table      
   XMLTable table = api.addTable(article); 
   api.addTableColumn(table, "Classification");  
   XMLTableRow row = api.addTableRow(table);

Cells

To add a cell to a row, you can use one of the following methods:

• The DocGeneratorAPI.addTableCell(XMLTableRow) adds a new cell
• The DocGeneratorAPI.addTableCell(XMLTableRow, String) adds a new cell with a specified sentence
• The DocGeneratorAPI.addTableCell(XMLTableRow, String, SentenceStyle) adds a new cell with a specified sentence with a style

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an article and adds a paragraph to this article
   XMLArticle article = api.createArticle("the first article");
            
   // add a table      
   XMLTable table = api.addTable(article); 
   api.addTableColumn(table, "Classification"); 
   XMLTableRow row = api.addTableRow(table); 
   api.addTableCell(row, "Pigeon");
   row = api.addTableRow(table);
   api.addTableCell(row, "Crow"); 
   row = api.addTableRow(table);
   api.addTableCell(row, "Eagle");      

Lists

To add a list^[6]

This is a ul or ol element

, you must use one of the following methods:

• The DocGeneratorAPI.addList(XMLArticle, boolean) adds a new list
• The DocGeneratorAPI.addList(ParagraphElementParent, boolean) adds a new list in a specified parent

To add an item to the list, you can use one of the following methods:

• The DocGeneratorAPI.addListItem(XMLList) adds a new item in the list
• The DocGeneratorAPI.addListItem(XMLList, String) adds a sentence as a new item in the list
• The DocGeneratorAPI.addListItem(XMLList, String, SentenceStyle) adds a sentence with a style as a new item in the list

For example:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);

   // create an article and adds a paragraph to this article
   XMLArticle article = api.createArticle("the first article");
            
   // add a list      
   XMLList list = api.addList(article, true); // add an unordered list
   list.addItem("Bird");     
   list.addItem("Cat");           

Importing articles

Several methods allow to import articles from XML files. it is possible to:

• Import an XML article, which will be one of the articles in the generated wiki
• Include an XML article in an article created through the API
• It is even possible to import an Image definition file