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

= Code example box with syntax highlighting

== Description

The CodeExampleMacro renders a code example box that supports syntax highlighting. It support three types of examples: simple, correct, and incorrect. The examples can be used for code review and functional testing.

Features:
 * The '''SELECT ALL''' link highlights all of the code in the box to simplify the copy and paste action.
 * A mouse click on the header (title) will show or hide the code block.
 * Code from the repository can be displayed using TracLinks syntax. The multiple repository configuration (Trac >= 0.12) is supported.

All rights reserved by [http://codedgers.com Codedgers Inc.]

== Usage

  1. Inside a wiki area you can invoke the `#!CodeExample` wiki processor to render a special formatted box containing specified source code, as shown and exemplified down:
     {{{
     {{{
     #!CodeExample
     ## parameter = value
     ....
     ## parameter = value
     #!language
     ...code...
     }}}
     }}} 
     * Where `## parameter = value` can be one or many from:
||'''Argument'''[[BR]]  ||'''Version'''[[BR]]  ||'''Required (R)[[BR]]Optional (O)''' ||'''Description'''[[BR]]	||'''Default'''[[BR]]  ||
|| `## type`  || || O || A type of box example: `simple`, `good`, `bad` [[BR]]* Example:  {{{ ## type = bad }}} || `simple` ||
|| `## title` || || O || The title of the example.[[BR]]* Example:  {{{ ## title = Source from repository A }}}  || If {{{## type = simple}}} then `EXAMPLE:`[[BR]]If {{{## type = good}}} then `CORRECT EXAMPLE:`[[BR]]If {{{## type = bad}}} then `INCORRECT EXAMPLE:` ||
|| `## path`  || || O || A file in the repository (using TracLinks format for source code)[[BR]]* Example:  {{{ ## path = GPGMail/Source/GPGMailPreferences.m }}}  || None ||
|| `## repo` || || O || Repository to use (Trac 0.12 and upper only).[[BR]]* Example:  {{{ ## repo = T.B.D. }}}  || None ||
|| `## regex` || || O || A regular expression indicates where to start an example.[[BR]]* Example:  {{{ ## regex = ".*updater\s*{" }}}  || None ||
|| `## lines` || || O || Number of lines to show.[[BR]]* Example:  {{{ ## lines = 3 }}}  || None ||
|| `#!language` || || O || Syntax highlighter. `language` is any supported by Trac. See TracSyntaxColoring.[[BR]]* Example:  {{{ #!python }}}  || `trac` ||
  2. The simple example:
     {{{
     {{{
     #!CodeExample
     #!python
     @staticmethod
     def get_templates_dirs():
         """ Notify Trac about templates dir. """
         from pkg_resources import resource_filename
         return [resource_filename(__name__, 'templates')]
     }}}
     }}}
     * will be rendered as:[[BR]]
      [[Image(example1.png)]][[BR]][[BR]]
  1. The incorrect example:
     {{{
     {{{
     #!CodeExample
     ## type = bad
     #!haskell
     fibs = 0 : 1 : [ a + b | a <- fibs | b <- tail fibs ]
     }}}
     }}}
     * will be rendered as:[[BR]]
       [[Image(example2.png)]][[BR]][[BR]]
  1. The correct example:
     {{{
     {{{
     #!CodeExample
     ## type = good
     #!haskell
     fibs = 0 : 1 : zipWith (+) fibs (tail fibs)
     }}}
     }}}
     * will be rendered as:[[BR]]
       [[Image(example3.png)]][[BR]][[BR]]
  1. There is also support for getting sources from the repository:
     {{{
     {{{
     #!CodeExample
     ## path=GPGMail/Source/GPGMailPreferences.m
     ## regex=".*updater\s*{"
     ## lines=3
     #!objective-c
     }}}
     }}}
     * will be rendered as:[[BR]]
       [[Image(example4.png)]]

== Installation

  {{{
  #!comment
  1. '''Check''' dependencies:
     i. none required

     * `[sudo]` is optional in case you have authorisation to modify your server.
  }}}
  1. '''Install''' plugin globally, for example with `easy_install`:
       {{{
       #!sh
       [sudo] easy_install https://trac-hacks.org/svn/codeexamplemacro
       }}}
        * `[sudo]` is optional in case you have authorisation to modify your server.
        * You might be required to select a specific `tag`, `branch`. Defaults to select from `trunk`.
  1. '''Enable''' this component by updating TracIni file as follows:
     {{{
     #!ini
     [components]
     codeexample.code_example_processor.* = enabled
     }}}
  {{{
  #!comment
  1. '''Configure''' this component in its own configuration section, by updating TracIni file as follows:
     i. none required
     {{{
     #!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.
  }}}
  1. '''Restart''' web server on command line:
     {{{
     #!sh
     [sudo] /etc/init.d/apache2 restart
     }}}
       * `[sudo]` is optional in case you have authorisation to modify your server.
  1. '''Test''' if this component is working properly. If the plugin is installed correctly, the example shown in the [#Usage] section on this page should be displayed.

== Bugs/Feature Requests

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

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

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

== Source & Download

You can [http://trac-hacks.org/svn/codeexamplemacro check out] !CodeExampleMacro using Subversion, or [source:codeexamplemacro browse the source] with Trac, or [download:codeexamplemacro download] the zipped source.

=== Recent Changes

[[ChangeLog(codeexamplemacro, 3)]]

== Author/Contributors

'''Author:''' [wiki:nuald] [[BR]]
'''Maintainer:''' [wiki:nuald], [wiki:rjollos] [[BR]]
'''Contributors:'''