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