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