[[PageOutline(2-5,Contents,pullout)]]

{{{
#!NewsFlash
'''Status'''

The trunk is a development version that works with Trac 0.11 and later. The code is thought to be stable, but please be ready to do some testing and report defects if you intend to install it on a production system. A tag will be created for version 2.0 when the code is known to be stable. Posting a note to #9958 about your experience using the plugin would be very appreciated.

'''Planned Enhancements'''
 * Work towards v2.0, improving documentation and fixing minor defects.
 * Render plantuml files from repository #7053.
}}}

= Render PlantUML Diagrams

== Description

[http://plantuml.sourceforge.net/ PlantUML] is a java utility that allows generation of different types of UML diagrams (sequence, activity, state, use cases, objects, ...) from a simple text description file.

This plugin allows the integration of PlantUML on Trac Wiki pages, dynamically generating and embedding the diagrams.

== Bugs/Feature Requests

Existing '''[report:9?COMPONENT=PlantUmlMacro bugs and feature requests]''' for !PlantUmlMacro.

If you have any issues, create a '''[/newticket?component=PlantUmlMacro&cc=airadier new ticket]'''.

[[TicketQuery(component=PlantUmlMacro&group=type,format=progress)]]

== Download

Download the zipped source from [download:plantumlmacro here].

== Source

You can check out PlantUmlMacro from [http://trac-hacks.org/svn/plantumlmacro here] using Subversion, or [source:plantumlmacro browse the source] with Trac.

== Installation

  1. '''Note''':
     1. Below instructions should be specific to some operating systems. Please help expanding these instructions.
     1. Broader installation guidelines are made available at [http://trac.edgewall.org/wiki/TracPlugins TracPlugins].
     1. Unused sections are for future use and are suggested to be commented out. For example:
        {{{
        {{{
        #!comment
        1. '''Check''' dependencies:
           i. none required
        }}}        
        }}}
     1. `[sudo]` is optional in case you already have enough authorisation to modify your server.
     [[BR]]
  2. '''Check''' dependencies:
     1. A valid Java runtime environment.
     1. [http://plantuml.sourceforge.net/download.html plantuml.jar]: save it to the location that you'll specify in the configuration section `/path/to/plantuml.jar`.
        * 
          {{{
          #!sh
          [sudo] wget http://sourceforge.net/projects/plantuml/files/plantuml.jar/download
          }}}
        * Check version of PlantUML jar:
          {{{
          #!sh
          cd /path/to/plantuml.jar
          [sudo] java -jar plantuml.jar -version
          }}}
     1. [http://www.graphviz.org/ Graphviz]: check if installed and working as required in [http://plantuml.sourceforge.net/graphvizdot.html graphvizdot].
        {{{
        #!sh
        [sudo] java -jar plantuml.jar -testdot
        }}}
        [[BR]]
  1. '''Install''' component: 
     * with easy_install, globally:
       {{{
       #!sh
       [sudo] easy_install https://trac-hacks.org/svn/plantumlmacro/trunk
       }}}
       [[BR]]
  1. '''Enable''' this component as follows:
     * by updating [wiki:TracIni trac.ini] file under appropriate configuration section;
       {{{
       #!ini
       [components]
       plantuml.* = enabled
       }}}
     * or accessing your Admin panel (under selected Trac environment {{{ ..admin/general/plugins }}}).
     [[BR]]
  1. '''Configure''' the Trac environment as follows:
     * by updating [wiki:TracIni trac.ini] file under appropriate configuration section;
       {{{
       #!ini
       [plantuml]
       plantuml_jar = /path/to/plantuml.jar
       java_bin = /path/to/java_bin (optional, if Java binary is not on the search path)
       }}}
       * example `plantuml_jar = /project-resources/trac/plugins`
       * example `java_bin = java` assumes that the Java binary is on the search path.[[BR]][[BR]]
     * or accessing your Admin panel (under selected Trac environment {{{ ..admin/general/plugins }}}).
     [[BR]]
  1. '''Restart''' web server:
     * Apache on Ubuntu, example command line:
       {{{
       #!sh
       [sudo] /etc/init.d/apache2 restart
       }}}
       [[BR]]
  1. '''Test''' if this component is working properly (main environment and secondary ones if you have). If this component is installed correctly, then the example shown in the [#Usage] section should be also displayed on the WikiMacros#PlantUML-macro page.   

== Usage

 1. As a !WikiProcessor with markup:
 {{{
{{{#!plantuml
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml
}}}
}}}
 will render the following UML diagram:

 [[Image(sequence.PNG)]]

 2. Documentation can be found on the WikiMacros page after installing the macro.

 3. More information on the PlantUML language and different types of UML diagrams can be found on the [http://plantuml.sourceforge.net/sources.html PlantUML Website].

== Recent Changes

[[ChangeLog(plantumlmacro, 3)]]

== Author/Contributors

'''Author:''' [wiki:airadier] [[BR]]
'''Maintainers:''' [[Maintainer]], rjollos [[BR]]
'''Contributors:''' ebencheung, Erwin Rademaker