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
024/**
025 * Annotation that can be applied to classes, fields, and methods to tweak how they are handled by {@link HtmlSerializer}.
026 *
027 * <p>
028 * Can be used in the following locations:
029 * <ul>
030 *    <li>Marshalled classes/methods/fields.
031 *    <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when used with {@link HtmlApply @HtmlApply}.
032 * </ul>
033 *
034 * <h5 class='section'>See Also:</h5><ul>
035 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/HtmlAnnotation">@Html Annotation</a>
036 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/HtmlSupport">HTML</a>
037 * </ul>
038 */
039@Documented
040@Target({ TYPE, FIELD, METHOD })
041@Retention(RUNTIME)
042@Inherited
043public @interface Html {
044
045   /**
046    * Use the specified anchor text when serializing a URI.
047    *
048    * <p>
049    * The text can contain any bean property values resolved through variables of the form <js>"{property-name}"</js>.
050    *
051    * <h5 class='figure'>Example:</h5>
052    * <p class='bjava'>
053    *    <jc>// Produces &lt;a href&#61;'...'&gt;drive&lt;/a&gt; when serialized to HTML.</jc>
054    *    <ja>@Html</ja>(anchorText=<js>"drive"</js>)
055    *    <ja>@URI</ja> <jc>// Treat property as a URL</jc>
056    *    <jk>public</jk> String getDrive() {...}
057    * </p>
058    *
059    * <p>
060    * This overrides the behavior specified by {@link HtmlSerializer.Builder#uriAnchorText(AnchorText)}.
061    *
062    * @return The annotation value.
063    */
064   String anchorText() default "";
065
066   /**
067    * Optional description for the exposed API.
068    *
069    * @return The annotation value.
070    * @since 9.2.0
071    */
072   String[] description() default {};
073
074   /**
075    * Specifies what format to use for the HTML element.
076    *
077    * @return The annotation value.
078    */
079   HtmlFormat format() default HtmlFormat.HTML;
080
081   /**
082    * Adds a hyperlink to a bean property when rendered as HTML.
083    *
084    * <p>
085    * The text can contain any bean property values resolved through variables of the form <js>"{property-name}"</js>.
086    *
087    * <p>
088    * The URLs can be any of the following forms:
089    * <ul>
090    *    <li>Absolute - e.g. <js>"http://host:123/myContext/myServlet/myPath"</js>
091    *    <li>Context-root-relative - e.g. <js>"/myContext/myServlet/myPath"</js>
092    *    <li>Context-relative - e.g. <js>"context:/myServlet/myPath"</js>
093    *    <li>Servlet-relative - e.g. <js>"servlet:/myPath"</js>
094    *    <li>Path-info-relative - e.g. <js>"myPath"</js>
095    * </ul>
096    *
097    * <h5 class='figure'>Example:</h5>
098    * <p class='bjava'>
099    *    <jk>public class</jk> FileSpace {
100    *
101    *       <ja>@Html</ja>(link=<js>"servlet:/drive/{drive}"</js>)
102    *       <jk>public</jk> String getDrive() {
103    *          ...;
104    *       }
105    *    }
106    * </p>
107    *
108    * @return The annotation value.
109    */
110   String link() default "";
111
112   /**
113    * When <jk>true</jk>, don't add headers to tables.
114    *
115    * <h5 class='section'>See Also:</h5><ul>
116    *    <li class='jm'>{@link HtmlSerializer.Builder#addKeyValueTableHeaders()}
117    * </ul>
118    *
119    * @return The annotation value.
120    */
121   boolean noTableHeaders() default false;
122
123   /**
124    * When <jk>true</jk>, collections of beans should be rendered as trees instead of tables.
125    *
126    * <p>
127    * Default is <jk>false</jk>.
128    *
129    * @return The annotation value.
130    */
131   boolean noTables() default false;
132
133   /**
134    * Associates an {@link HtmlRender} with a bean property for custom HTML rendering of the property.
135    *
136    * <p>
137    * This annotation applies to bean properties and classes.
138    *
139    * @return The annotation value.
140    */
141   @SuppressWarnings({
142      "rawtypes" // Raw types necessary for HtmlRender class parameter
143   })
144   Class<? extends HtmlRender> render() default HtmlRender.class;
145
146   /**
147    * Specifies the CSS style to apply to the HTML element containing the bean property value.
148    *
149    * <p>
150    * This is a simpler alternative to using {@link #render()} when you only need to apply CSS styling
151    * without custom content transformation.
152    *
153    * <h5 class='figure'>Example:</h5>
154    * <p class='bjava'>
155    *    <jc>// Apply styling to a bean property</jc>
156    *    <ja>@Html</ja>(style=<js>"white-space:normal;min-width:200px"</js>)
157    *    <jk>public</jk> String getField() {...}
158    * </p>
159    *
160    * <p>
161    * If both {@link #style()} and {@link #render()} are specified, the render takes precedence.
162    *
163    * @return The annotation value.
164    */
165   String style() default "";
166}