Bundled Templates :: Macro Library

Experimental Warning: This 'bundled macro library' is currently experimental. Behaviour and interfaces may change without any prior notice.

The following macro library is bundled with DIM and loaded by default using the URI "classpath:/templates/dim/macro-library.vm". Library loading is configured via the velocity engine property "velocimacro.library" and this bundled library is loaded prior to the default library "VM_global_library.vm". See Extensions Reference for more information on how to adjust this.

When the velocity engine is initialized, the libraries are resolved using the same path resolution logic as used everywhere else within the macro, thus providing a custom default library can be achieved by putting it into one of the search paths, e.g. directly below "site" use "src/site/VM_global_library.vm".

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
#**
 * Sets the variable '$outIsMarked' to true when $javaElement was marked with the given annotation
 * or corresponding javadoc tag.
 *
 * Example Usage:
 *
 * #dim_checkIsMarkedWith($javaElement, "@Deprecated", $deprecated)
 * #if($deprecated) <b><i>$javaElement.name is deprecated!</i></b> #end
 *#
#macro(dim_checkIsMarkedWith $javaElement $annotation $outIsMarked)
    #set($tagOfAnnotation = $annotation.substring(1))
    #set($outIsMarked = (
        $javaElement.annotations.containsKey("$annotation") ||
        $javaElement.tags.containsKey($tagOfAnnotation) ||
        $javaElement.tags.containsKey($display.uncapitalize($tagOfAnnotation))))
#end
  
#**
 * Prints the given text if $javaElement is deprecated.
 *#
#macro(dim_printIfDeprecated $javaElement $text)
    #dim_checkIsMarkedWith($javaElement, "@Deprecated", $dim_deprecated)
    #if($dim_deprecated) $text #end
#end
  
#**
 * Prints the value of the tag @since if it exists on $javaElement or $defaultValue if not.
 *#
#macro(dim_printSince $javaElement $defaultValue)
    #if($javaElement.tags.containsKey("since")) $javaElement.tags.since #else $defaultValue #end
#end
  
#**
 * Maps $file to a classpath that is defined in $classpathMappingTable.
 *
 * It may be advisable to setup a custom $classpathMappingTable when using one of the
 * offered *_attach* macros within your own templates.
 *#
#macro(dim_mapFileToClassPath $file $outFileClassPath)
    #if (!$classpathMappingTable) #set($classpathMappingTable = {
    'dim/js' : 'classpath:/templates/dim/js',
    'dim/css' : 'classpath:/templates/dim/css',
    'dim/images' : 'classpath:/templates/dim/images',
    'js' : 'classpath:/js-bundle'
    })
    #end
  
    #if (!$file.contains("/")) #set($outFileClassPath = "$file")
    #else
        #set($prefix = $file.substring(0, $file.lastIndexOf('/')))
        #if($classpathMappingTable.containsKey($prefix))
            #set($outFileClassPath = "$classpathMappingTable.get($prefix)$file.substring($prefix.length())")
        #else
            #set($outFileClassPath = "$file")
        #end
    #end
#end
  
#**
 * Includes a set of bundled JavaScript libraries and sets $outSuccess=true if the operation was successful.
 *
 * Example Usage:
 *
 * #dim_attachJs(["jquery", "jquery.json.min", "jstorage.min"], $librariesIncluded)
 * #if($librariesIncluded)
 *      <script>jQuery(..)</script>
 * #end
 *#
#macro(dim_attachJs $librariesToAttach $outSuccess)
    #set($outSuccess = $globals.HTMLCapableSink)
    #if($outSuccess)
        #foreach($file in $librariesToAttach)
            #if (!$file.contains("/")) #set($file = "js/$file") #end
            #dim_mapFileToClassPath($file, $filePath)
            #if (!$globals.attachJs("${file}.js", "${filePath}.js")) #set($outSuccess = false) #end
        #end
    #end
#end
  
#**
 * Does the same as dim_attachJs() but operates on CSS instead of JS.
 *#
#macro(dim_attachCss $cssToAttach $outSuccess)
    #set($outSuccess = $globals.HTMLCapableSink)
    #if($outSuccess)
        #foreach($file in $cssToAttach)
            #dim_mapFileToClassPath($file, $filePath)
            #if (!$globals.attachCss("${file}.css", "${filePath}.css")) #set($outSuccess = false) #end
        #end
    #end
#end
  
#**
 * Attaches binary content like images and sets $outHref with a HREF value that can
 * be used within a page to reference the attached content.
 *
 * Example Usage:
 *
 * #dim_attachBinary("dim/images/tabbed-panel-top-border.png", $topBorderImage)
 * <img src="$topBorderImage"/>
 *#
#macro(dim_attachBinary $binaryToAttach $outHref)
    #dim_mapFileToClassPath($binaryToAttach, $filePath)
    #set($outHref = $globals.attachBinaryContent($binaryToAttach, $filePath))
#end