1 /*
2 * Copyright 2011 - Doxia :: Include Macro - Juergen Kellerer
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.tinyjee.maven.dim.extensions;
18
19 import java.util.Map;
20
21 import static org.tinyjee.maven.dim.IncludeMacroSignature.PARAM_SOURCE;
22 import static org.tinyjee.maven.dim.IncludeMacroSignature.PARAM_VERBATIM;
23
24 /**
25 * This extension re-arranges selected document sections (hierarchical headlines in Doxia) using a table of columns and rows.
26 * <p/>
27 * The actual layout is created using a specified number of columns and rows and does gracefully fallback to the standard layout
28 * if client side javascript is not available.
29 *
30 * @author Juergen_Kellerer, 2011-11-08
31 */
32 public class TableLayoutParameterTransformer extends AbstractParameterTransformer {
33
34 /**
35 * Enables this extension and sets a regular expression matching the section titles that should be transformed into a tabs.
36 * <p/>
37 * <b>Note:</b> Setting this property has no effect in case of "<code>source</code>" or "<code>source-class</code>" were
38 * specified with the macro call. This behaviour ensures that the parameter "<code>tabbed-panel</code>" can still be used
39 * with ordinary macro calls where a source or source-class was set.
40 * <p/>
41 * This parameter expects a regular expression that is used to select what sections are placed inside the table layout by matching
42 * the given section titles (headlines).<br/>
43 * By default the javascript looks for the first section that follows the include position and continues with all
44 * siblings (sections of the same level). Neither parent nor child sections are processed, therefore it's mostly safe
45 * to use the <i>match all</i> expression <code>.*</code> if all sub-sequent sections of the same nesting level should
46 * be formatted with table layout.
47 * <p/>
48 * Examples:<ul>
49 * <li>"<code>%{include|table-layout=.*|columns=2}</code>" - Transforms all following sections (of the same level) to tabs.</li>
50 * <li>"<code>%{include|table-layout=.*(Example).*|columns=*}</code>" - Formats all sections containing the word "Example"
51 * using a side by side view.</li>
52 * </ul>
53 */
54 public static final String PARAM_TABLE_LAYOUT = "table-layout";
55
56 /**
57 * Specifies the number of columns to render (defaults to '{@code *}').
58 * <p/>
59 * If this parameter is set to asterisk ("{@code *}") the number of columns is unbounded and
60 * calculates out of the number of sections divided by the defined rows. If both {@code columns} and {@code rows}
61 * is set to asterisk the number of columns equals the number of sections while the number of rows becomes "1".
62 */
63 public static final String PARAM_COLUMNS = "columns";
64
65 /**
66 * Specifies the number of rows to render (defaults to '{@code *}').
67 * <p/>
68 * If this parameter is set to asterisk ("{@code *}") the number of rows is unbounded and
69 * calculates out of the number of sections divided by the defined columns.
70 */
71 public static final String PARAM_ROWS = "rows";
72
73 /**
74 * Defines the direction for placing the sections in the table layout (defaults to '{@code top-down}').
75 * <p/>
76 * Possible values:<ul>
77 * <li>{@code top-down} - Places sections below each other and wraps when "{@code rows}" number of sections were placed.</li>
78 * <li>{@code left-right} or {@code ltr} - Places sections next to each other starting from <i>left</i> and wraps when
79 * "{@code columns}" number of sections were placed.</li>
80 * <li>{@code right-left} or {@code rtl} - Places sections next to each other starting from <i>right</i> and wraps when
81 * "{@code columns}" number of sections were placed.</li>
82 * </ul>
83 */
84 public static final String PARAM_DIRECTION = "direction";
85
86 /**
87 * Defines the gab (margin) between the table cells (defaults to '{@code 10pt}').
88 * <p/>
89 * Note: The gap can also be defined for the horizontal or vertical direction using {@code horizontal-gap} and {@code vertical-gap}.
90 */
91 public static final String PARAM_GAP = "gap";
92
93 /**
94 * Defines the width of the layout (defaults to '{@code 100%}').
95 */
96 public static final String PARAM_WIDTH = "width";
97
98 /**
99 * <b>Optional Parameter:</b> Defines the CSS style of the container hosting the elements.
100 * <p/>
101 * Example - Creates a right aligned floating box of all "<i>Hints</i>":<code><pre>
102 * %{include|table-layout=.*(Hint).*|columns=1|width=200|style=border: 1px solid gray; background-color:#eee; float: right;}</pre></code>
103 */
104 public static final String PARAM_STYLE = "style";
105
106 /**
107 * <b>Optional Parameter:</b> Defines the CSS style class of the container hosting the elements.
108 */
109 public static final String PARAM_STYLE_CLASS = "style-class";
110
111 /**
112 * <b>Optional Parameter:</b> Defines the CSS style of the TD elements.
113 */
114 public static final String PARAM_CELL_STYLE = "cell-style";
115
116 /**
117 * <b>Optional Parameter:</b> Specifies a comma separates list of width values (CSS format) to apply with the columns.
118 * The number of width values doesn't need to match the number of actual columns as missing values are interpolated.
119 */
120 public static final String PARAM_COLUMN_WIDTHS = "column-widths";
121
122 /**
123 * <b>Optional Parameter:</b> Specifies a comma separates list of classes to apply with the columns. The number of classes
124 * doesn't need to match the number of actual columns as missing values are interpolated.
125 */
126 public static final String PARAM_COLUMN_CLASSES = "column-classes";
127
128 /**
129 * <b>Optional Parameter:</b> Specifies a comma separates list of height values (CSS format) to apply with the rows.
130 * The number of height values doesn't need to match the number of actual rows as missing values are interpolated.
131 */
132 public static final String PARAM_ROW_HEIGHTS = "row-heights";
133
134 /**
135 * <b>Optional Parameter:</b> Specifies a comma separates list of classes to apply with the rows. The number of classes
136 * doesn't need to match the number of actual rows as missing values are interpolated.
137 */
138 public static final String PARAM_ROW_CLASSES = "row-classes";
139
140 private static final String OUT_PARAM_SECTIONS = "sections";
141
142
143 @Override
144 protected boolean doTransformParameters(Map<String, Object> params) {
145 Object sections = params.get(PARAM_TABLE_LAYOUT);
146 if (sections != null) {
147 params.put(PARAM_SOURCE, "classpath:/templates/dim/table-layout.html.vm");
148 params.put(PARAM_VERBATIM, false);
149 params.put(OUT_PARAM_SECTIONS, "*".equals(sections) ? ".*" : sections);
150
151 if ("left-right".equals(params.get(PARAM_DIRECTION)) || "left-to-right".equals(params.get(PARAM_DIRECTION)))
152 params.put(PARAM_DIRECTION, "ltr");
153 else if ("right-left".equals(params.get(PARAM_DIRECTION)) || "right-to-left".equals(params.get(PARAM_DIRECTION)))
154 params.put(PARAM_DIRECTION, "rtl");
155
156 return true;
157 }
158 return false;
159 }
160 }