Home » Download » Modules

Graphviz Filter

· ·
kratib - January 17, 2008 - 22:46
Graphviz Filter

Graphviz Filter is a fun little filter that treats input text as Graphviz DOT syntax, converts it using Graphviz tools to the requested format(s) and renders it in HTML. It's useful to quickly create graphs dynamically from within Drupal nodes. A particularly exciting application is to create an input format consisting of PHP code followed by Graphviz Filter, thereby allowing one to write code that outputs a DOT file, which is then rendered to HTML. For example, one could create a visual taxonomy tree with nodes hanging from the terms, and each visual node would be clickable (using the URL Graphviz attribute) to point to the actual Drupal node. Stuff like that!

Thanks to varienne for the great documentation (in the Resources section below)!

REQUIREMENTS & INSTALLATION

Graphviz tools

  • Ubuntu/Debian:
    sudo apt-get install graphviz
  • Windows: Download version 2.21 or higher as version 2.20 seemed to cause problems.
  • Mac OS X + MAMP: Download version 2.21 or higher as version 2.20 seemed to cause problems.
    Set Apache to find the newly-installed commands by appending to the file /Applications/MAMP/Library/bin/envvars:
    export PATH="$PATH:/usr/local/bin"

    then restart Apache.
  • Ensure that the Graphviz tools are on the system PATH by opening a console and typing:
    dot -V

    If the command is not found, you will need to troubleshoot as described in the documentation below.

PEAR::Image_GraphViz

Not required for the core filter module, but required for both CCK Schema and Workflow Graph. Install this package by typing:

pear install Image_GraphViz

provided `pear` is on the system PATH. In Linux, you might need to prepend `sudo`.

USAGE

Enable the module, then add the Graphviz Filter to whatever input format you like. Enclose the DOT syntax within [graphviz]...[/graphviz] tags. In order to control the output, use the following arguments in the DOT comments:
* @command: Process the graph script using this Graphviz command (`dot`, `neato`, `twopi`, etc).
* @formats: Comma-separated list of desired output formats. Formats are listed in the filter info and tips.
* @title: Title of the output image.
In addition, each renderer can define its own arguments that are listed in the filter tips.

EXAMPLE

Put this in the body of a node whose input format is PHP code followed by Graphviz Filter:

<?php global $user ?>
[graphviz]
/*
* @formats = svg, png, gif
* @imagemap = true
*
*/
digraph G {
        fontname = "Bitstream Vera Sans"
        fontsize = 8

        node [
                fontname = "Bitstream Vera Sans"
                fontsize = 8
                shape = "record"
        ]

        edge [
                fontname = "Bitstream Vera Sans"
                fontsize = 8
        ]

        User [
                label = "{<?php echo $user->name ?>|+ name : string\l+ age : int\l|+ hello() : void\l}"
                URL = "http://www.drupal.org"
        ]
}
[/graphviz]

FREQUENTLY ASKED QUESTIONS

Q. How can I render a graph for [buddies, taxonomies, etc.] using this module?
A. Right now the module acts as a filter for nodes. In order to display any of the graphs you have in mind, you can use the following recipe:
1. Write a PHP function that generates a DOT script dynamically from the data you want to display, like the user relationships. The DOT syntax is pretty simple and you should be able to get meaningful output within an hour.
2. Create an input format made up of filters "PHP evaluator" followed by "Graphviz (DOT) syntax".
3. Create a page or story, select the input format that you just created, and call the function that you wrote. Upon submission, the node will render the Graphviz script. Of course, you can also write that function inside the page directly.
3a. Alternatively, you can write a module that exposes a menu item to render your graph. In the callback that implements the menu item, you would call the Drupal function check_markup() with the name of the Graphviz input format and the DOT script that you generated. Upon return you'd get the markup of the graph which you can embed in your own HTML.

Q. How can I render Wiki format in the same node as a Graphviz diagram?
A. Use the following recipe:
1. Use the PEAR Wiki Filter module.
2. Create an input format made up of filters "PEAR Wiki Filter" followed by "Graphviz (DOT) syntax".
3. Configure the PEAR Wiki Filter section of the new input format such that the "Ignore regexp" field is set to

/\[graphviz\](.*?)\[\/graphviz\]/si

4. If you want to include many filters with the PEAR Wiki Filter (such as GeSHi + Graphviz), set the "Ignore regexp" field to
/(\[graphviz\](.*?)\[\/graphviz\])|(\[geshifilter-code\](.*?)\[\/geshifilter-code\])/si

You can now type Wiki syntax in which you embed any number of [graphviz]..[/graphviz] blocks.

APPLICATIONS

* CCK Schema (included in this package): used to render a diagram of CCK types and relationships.
* Workflow Graph (included in this package as of 6.x-1.3): used to render diagrams of workflow definitions and histories.

TECHNICAL DETAILS

* Stores generated output in files/graphviz. Ensures uniqueness of filenames by naming them with md5 of input text.
* Uses two new hooks to allow new ways to render the graph:
hook_graphviz_formats() returns an array of Graphviz rendering formats that the module supports.

<?php
function mymodule_graphviz_formats() {
  return array(
    'myformat_1' => array(
      'description' => t('Format description'),
      'format' => 'png',
      'arguments' => array(
        'argument_1' => array('description' => t('Argument description'), 'value' => 'default value'),
      ),
    );
  );
}
?>

where the format entry refers to one of the supported DOT output formats. The filter will render the graph to this format and then hand the generated file to your module for embedding in HTML.

hook_graphviz_render($inpath, $outpath, $format, $args) actually renders the graph to an HTML fragment that is displayed as output of the filter. $inpath is input DOT file, $outpath is generated file, $format is the format being rendered (e.g. 'myformat_1' above), and $args is the array of arguments found in the DOT script.

Happy visualization!

Releases

Official releasesDateSizeLinksStatus
6.x-1.42009-May-0512.45 KBDownload · Release notesRecommended for 6.xThis is currently the recommended release for 6.x.
5.x-1.22008-Oct-219.87 KBDownload · Release notesRecommended for 5.xThis is currently the recommended release for 5.x.
Development snapshotsDateSizeLinksStatus
6.x-1.x-dev2009-Jun-0612.49 KBDownload · Release notesDevelopment snapshotDevelopment snapshots are automatically regenerated and their contents can frequently change, so they are not recommended for production use.
5.x-1.x-dev2008-Sep-209.87 KBDownload · Release notesDevelopment snapshotDevelopment snapshots are automatically regenerated and their contents can frequently change, so they are not recommended for production use.


 
 

Drupal is a registered trademark of Dries Buytaert.