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