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.html.*;
021
022/**
023 * Annotation that can be applied to classes, fields, and methods to tweak how they are handled by {@link HtmlSerializer}.
024 */
025@Documented
026@Target({TYPE,FIELD,METHOD})
027@Retention(RUNTIME)
028@Inherited
029public @interface Html {
030
031   /**
032    * Use the specified anchor text when serializing a URI.
033    * 
034    * <p>
035    * The text can contain any bean property values resolved through variables of the form <js>"{property-name}"</js>.
036    * 
037    * <h5 class='figure'>Example:</h5>
038    * <p class='bcode'>
039    *    <jk>public class</jk> FileSpace {
040    * 
041    *       <ja>@Html</ja>(anchorText=<js>"drive/{drive}"</js>)
042    *       <jk>public</jk> String getDrive() {
043    *          ...;
044    *       }
045    *    }
046    * </p>
047    */
048   String anchorText() default "";
049
050   /**
051    * Treat as plain text.
052    * 
053    * <p>
054    * Object is serialized to a String using the <code>toString()</code> method and written directly to output.
055    * Useful when you want to serialize custom HTML.
056    */
057   boolean asPlainText() default false;
058
059   /**
060    * Treat as XML.
061    * 
062    * <p>
063    * Useful when creating beans that model HTML elements.
064    */
065   boolean asXml() default false;
066
067   /**
068    * Adds a hyperlink to a bean property when rendered as HTML.
069    * 
070    * <p>
071    * The text can contain any bean property values resolved through variables of the form <js>"{property-name}"</js>.
072    * 
073    * <p>
074    * The URLs can be any of the following forms:
075    * <ul>
076    *    <li>Absolute - e.g. <js>"http://host:123/myContext/myServlet/myPath"</js>
077    *    <li>Context-root-relative - e.g. <js>"/myContext/myServlet/myPath"</js>
078    *    <li>Context-relative - e.g. <js>"context:/myServlet/myPath"</js>
079    *    <li>Servlet-relative - e.g. <js>"servlet:/myPath"</js>
080    *    <li>Path-info-relative - e.g. <js>"myPath"</js>
081    * </ul>
082    * 
083    * <h5 class='figure'>Example:</h5>
084    * <p class='bcode'>
085    *    <jk>public class</jk> FileSpace {
086    * 
087    *       <ja>@Html</ja>(link=<js>"servlet:/drive/{drive}"</js>)
088    *       <jk>public</jk> String getDrive() {
089    *          ...;
090    *       }
091    *    }
092    * </p>
093    */
094   String link() default "";
095
096   /**
097    * When <jk>true</jk>, don't add headers to tables.
098    * 
099    * <h5 class='section'>See Also:</h5>
100    * <ul>
101    *    <li class='jf'>{@link HtmlSerializer#HTML_addKeyValueTableHeaders}
102    * </ul>
103    */
104   boolean noTableHeaders() default false;
105
106   /**
107    * When <jk>true</jk>, collections of beans should be rendered as trees instead of tables.
108    * 
109    * <p>
110    * Default is <jk>false</jk>.
111    */
112   boolean noTables() default false;
113   
114   /**
115    * Associates an {@link HtmlRender} with a bean property for custom HTML rendering of the property.
116    * 
117    * <p>
118    * This annotation applies to bean properties and classes.
119    */
120   @SuppressWarnings("rawtypes")
121   Class<? extends HtmlRender> render() default HtmlRender.class;
122}