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-img-element"><img></a> 025 * element. 026 * 027 * <p> 028 * The img element represents an image in the document. It is a void element that embeds an image 029 * into the page. The alt attribute is required for accessibility, providing alternative text 030 * for screen readers and when images cannot be displayed. 031 * 032 * <h2 class='section'>Examples:</h2> 033 * <p class='bcode w800'> 034 * <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*; 035 * 036 * <jc>// Simple image with alt text</jc> 037 * Img <jv>img1</jv> = <jsm>img</jsm>() 038 * .src(<js>"photo.jpg"</js>) 039 * .alt(<js>"A beautiful sunset over the mountains"</js>); 040 * 041 * <jc>// Image with dimensions and styling</jc> 042 * Img <jv>img2</jv> = <jsm>img</jsm>() 043 * .src(<js>"logo.png"</js>) 044 * .alt(<js>"Company Logo"</js>) 045 * .width(<js>"200"</js>) 046 * .height(<js>"100"</js>) 047 * .class_(<js>"logo"</js>); 048 * 049 * <jc>// Image with CORS and image map</jc> 050 * Img <jv>img3</jv> = <jsm>img</jsm>() 051 * .src(<js>"https://example.com/image.jpg"</js>) 052 * .alt(<js>"Interactive image"</js>) 053 * .crossorigin(<js>"anonymous"</js>) 054 * .usemap(<js>"#imagemap"</js>); 055 * 056 * <jc>// Responsive image with multiple sources</jc> 057 * Img <jv>img4</jv> = <jsm>img</jsm>() 058 * .src(<js>"image-800w.jpg"</js>) 059 * .alt(<js>"Responsive image"</js>) 060 * .sizes(<js>"(max-width: 600px) 100vw, 50vw"</js>) 061 * .srcset(<js>"image-400w.jpg 400w, image-800w.jpg 800w"</js>); 062 * </p> 063 * 064 * <p> 065 * The following convenience methods are provided for constructing instances of this bean: 066 * <ul class='javatree'> 067 * <li class='jc'>{@link HtmlBuilder} 068 * <ul class='javatree'> 069 * <li class='jm'>{@link HtmlBuilder#img() img()} 070 * </ul> 071 * </ul> 072 * 073 * <h2 class='section'>See Also:</h2><ul> 074 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 075 * </ul> 076 */ 077@Marshalled(typeName = "img") 078public class Img extends HtmlElementVoid<Img> { 079 080 /** 081 * Creates an empty {@link Img} element. 082 */ 083 public Img() {} 084 085 /** 086 * Creates an {@link Img} element with the specified {@link Img#src(Object)} attribute. 087 * 088 * @param src The {@link Img#src(Object)} attribute. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 089 */ 090 public Img(Object src) { 091 src(src); 092 } 093 094 /** 095 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-img-alt">alt</a> attribute. 096 * 097 * <p> 098 * Specifies alternative text for the image. This text is displayed when the image cannot be loaded 099 * and is used by screen readers for accessibility. 100 * 101 * <p> 102 * The alt text should be descriptive and convey the same information as the image. 103 * 104 * @param value Alternative text for the image. Can be <jk>null</jk> to unset the attribute. 105 * @return This object. 106 */ 107 public Img alt(String value) { 108 attr("alt", value); 109 return this; 110 } 111 112 /** 113 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-img-crossorigin">crossorigin</a> 114 * attribute. 115 * 116 * <p> 117 * Specifies how the element handles cross-origin requests for CORS (Cross-Origin Resource Sharing). 118 * 119 * <p> 120 * Possible values: 121 * <ul> 122 * <li><js>"anonymous"</js> - Cross-origin requests are made without credentials</li> 123 * <li><js>"use-credentials"</js> - Cross-origin requests include credentials</li> 124 * </ul> 125 * 126 * @param value How to handle cross-origin requests. Can be <jk>null</jk> to unset the attribute. 127 * @return This object. 128 */ 129 public Img crossorigin(String value) { 130 attr("crossorigin", value); 131 return this; 132 } 133 134 /** 135 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-dim-height">height</a> 136 * attribute. 137 * 138 * <p> 139 * Vertical dimension. 140 * 141 * @param value 142 * The new value for this attribute. 143 * Typically a {@link Number} or {@link String}. 144 * Can be <jk>null</jk> to unset the attribute. 145 * @return This object. 146 */ 147 public Img height(Object value) { 148 attr("height", value); 149 return this; 150 } 151 152 /** 153 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-img-ismap">ismap</a> attribute. 154 * 155 * <p> 156 * Whether the image is a server-side image map. 157 * 158 * <p> 159 * This attribute uses deminimized values: 160 * <ul> 161 * <li><jk>false</jk> - Attribute is not added</li> 162 * <li><jk>true</jk> - Attribute is added as <js>"ismap"</js></li> 163 * <li>Other values - Passed through as-is</li> 164 * </ul> 165 * 166 * @param value 167 * The new value for this attribute. 168 * Typically a {@link Boolean} or {@link String}. 169 * Can be <jk>null</jk> to unset the attribute. 170 * @return This object. 171 */ 172 public Img ismap(Object value) { 173 attr("ismap", deminimize(value, "ismap")); 174 return this; 175 } 176 177 /** 178 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-img-src">src</a> attribute. 179 * 180 * <p> 181 * Address of the resource. 182 * 183 * <p> 184 * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 185 * Strings must be valid URIs. 186 * 187 * <p> 188 * URIs defined by {@link UriResolver} can be used for values. 189 * 190 * @param value 191 * The new value for this attribute. 192 * Typically a {@link URL} or {@link String}. 193 * Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 194 * @return This object. 195 */ 196 public Img src(Object value) { 197 attrUri("src", value); 198 return this; 199 } 200 201 /** 202 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-hyperlink-usemap">usemap</a> 203 * attribute. 204 * 205 * <p> 206 * Specifies the name of an image map to use with this image. The value should correspond to 207 * the name attribute of a map element that defines clickable areas on the image. 208 * 209 * <p> 210 * The value should start with "#" followed by the name of the map element. 211 * 212 * @param value The name of the image map to use (e.g., "#mymap"). Can be <jk>null</jk> to unset the attribute. 213 * @return This object. 214 */ 215 public Img usemap(String value) { 216 attr("usemap", value); 217 return this; 218 } 219 220 /** 221 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-dim-width">width</a> attribute. 222 * 223 * <p> 224 * Horizontal dimension. 225 * 226 * @param value 227 * The new value for this attribute. 228 * Typically a {@link Number} or {@link String}. 229 * Can be <jk>null</jk> to unset the attribute. 230 * @return This object. 231 */ 232 public Img width(Object value) { 233 attr("width", value); 234 return this; 235 } 236}