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.bean.html5; 018 019import java.net.*; 020 021import org.apache.juneau.marshall.*; 022 023/** 024 * DTO for an HTML <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#the-area-element"><area></a> 025 * element. 026 * 027 * <p> 028 * The area element defines a clickable region within an image map. It is used in conjunction with 029 * the map element to create interactive images with multiple clickable areas, each linking to 030 * different destinations. 031 * 032 * <h2 class='section'>Examples:</h2> 033 * <p class='bcode w800'> 034 * <jc>// Rectangular clickable area</jc> 035 * Area <jv>area1</jv> = <jsm>area</jsm>().shape(<js>"rect"</js>).coords(<js>"0,0,100,50"</js>).href(<js>"https://example.com/page1"</js>); 036 * 037 * <jc>// Circular clickable area</jc> 038 * Area <jv>area2</jv> = <jsm>area</jsm>().shape(<js>"circle"</js>).coords(<js>"150,75,50"</js>).href(<js>"https://example.com/page2"</js>); 039 * 040 * <jc>// Area with alternative text and target</jc> 041 * Area <jv>area3</jv> = <jsm>area</jsm>().shape(<js>"rect"</js>).coords(<js>"200,0,300,100"</js>).href(<js>"https://example.com/page3"</js>) 042 * .alt(<js>"Click here for more info"</js>) 043 * .target(<js>"_blank"</js>); 044 * </p> 045 * 046 * <p> 047 * The following convenience methods are provided for constructing instances of this bean: 048 * <ul class='javatree'> 049 * <li class='jc'>{@link HtmlBuilder} 050 * <ul class='javatree'> 051 * <li class='jm'>{@link HtmlBuilder#area() area()} 052 * </ul> 053 * </ul> 054 * 055 * <h2 class='section'>See Also:</h2><ul> 056 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 057 * </ul> 058 */ 059@Marshalled(typeName = "area") 060public class Area extends HtmlElementVoid<Area> { 061 062 /** 063 * Creates an empty {@link Area} element. 064 */ 065 public Area() {} 066 067 /** 068 * Creates an {@link Area} element with the specified {@link Area#shape(String)}, {@link Area#coords(String)}, 069 * and {@link Area#href(Object)} attributes. 070 * 071 * @param shape The {@link Area#shape(String)} attribute. Can be <jk>null</jk> to unset the attribute. 072 * @param coords The {@link Area#coords(String)} attribute. Can be <jk>null</jk> to unset the attribute. 073 * @param href The {@link Area#href(Object)} attribute. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 074 */ 075 public Area(String shape, String coords, Object href) { 076 shape(shape).coords(coords).href(href); 077 } 078 079 /** 080 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-area-alt">alt</a> attribute. 081 * 082 * <p> 083 * Specifies alternative text for the area. This text is displayed when the image map cannot be loaded 084 * and is used by screen readers for accessibility. 085 * 086 * <p> 087 * The alt text should be descriptive and convey the same information as the clickable area. 088 * 089 * @param value Alternative text for the area. Can be <jk>null</jk> to unset the attribute. 090 * @return This object. 091 */ 092 public Area alt(String value) { 093 attr("alt", value); 094 return this; 095 } 096 097 /** 098 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-area-coords">coords</a> 099 * attribute. 100 * 101 * <p> 102 * Specifies the coordinates of the clickable area within the image map. The format depends on the shape: 103 * 104 * <p> 105 * Coordinate formats: 106 * <ul> 107 * <li><js>"rect"</js> - x1,y1,x2,y2 (top-left and bottom-right corners)</li> 108 * <li><js>"circle"</js> - x,y,radius (center point and radius)</li> 109 * <li><js>"poly"</js> - x1,y1,x2,y2,x3,y3,... (polygon vertices)</li> 110 * <li><js>"default"</js> - No coordinates needed</li> 111 * </ul> 112 * 113 * @param value The coordinates defining the clickable area. Can be <jk>null</jk> to unset the attribute. 114 * @return This object. 115 */ 116 public Area coords(String value) { 117 attr("coords", value); 118 return this; 119 } 120 121 /** 122 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-download">download</a> attribute. 123 * 124 * <p> 125 * Whether to download the resource instead of navigating to it, and its file name if so. 126 * 127 * @param value 128 * The new value for this attribute. 129 * Typically a {@link Boolean} or {@link String}. 130 * Can be <jk>null</jk> to unset the attribute. 131 * @return This object. 132 */ 133 public Area download(Object value) { 134 attr("download", value); 135 return this; 136 } 137 138 /** 139 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-href">href</a> attribute. 140 * 141 * <p> 142 * Address of the hyperlink. 143 * 144 * <p> 145 * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 146 * Strings must be valid URIs. 147 * 148 * <p> 149 * URIs defined by {@link UriResolver} can be used for values. 150 * 151 * @param value 152 * The new value for this attribute. 153 * Typically a {@link URL} or {@link String}. 154 * Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 155 * @return This object. 156 */ 157 public Area href(Object value) { 158 attrUri("href", value); 159 return this; 160 } 161 162 /** 163 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-hreflang">hreflang</a> attribute. 164 * 165 * <p> 166 * Specifies the language of the linked resource. Used for SEO and accessibility purposes. 167 * 168 * <p> 169 * Examples: 170 * <ul> 171 * <li><js>"en"</js> - English</li> 172 * <li><js>"es"</js> - Spanish</li> 173 * <li><js>"fr"</js> - French</li> 174 * <li><js>"de"</js> - German</li> 175 * <li><js>"zh"</js> - Chinese</li> 176 * <li><js>"ja"</js> - Japanese</li> 177 * </ul> 178 * 179 * @param value The language code of the linked resource. Can be <jk>null</jk> to unset the attribute. 180 * @return This object. 181 */ 182 public Area hreflang(String value) { 183 attr("hreflang", value); 184 return this; 185 } 186 187 /** 188 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-rel">rel</a> attribute. 189 * 190 * <p> 191 * Specifies the relationship between the current document and the linked resource. 192 * 193 * <p> 194 * Common values: 195 * <ul> 196 * <li><js>"alternate"</js> - Alternative version of the page</li> 197 * <li><js>"author"</js> - Link to the author of the page</li> 198 * <li><js>"bookmark"</js> - Permalink for bookmarking</li> 199 * <li><js>"external"</js> - External link</li> 200 * <li><js>"help"</js> - Link to help documentation</li> 201 * <li><js>"license"</js> - Link to license information</li> 202 * <li><js>"next"</js> - Next page in a sequence</li> 203 * <li><js>"nofollow"</js> - Don't follow this link for SEO</li> 204 * <li><js>"noreferrer"</js> - Don't send referrer information</li> 205 * <li><js>"prev"</js> - Previous page in a sequence</li> 206 * <li><js>"search"</js> - Link to search functionality</li> 207 * <li><js>"tag"</js> - Tag for the current page</li> 208 * </ul> 209 * 210 * @param value The relationship between the document and linked resource. Can be <jk>null</jk> to unset the attribute. 211 * @return This object. 212 */ 213 public Area rel(String value) { 214 attr("rel", value); 215 return this; 216 } 217 218 /** 219 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-area-shape">shape</a> attribute. 220 * 221 * <p> 222 * Specifies the shape of the clickable area in an image map. 223 * 224 * <p> 225 * Possible values: 226 * <ul> 227 * <li><js>"rect"</js> - Rectangular area (default)</li> 228 * <li><js>"circle"</js> - Circular area</li> 229 * <li><js>"poly"</js> - Polygonal area</li> 230 * <li><js>"default"</js> - Entire image area</li> 231 * </ul> 232 * 233 * @param value The shape of the clickable area. Can be <jk>null</jk> to unset the attribute. 234 * @return This object. 235 */ 236 public Area shape(String value) { 237 attr("shape", value); 238 return this; 239 } 240 241 /** 242 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-target">target</a> attribute. 243 * 244 * <p> 245 * Specifies where to open the linked resource when the area is clicked. 246 * 247 * <p> 248 * Common values: 249 * <ul> 250 * <li><js>"_blank"</js> - Open in a new window/tab</li> 251 * <li><js>"_self"</js> - Open in the same frame (default)</li> 252 * <li><js>"_parent"</js> - Open in the parent frame</li> 253 * <li><js>"_top"</js> - Open in the full body of the window</li> 254 * <li><js>"framename"</js> - Open in a named frame</li> 255 * </ul> 256 * 257 * @param value Where to open the linked resource. Can be <jk>null</jk> to unset the attribute. 258 * @return This object. 259 */ 260 public Area target(String value) { 261 attr("target", value); 262 return this; 263 } 264 265 /** 266 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-type">type</a> attribute. 267 * 268 * <p> 269 * Specifies the MIME type of the linked resource. Helps browsers determine how to handle the resource. 270 * 271 * <p> 272 * Common values: 273 * <ul> 274 * <li><js>"text/html"</js> - HTML document</li> 275 * <li><js>"text/css"</js> - CSS stylesheet</li> 276 * <li><js>"application/pdf"</js> - PDF document</li> 277 * <li><js>"image/png"</js> - PNG image</li> 278 * <li><js>"application/zip"</js> - ZIP archive</li> 279 * </ul> 280 * 281 * @param value The MIME type of the linked resource. Can be <jk>null</jk> to unset the attribute. 282 * @return This object. 283 */ 284 public Area type(String value) { 285 attr("type", value); 286 return this; 287 } 288}