001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall.html;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024import org.apache.juneau.marshall.*;
025import org.apache.juneau.marshall.serializer.*;
026
027/**
028 * Annotation for specifying config properties defined in {@link HtmlSerializer}, {@link HtmlParser}, and {@link HtmlDocSerializer}.
029 *
030 * <p>
031 * Used primarily for specifying bean configuration properties on REST classes and methods.
032 *
033 * <h2 class='section'>See Also:</h2><ul>
034 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/HtmlSupport">HTML</a>
035 * </ul>
036 */
037@Target({ TYPE, METHOD })
038@Retention(RUNTIME)
039@Inherited
040@ContextApply({ HtmlConfigAnnotation.SerializerApply.class, HtmlConfigAnnotation.ParserApply.class })
041public @interface HtmlConfig {
042
043   /**
044    * Add <js>"_type"</js> properties when needed.
045    *
046    * <p>
047    * If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
048    * through reflection.
049    *
050    * <p>
051    * When present, this value overrides the {@link org.apache.juneau.marshall.serializer.Serializer.Builder#addBeanTypes() Serializer.Builder#addBeanTypes()} setting and is
052    * provided to customize the behavior of specific serializers in a {@link SerializerSet}.
053    *
054    * <ul class='values'>
055    *    <li><js>"true"</js>
056    *    <li><js>"false"</js> (default)
057    * </ul>
058    *
059    * <h4 class='section'>Notes:</h4><ul>
060    *    <li class='note'>
061    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
062    * </ul>
063    *
064    * <h4 class='section'>See Also:</h4><ul>
065    *    <li class='jm'>{@link HtmlSerializer.Builder#addBeanTypesHtml()}
066    * </ul>
067    *
068    * @return The annotation value.
069    */
070   String addBeanTypes() default "";
071
072   /**
073    * Add key/value headers on bean/map tables.
074    *
075    * <p>
076    * When enabled, <bc>key</bc> and <bc>value</bc> column headers are added to tables.
077    *
078    * <p>
079    * The following shows the difference between the two generated outputs:
080    *
081    * <table class='styled'>
082    *    <caption>Serialized output without headers</caption>
083    *    <tr>
084    *       <th><c>withoutHeaders</c></th>
085    *       <th><c>withHeaders</c></th>
086    *    </tr>
087    *    <tr>
088    *       <td>
089    *          <table class='unstyled'>
090    *             <caption>Nested table without headers (1)</caption>
091    *             <tr><td>f1</td><td>foo</td></tr>
092    *             <tr><td>f2</td><td>bar</td></tr>
093    *          </table>
094    *       </td>
095    *       <td>
096    *          <table class='unstyled'>
097    *             <caption>Nested table without headers (2)</caption>
098    *             <tr><th>key</th><th>value</th></tr>
099    *             <tr><td>f1</td><td>foo</td></tr>
100    *             <tr><td>f2</td><td>bar</td></tr>
101    *          </table>
102    *       </td>
103    *    </tr>
104    * </table>
105    *
106    * <ul class='values'>
107    *    <li><js>"true"</js>
108    *    <li><js>"false"</js> (default)
109    * </ul>
110    *
111    * <h4 class='section'>Notes:</h4><ul>
112    *    <li class='note'>
113    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
114    * </ul>
115    *
116    * <h4 class='section'>See Also:</h4><ul>
117    *    <li class='jm'>{@link HtmlSerializer.Builder#addKeyValueTableHeaders()}
118    * </ul>
119    *
120    * @return The annotation value.
121    */
122   String addKeyValueTableHeaders() default "";
123
124   /**
125    * Don't look for link labels in URIs.
126    *
127    * <p>
128    * Disables the feature where if the URL has a label parameter (e.g. <js>"?label=foobar"</js>), then use that as the anchor text of the link.
129    *
130    * <p>
131    * The parameter name can be changed via the {@link HtmlSerializer.Builder#labelParameter(String)} property.
132    *
133    * <p>
134    * The following shows the difference between the two generated outputs.
135    * <br>Note that they're both hyperlinks, but the anchor text differs:
136    *
137    * <table class='styled'>
138    *    <caption>Serialized output with labels</caption>
139    *    <tr>
140    *       <th><c>withLabels</c></th>
141    *       <th><c>withoutLabels</c></th>
142    *    </tr>
143    *    <tr>
144    *       <td>
145    *          <table class='unstyled'>
146    *             <caption>Nested table with labels (1)</caption>
147    *             <tr><th>key</th><th>value</th></tr>
148    *             <tr><td>f1</td><td><a href='http://www.apache.org?label=Apache%20Foundation'>Apache Foundation</a></td></tr>
149    *          </table>
150    *       </td>
151    *       <td>
152    *          <table class='unstyled'>
153    *             <caption>Nested table with labels (2)</caption>
154    *             <tr><th>key</th><th>value</th></tr>
155    *             <tr><td>f1</td><td><a href='http://www.apache.org?label=Apache%20Foundation'>http://www.apache.org?label=Apache%20Foundation</a></td></tr>
156    *          </table>
157    *       </td>
158    *    </tr>
159    * </table>
160    *
161    * <ul class='values'>
162    *    <li><js>"true"</js>
163    *    <li><js>"false"</js> (default)
164    * </ul>
165    *
166    * <h4 class='section'>Notes:</h4><ul>
167    *    <li class='note'>
168    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
169    * </ul>
170    *
171    * <h4 class='section'>See Also:</h4><ul>
172    *    <li class='jm'>{@link HtmlSerializer.Builder#disableDetectLabelParameters()}
173    * </ul>
174    *
175    * @return The annotation value.
176    */
177   String disableDetectLabelParameters() default "";
178
179   /**
180    * Don't look for URLs in {@link String Strings}.
181    *
182    * <p>
183    * Disables the feature where if a string looks like a URL (i.e. starts with <js>"http://"</js> or <js>"https://"</js>, then treat it like a URL
184    * and make it into a hyperlink based on the rules specified by {@link HtmlSerializer.Builder#uriAnchorText(AnchorText)}.
185    *
186    * <p>
187    * The following shows the difference between the two generated outputs:
188    *
189    * <table class='styled'>
190    *    <caption>Serialized output with links</caption>
191    *    <tr>
192    *       <th><c>withLinks</c></th>
193    *       <th><c>withoutLinks</c></th>
194    *    </tr>
195    *    <tr>
196    *       <td>
197    *          <table class='unstyled'>
198    *             <caption>Nested table with links (1)</caption>
199    *             <tr><th>key</th><th>value</th></tr>
200    *             <tr><td>f1</td><td><a href='http://www.apache.org'>http://www.apache.org</a></td></tr>
201    *          </table>
202    *       </td>
203    *       <td>
204    *          <table class='unstyled'>
205    *             <caption>Nested table with links (2)</caption>
206    *             <tr><th>key</th><th>value</th></tr>
207    *             <tr><td>f1</td><td>http://www.apache.org</td></tr>
208    *          </table>
209    *       </td>
210    *    </tr>
211    * </table>
212    *
213    * <ul class='values'>
214    *    <li><js>"true"</js>
215    *    <li><js>"false"</js> (default)
216    * </ul>
217    *
218    * <h4 class='section'>Notes:</h4><ul>
219    *    <li class='note'>
220    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
221    * </ul>
222    *
223    * <h4 class='section'>See Also:</h4><ul>
224    *    <li class='jm'>{@link HtmlSerializer.Builder#disableDetectLinksInStrings()}
225    * </ul>
226    *
227    * @return The annotation value.
228    */
229   String disableDetectLinksInStrings() default "";
230
231   /**
232    * Link label parameter name.
233    *
234    * <p>
235    * The parameter name to look for when resolving link labels.
236    *
237    * <h4 class='section'>Notes:</h4><ul>
238    *    <li class='note'>
239    *       Default value: <js>"label"</js>
240    *    <li class='note'>
241    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
242    * </ul>
243    *
244    * <h4 class='section'>See Also:</h4><ul>
245    *    <li class='jm'>{@link HtmlSerializer.Builder#labelParameter(String)}
246    * </ul>
247    *
248    * @return The annotation value.
249    */
250   String labelParameter() default "";
251
252   /**
253    * Optional rank for this config.
254    *
255    * <p>
256    * Can be used to override default ordering and application of config annotations.
257    *
258    * @return The annotation value.
259    */
260   int rank() default 0;
261
262   /**
263    * Anchor text source.
264    *
265    * <p>
266    * When creating anchor tags (e.g. <code><xt>&lt;a</xt> <xa>href</xa>=<xs>'...'</xs>
267    * <xt>&gt;</xt>text<xt>&lt;/a&gt;</xt></code>) in HTML, this setting defines what to set the inner text to.
268    *
269    * <ul class='values'>
270    *    <li><js>"TO_STRING"</js> - Set to whatever is returned by {@link #toString()} on the object.
271    *    <li><js>"PROPERTY_NAME"</js> - Set to the bean property name.
272    *    <li><js>"URI"</js> - Set to the URI value.
273    *    <li><js>"LAST_TOKEN"</js> - Set to the last token of the URI value.
274    *    <li><js>"URI_ANCHOR"</js> - Set to the anchor of the URL.
275    *    <li><js>"CONTEXT_RELATIVE"</js> - Same as <js>"TO_STRING"</js> but assumes it's a context-relative path.
276    *    <li><js>"SERVLET_RELATIVE"</js> - Same as <js>"TO_STRING"</js> but assumes it's a servlet-relative path.
277    *    <li><js>"PATH_RELATIVE"</js> - Same as <js>"TO_STRING"</js> but assumes it's a path-relative path.
278    * </ul>
279    *
280    * <h4 class='section'>Notes:</h4><ul>
281    *    <li class='note'>
282    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"${C:myConfigVar}"</js>).
283    * </ul>
284    *
285    * <h4 class='section'>See Also:</h4><ul>
286    *    <li class='jm'>{@link HtmlSerializer.Builder#uriAnchorText(AnchorText)}
287    * </ul>
288    *
289    * @return The annotation value.
290    */
291   String uriAnchorText() default "";
292}