freemarker-visualizer

freemarker-visualizer

:construction: Work in Progress! :construction:

Introduction

A command-line utility to produce visual graphs of FreeMarker file trees. It was inspired by Madge, a library that produces visual graphs of JavaScript dependencies.

• Files specified in <#import /> and <#include /> directives are graphed by default
• Plugins can be used to add additional information to the graph

Setup

npm install -g freemarker-visualizer

Install graphviz:

# OS X:
brew install graphviz || port install graphviz
# Fedora:
dnf install graphviz
# Ubuntu:
apt-get install graphviz

Usage

Graph file tree:

freemarker-visualizer path/to/template.ftl --directories path/to/dir

This will display a visual graph.

Save graph as an image:

freemarker-visualizer path/to/template.ftl --directories path/to/dir --image graph.svg

This will save graph.svg in the cwd.

Specify multiple template directories:

freemarker-visualizer path/to/template.ftl --directories dir1 dir2

This is useful in a project that has multiple base template directories. To avoid difficulty using freemarker-visualizer, the directories may be set in a configuration file.

Add additional template info:

freemarker-visualizer path/to/template.ftl --directories path/to/dir --plugins path/to/plugin.js

This will generate a graph with additional information about each processed template.

Configuration

Property	Type	Default	Description
directories	Array	null	paths of base directories to search for templates
plugins	Array	null	paths to plugins
template	String	null	path to template
image	String	graph.png	path for generated graph image

You can add a configuration file in .config/freemarker-visualizer/config.js in your home directory or provide it through the --config flag.

Writing plugins

To generate additional information about each template, a plugin can be referenced through the cli or added to the configuration file.

Each plugin must:

• be a JavaScript file
• export a function with a data parameter
• return an object with the new information to be displayed

See example plugins for more information.

Limitations

Currently, this utility will ignore template paths that are not relative to one of the provided base template directories. For example, "*/template.ftl" would not be resolved.