001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.html.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020import org.apache.juneau.*; 021import org.apache.juneau.annotation.*; 022import org.apache.juneau.html.*; 023import org.apache.juneau.svl.*; 024 025/** 026 * Annotation for specifying config properties defined in {@link HtmlSerializer}, {@link HtmlParser}, and {@link HtmlDocSerializer}. 027 * 028 * <p> 029 * Used primarily for specifying bean configuration properties on REST classes and methods. 030 */ 031@Documented 032@Target({TYPE,METHOD}) 033@Retention(RUNTIME) 034@Inherited 035@PropertyStoreApply(HtmlDocConfigApply.class) 036public @interface HtmlDocConfig { 037 038 /** 039 * Optional rank for this config. 040 * 041 * <p> 042 * Can be used to override default ordering and application of config annotations. 043 */ 044 int rank() default 0; 045 046 //------------------------------------------------------------------------------------------------------------------- 047 // HtmlDocSerializer 048 //------------------------------------------------------------------------------------------------------------------- 049 050 /** 051 * Configuration property: Aside section contents. 052 * 053 * <p> 054 * Allows you to specify the contents of the aside section on the HTML page. 055 * The aside section floats on the right of the page for providing content supporting the serialized content of 056 * the page. 057 * 058 * <h5 class='section'>Example:</h5> 059 * <p class='bcode w800'> 060 * <ja>@HtmlDocConfig</ja>( 061 * aside={ 062 * <js>"<ul>"</js>, 063 * <js>" <li>Item 1"</js>, 064 * <js>" <li>Item 2"</js>, 065 * <js>" <li>Item 3"</js>, 066 * <js>"</ul>"</js> 067 * } 068 * ) 069 * </p> 070 * 071 * <ul class='notes'> 072 * <li> 073 * Format: HTML 074 * <li> 075 * Supports {@doc DefaultRestSvlVariables} 076 * (e.g. <js>"$L{my.localized.variable}"</js>). 077 * <li> 078 * A value of <js>"NONE"</js> can be used to force no value. 079 * <li> 080 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 081 * <li> 082 * Multiple values are combined with newlines into a single string. 083 * <li> 084 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 085 * <li> 086 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 087 * parent class. 088 * </ul> 089 * 090 * <ul class='seealso'> 091 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_aside} 092 * </ul> 093 */ 094 String[] aside() default {}; 095 096 /** 097 * Configuration property: Footer section contents. 098 * 099 * <p> 100 * Allows you to specify the contents of the footer section on the HTML page. 101 * 102 * <h5 class='section'>Example:</h5> 103 * <p class='bcode w800'> 104 * <ja>@HtmlDocConfig</ja>( 105 * footer={ 106 * <js>"<b>This interface is great!</b>"</js> 107 * } 108 * ) 109 * </p> 110 * 111 * <ul class='notes'> 112 * <li> 113 * Format: HTML 114 * <li> 115 * Supports {@doc DefaultRestSvlVariables} 116 * (e.g. <js>"$L{my.localized.variable}"</js>). 117 * <li> 118 * A value of <js>"NONE"</js> can be used to force no value. 119 * <li> 120 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 121 * <li> 122 * Multiple values are combined with newlines into a single string. 123 * <li> 124 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 125 * <li> 126 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 127 * parent class. 128 * </ul> 129 * 130 * <ul class='seealso'> 131 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_footer} 132 * </ul> 133 */ 134 String[] footer() default {}; 135 136 /** 137 * Configuration property: Additional head section content. 138 * 139 * <p> 140 * Adds the specified HTML content to the head section of the page. 141 * 142 * <h5 class='section'>Example:</h5> 143 * <p class='bcode w800'> 144 * <ja>@HtmlDocConfig</ja>( 145 * head={ 146 * <js>"<link rel='icon' href='$U{servlet:/htdocs/mypageicon.ico}'>"</js> 147 * } 148 * ) 149 * </p> 150 * 151 * <ul class='notes'> 152 * <li> 153 * Format: HTML 154 * <li> 155 * Supports {@doc DefaultRestSvlVariables} 156 * (e.g. <js>"$L{my.localized.variable}"</js>). 157 * <li> 158 * A value of <js>"NONE"</js> can be used to force no value. 159 * <li> 160 * The head content from the parent can be included by adding the literal <js>"INHERIT"</js> as a value. 161 * <li> 162 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 163 * <li> 164 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 165 * parent class. 166 * </ul> 167 * 168 * <ul class='seealso'> 169 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_head} 170 * </ul> 171 */ 172 String[] head() default {}; 173 174 /** 175 * Configuration property: Header section contents. 176 * 177 * <p> 178 * Allows you to override the contents of the header section on the HTML page. 179 * The header section normally contains the title and description at the top of the page. 180 * 181 * <h5 class='section'>Example:</h5> 182 * <p class='bcode w800'> 183 * <ja>@HtmlDocConfig</ja>( 184 * header={ 185 * <js>"<h1>My own header</h1>"</js> 186 * } 187 * ) 188 * </p> 189 * 190 * <ul class='notes'> 191 * <li> 192 * Format: HTML 193 * <li> 194 * A value of <js>"NONE"</js> can be used to force no header. 195 * <li> 196 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 197 * <li> 198 * Supports {@doc DefaultRestSvlVariables} 199 * (e.g. <js>"$L{my.localized.variable}"</js>). 200 * <li> 201 * Multiple values are combined with newlines into a single string. 202 * <li> 203 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 204 * <li> 205 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 206 * parent class if not overridden. 207 * </ul> 208 * 209 * <ul class='seealso'> 210 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_header} 211 * </ul> 212 */ 213 String[] header() default {}; 214 215 /** 216 * Configuration property: Nav section contents. 217 * 218 * <p> 219 * Allows you to override the contents of the nav section on the HTML page. 220 * The nav section normally contains the page links at the top of the page. 221 * 222 * <h5 class='section'>Example:</h5> 223 * <p class='bcode w800'> 224 * <ja>@HtmlDocConfig</ja>( 225 * nav={ 226 * <js>"<p class='special-navigation'>This is my special navigation content</p>"</js> 227 * } 228 * ) 229 * </p> 230 * 231 * <ul class='notes'> 232 * <li> 233 * Format: HTML 234 * <li> 235 * When {@link #navlinks()} is also specified, this content is placed AFTER the navigation links. 236 * <li> 237 * Supports {@doc DefaultRestSvlVariables} 238 * (e.g. <js>"$L{my.localized.variable}"</js>). 239 * <li> 240 * A value of <js>"NONE"</js> can be used to force no value. 241 * <li> 242 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 243 * <li> 244 * Multiple values are combined with newlines into a single string. 245 * <li> 246 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 247 * <li> 248 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 249 * parent class. 250 * </ul> 251 * 252 * <ul class='seealso'> 253 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_nav} 254 * </ul> 255 */ 256 String[] nav() default {}; 257 258 /** 259 * Configuration property: Page navigation links. 260 * 261 * <p> 262 * Adds a list of hyperlinks immediately under the title and description but above the content of the page. 263 * 264 * <p> 265 * This can be used to provide convenient hyperlinks when viewing the REST interface from a browser. 266 * 267 * <p> 268 * The value is an array of strings with two possible values: 269 * <ul> 270 * <li>A key-value pair representing a hyperlink label and href: 271 * <br><js>"google: http://google.com"</js> 272 * <li>Arbitrary HTML. 273 * </ul> 274 * 275 * <p> 276 * Relative URLs are considered relative to the servlet path. 277 * For example, if the servlet path is <js>"http://localhost/myContext/myServlet"</js>, and the 278 * URL is <js>"foo"</js>, the link becomes <js>"http://localhost/myContext/myServlet/foo"</js>. 279 * Absolute (<js>"/myOtherContext/foo"</js>) and fully-qualified (<js>"http://localhost2/foo"</js>) URLs 280 * can also be used in addition to various other protocols specified by {@link UriResolver} such as 281 * <js>"servlet:/..."</js>. 282 * 283 * <h5 class='section'>Example:</h5> 284 * <p class='bcode w800'> 285 * <ja>@HtmlDocConfig</ja>( 286 * navlinks={ 287 * <js>"options: servlet:/?method=OPTIONS"</js>, 288 * <js>"stats: servlet:/stats"</js>, 289 * <js>"doc: doc"</js> 290 * } 291 * ) 292 * <jk>public class</jk> AddressBookResource <jk>extends</jk> BasicRestServletJena { 293 * </p> 294 * 295 * <ul class='notes'> 296 * <li> 297 * Supports {@doc DefaultRestSvlVariables} 298 * (e.g. <js>"$L{my.localized.variable}"</js>). 299 * <li> 300 * A value of <js>"NONE"</js> can be used to force no value. 301 * <li> 302 * The parent links can be included by adding the literal <js>"INHERIT"</js> as a value. 303 * <br>Use the syntax <js>"key[index]: value"</js> or <js>"[index]: value"</js> to specify an index location 304 * to place a link inside the list of parent links. 305 * <li> 306 * Supports {@doc juneau-marshall.URIs} (e.g. <js>"servlet:/..."</js>, <js>"request:/..."</js>). 307 * <li> 308 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 309 * <li> 310 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 311 * parent class. 312 * </ul> 313 * 314 * <ul class='seealso'> 315 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_navlinks} 316 * </ul> 317 */ 318 String[] navlinks() default {}; 319 320 /** 321 * Configuration property: No-results message. 322 * 323 * <p> 324 * Allows you to specify the string message used when trying to serialize an empty array or empty list. 325 * 326 * <h5 class='section'>Example:</h5> 327 * <p class='bcode w800'> 328 * <ja>@HtmlDocConfig</ja>( 329 * noResultsMessage=<js>"<b>This interface is great!</b>"</js> 330 * ) 331 * </p> 332 * 333 * <ul class='notes'> 334 * <li> 335 * Format: HTML 336 * <li> 337 * A value of <js>"NONE"</js> can be used to represent no value to differentiate it from an empty string. 338 * <li> 339 * Supports {@doc DefaultRestSvlVariables} 340 * (e.g. <js>"$L{my.localized.variable}"</js>). 341 * </ul> 342 * 343 * <ul class='seealso'> 344 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_noResultsMessage} 345 * </ul> 346 */ 347 String noResultsMessage() default ""; 348 349 /** 350 * Configuration property: Prevent word wrap on page. 351 * 352 * <p> 353 * Adds <js>"* {white-space:nowrap}"</js> to the CSS instructions on the page to prevent word wrapping. 354 * 355 * <ul class='notes'> 356 * <li> 357 * Possible values: 358 * <ul> 359 * <li><js>"true"</js> 360 * <li><js>"false"</js> (default) 361 * </ul> 362 * <li> 363 * Supports {@doc DefaultRestSvlVariables} 364 * (e.g. <js>"$L{my.localized.variable}"</js>). 365 * </ul> 366 * 367 * <ul class='seealso'> 368 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_nowrap} 369 * </ul> 370 */ 371 String nowrap() default ""; 372 373 /** 374 * Configuration property: Javascript code. 375 * 376 * <p> 377 * Adds the specified Javascript code to the HTML page. 378 * 379 * <h5 class='section'>Example:</h5> 380 * <p class='bpcode w800'> 381 * <ja>@HtmlDocConfig</ja>( 382 * script={ 383 * <js>"alert('hello!');"</js> 384 * } 385 * ) 386 * </p> 387 * 388 * <ul class='notes'> 389 * <li> 390 * Format: Javascript 391 * <li> 392 * Supports {@doc DefaultRestSvlVariables} 393 * (e.g. <js>"$L{my.localized.variable}"</js>). 394 * <li> 395 * A value of <js>"NONE"</js> can be used to force no value. 396 * <li> 397 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 398 * <li> 399 * Multiple values are combined with newlines into a single string. 400 * <li> 401 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 402 * <li> 403 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 404 * parent class. 405 * </ul> 406 * 407 * <ul class='seealso'> 408 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_script} 409 * </ul> 410 */ 411 String[] script() default {}; 412 413 /** 414 * Configuration property: CSS style code. 415 * 416 * <p> 417 * Adds the specified CSS instructions to the HTML page. 418 * 419 * <h5 class='section'>Example:</h5> 420 * <p class='bpcode w800'> 421 * <ja>@HtmlDocConfig</ja>( 422 * style={ 423 * <js>"h3 { color: red; }"</js>, 424 * <js>"h5 { font-weight: bold; }"</js> 425 * } 426 * ) 427 * </p> 428 * 429 * <ul class='notes'> 430 * <li> 431 * Format: CSS 432 * <li> 433 * Supports {@doc DefaultRestSvlVariables} 434 * (e.g. <js>"$L{my.localized.variable}"</js>). 435 * <li> 436 * A value of <js>"NONE"</js> can be used to force no value. 437 * <li> 438 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 439 * <li> 440 * Multiple values are combined with newlines into a single string. 441 * <li> 442 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 443 * <li> 444 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 445 * parent class. 446 * </ul> 447 * 448 * <ul class='seealso'> 449 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_style} 450 * </ul> 451 */ 452 String[] style() default {}; 453 454 /** 455 * Configuration property: Stylesheet import URLs. 456 * 457 * <p> 458 * Adds a link to the specified stylesheet URL. 459 * 460 * <p> 461 * Note that this stylesheet is controlled by the <code><ja>@Rest</ja>.stylesheet()</code> annotation. 462 * 463 * <ul class='notes'> 464 * <li> 465 * Format: URL 466 * <li> 467 * Supports {@doc DefaultRestSvlVariables} 468 * (e.g. <js>"$L{my.localized.variable}"</js>). 469 * <li> 470 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 471 * <li> 472 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 473 * parent class. 474 * </ul> 475 * 476 * <ul class='seealso'> 477 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_stylesheet} 478 * </ul> 479 */ 480 String[] stylesheet() default {}; 481 482 /** 483 * Configuration property: HTML document template. 484 * 485 * <p> 486 * Specifies the template to use for serializing the page. 487 * 488 * <p> 489 * By default, the {@link BasicHtmlDocTemplate} class is used to construct the contents of the HTML page, but 490 * can be overridden with your own custom implementation class. 491 * 492 * <h5 class='section'>Example:</h5> 493 * <p class='bcode w800'> 494 * <ja>@HtmlDocConfig</ja>( 495 * template=MySpecialDocTemplate.<jk>class</jk> 496 * ) 497 * </p> 498 * 499 * <ul class='notes'> 500 * <li> 501 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 502 * <li> 503 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 504 * parent class. 505 * </ul> 506 * 507 * <ul class='seealso'> 508 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_template} 509 * </ul> 510 */ 511 Class<? extends HtmlDocTemplate> template() default HtmlDocTemplate.Null.class; 512 513 /** 514 * Configuration property: HTML Widgets. 515 * 516 * <p> 517 * Defines widgets that can be used in conjunction with string variables of the form <js>"$W{name}"</js>to quickly 518 * generate arbitrary replacement text. 519 * 520 * <p> 521 * Widgets resolve the following variables: 522 * 523 * <ul class='spaced-list'> 524 * <li> 525 * <js>"$W{name}"</js> - Contents returned by {@link HtmlWidget#getHtml(VarResolverSession)}. 526 * </ul> 527 * 528 * <p> 529 * The following examples shows how to associate a widget with a REST method and then have it rendered in the links 530 * and aside section of the page: 531 * 532 * <p class='bcode w800'> 533 * <ja>@HtmlDocConfig</ja>( 534 * widgets={ 535 * MyWidget.<jk>class</jk> 536 * } 537 * navlinks={ 538 * <js>"$W{MyWidget}"</js> 539 * }, 540 * aside={ 541 * <js>"Check out this widget: $W{MyWidget}"</js> 542 * } 543 * ) 544 * </p> 545 * 546 * <ul class='notes'> 547 * <li> 548 * Widgets are inherited from parent to child, but can be overridden by reusing the widget name. 549 * <li> 550 * Values are appended to the existing list. 551 * </ul> 552 * 553 * <ul class='seealso'> 554 * <li class='link'>{@doc juneau-rest-server.HtmlDocAnnotation.Widgets} 555 * </ul> 556 */ 557 Class<? extends HtmlWidget>[] widgets() default {}; 558}