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/text-level-semantics.html#the-a-element"><a></a> 025 * element. 026 * 027 * <p> 028 * The anchor element creates a hyperlink to other web pages, files, locations within the same page, 029 * email addresses, or any other URL. It is one of the most fundamental elements for web navigation. 030 * 031 * <h5 class='section'>Examples:</h5> 032 * <p class='bcode w800'> 033 * <jc>// Simple link to another page</jc> 034 * A <jv>a1</jv> = <jsm>a</jsm>().href(<js>"https://example.com"</js>).text(<js>"Visit Example"</js>); 035 * 036 * <jc>// Link with target to open in new window</jc> 037 * A <jv>a2</jv> = <jsm>a</jsm>().href(<js>"https://example.com"</js>).target(<js>"_blank"</js>).text(<js>"Open in New Window"</js>); 038 * 039 * <jc>// Email link</jc> 040 * A <jv>a3</jv> = <jsm>a</jsm>().href(<js>"mailto:user@example.com"</js>).text(<js>"Send Email"</js>); 041 * 042 * <jc>// Link with relationship and language</jc> 043 * A <jv>a4</jv> = <jsm>a</jsm>().href(<js>"https://example.com"</js>).rel(<js>"nofollow"</js>).hreflang(<js>"en"</js>).text(<js>"English Version"</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#a() a()} 052 * <li class='jm'>{@link HtmlBuilder#a(Object, Object...) a(Object, Object...)} 053 * </ul> 054 * </ul> 055 * </p> 056 * 057 * <h5 class='section'>See Also:</h5><ul> 058 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 059 * </ul> 060 */ 061@Marshalled(typeName = "a") 062public class A extends HtmlElementMixed<A> { 063 064 /** 065 * Creates an empty {@link A} element. 066 */ 067 public A() {} 068 069 /** 070 * Creates an {@link A} element with the specified {@link A#href(Object)} attribute and {@link A#children(Object[])} 071 * nodes. 072 * 073 * @param href The {@link A#href(Object)} attribute. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 074 * @param children The {@link A#children(Object[])} nodes. Must not be <jk>null</jk>. 075 */ 076 public A(Object href, Object[] children) { 077 href(href).children(children); 078 } 079 080 /** 081 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-download">download</a> attribute. 082 * 083 * <p> 084 * Whether to download the resource instead of navigating to it, and its file name if so. 085 * 086 * @param value 087 * The new value for this attribute. 088 * Typically a {@link Boolean} or {@link String}. 089 * Can be <jk>null</jk> to unset the attribute. 090 * @return This object. 091 */ 092 public A download(Object value) { 093 attr("download", value); 094 return this; 095 } 096 097 /** 098 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-href">href</a> attribute. 099 * 100 * <p> 101 * Address of the hyperlink. 102 * 103 * <p> 104 * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 105 * Strings must be valid URIs. 106 * 107 * <p> 108 * URIs defined by {@link UriResolver} can be used for values. 109 * 110 * @param value 111 * The new value for this attribute. 112 * Typically a {@link URL} or {@link String}. 113 * Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 114 * @return This object. 115 */ 116 public A href(Object value) { 117 attrUri("href", value); 118 return this; 119 } 120 121 /** 122 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-hreflang">hreflang</a> attribute. 123 * 124 * <p> 125 * Specifies the language of the linked resource. Used for SEO and accessibility purposes. 126 * 127 * <p> 128 * Examples: 129 * <ul> 130 * <li><js>"en"</js> - English</li> 131 * <li><js>"es"</js> - Spanish</li> 132 * <li><js>"fr"</js> - French</li> 133 * <li><js>"de"</js> - German</li> 134 * <li><js>"zh"</js> - Chinese</li> 135 * <li><js>"ja"</js> - Japanese</li> 136 * </ul> 137 * 138 * @param value The language code of the linked resource. Can be <jk>null</jk> to unset the attribute. 139 * @return This object. 140 */ 141 public A hreflang(String value) { 142 attr("hreflang", value); 143 return this; 144 } 145 146 /** 147 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-rel">rel</a> attribute. 148 * 149 * <p> 150 * Specifies the relationship between the current document and the linked resource. 151 * 152 * <p> 153 * Common values: 154 * <ul> 155 * <li><js>"alternate"</js> - Alternative version of the page</li> 156 * <li><js>"author"</js> - Link to the author of the page</li> 157 * <li><js>"bookmark"</js> - Permalink for bookmarking</li> 158 * <li><js>"external"</js> - External link</li> 159 * <li><js>"help"</js> - Link to help documentation</li> 160 * <li><js>"license"</js> - Link to license information</li> 161 * <li><js>"next"</js> - Next page in a sequence</li> 162 * <li><js>"nofollow"</js> - Don't follow this link for SEO</li> 163 * <li><js>"noreferrer"</js> - Don't send referrer information</li> 164 * <li><js>"prev"</js> - Previous page in a sequence</li> 165 * <li><js>"search"</js> - Link to search functionality</li> 166 * <li><js>"tag"</js> - Tag for the current page</li> 167 * </ul> 168 * 169 * @param value The relationship between the document and linked resource. Can be <jk>null</jk> to unset the attribute. 170 * @return This object. 171 */ 172 public A rel(String value) { 173 attr("rel", value); 174 return this; 175 } 176 177 /** 178 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-target">target</a> attribute. 179 * 180 * <p> 181 * Specifies where to open the linked resource when the link is clicked. 182 * 183 * <p> 184 * Common values: 185 * <ul> 186 * <li><js>"_blank"</js> - Open in a new window/tab</li> 187 * <li><js>"_self"</js> - Open in the same frame (default)</li> 188 * <li><js>"_parent"</js> - Open in the parent frame</li> 189 * <li><js>"_top"</js> - Open in the full body of the window</li> 190 * <li><js>"framename"</js> - Open in a named frame</li> 191 * </ul> 192 * 193 * @param value Where to open the linked resource. Can be <jk>null</jk> to unset the attribute. 194 * @return This object. 195 */ 196 public A target(String value) { 197 attr("target", value); 198 return this; 199 } 200 201 /** 202 * <a class="doclink" href="https://www.w3.org/TR/html5/links.html#attr-hyperlink-type">type</a> attribute. 203 * 204 * <p> 205 * Specifies the MIME type of the linked resource. Helps browsers determine how to handle the resource. 206 * 207 * <p> 208 * Common values: 209 * <ul> 210 * <li><js>"text/html"</js> - HTML document</li> 211 * <li><js>"text/css"</js> - CSS stylesheet</li> 212 * <li><js>"application/pdf"</js> - PDF document</li> 213 * <li><js>"image/png"</js> - PNG image</li> 214 * <li><js>"application/zip"</js> - ZIP archive</li> 215 * </ul> 216 * 217 * @param value The MIME type of the linked resource. Can be <jk>null</jk> to unset the attribute. 218 * @return This object. 219 */ 220 public A type(String value) { 221 attr("type", value); 222 return this; 223 } 224}