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 RestSvlVariables} 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: Float aside section contents. 098 * 099 * <p> 100 * Allows you to position the aside contents of the page around the main contents. 101 * 102 * <p> 103 * By default, the aside section is floated to the right. 104 * 105 * <h5 class='section'>Example:</h5> 106 * <p class='bcode w800'> 107 * <ja>@HtmlDocConfig</ja>( 108 * aside={ 109 * <js>"<ul>"</js>, 110 * <js>" <li>Item 1"</js>, 111 * <js>" <li>Item 2"</js>, 112 * <js>" <li>Item 3"</js>, 113 * <js>"</ul>"</js> 114 * }, 115 * asideFloat=<js>"TOP"</js> 116 * ) 117 * </p> 118 * 119 * <ul class='notes'> 120 * <li> 121 * Possible values: 122 * <ul> 123 * <li><js>"RIGHT"</js> 124 * <li><js>"LEFT"</js> 125 * <li><js>"TOP"</js> 126 * <li><js>"BOTTOM"</js> 127 * <li><js>"DEFAULT"</js> (defaults to <js>"RIGHT"</js>) 128 * </ul> 129 * <li> 130 * Supports {@doc RestSvlVariables} 131 * (e.g. <js>"$L{my.localized.variable}"</js>). 132 * <li> 133 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 134 * <li> 135 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 136 * parent class. 137 * </ul> 138 * 139 * <ul class='seealso'> 140 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_asideFloat} 141 * </ul> 142 */ 143 String asideFloat() default "DEFAULT"; 144 145 /** 146 * Configuration property: Footer section contents. 147 * 148 * <p> 149 * Allows you to specify the contents of the footer section on the HTML page. 150 * 151 * <h5 class='section'>Example:</h5> 152 * <p class='bcode w800'> 153 * <ja>@HtmlDocConfig</ja>( 154 * footer={ 155 * <js>"<b>This interface is great!</b>"</js> 156 * } 157 * ) 158 * </p> 159 * 160 * <ul class='notes'> 161 * <li> 162 * Format: HTML 163 * <li> 164 * Supports {@doc RestSvlVariables} 165 * (e.g. <js>"$L{my.localized.variable}"</js>). 166 * <li> 167 * A value of <js>"NONE"</js> can be used to force no value. 168 * <li> 169 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 170 * <li> 171 * Multiple values are combined with newlines into a single string. 172 * <li> 173 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 174 * <li> 175 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 176 * parent class. 177 * </ul> 178 * 179 * <ul class='seealso'> 180 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_footer} 181 * </ul> 182 */ 183 String[] footer() default {}; 184 185 /** 186 * Configuration property: Additional head section content. 187 * 188 * <p> 189 * Adds the specified HTML content to the head section of the page. 190 * 191 * <h5 class='section'>Example:</h5> 192 * <p class='bcode w800'> 193 * <ja>@HtmlDocConfig</ja>( 194 * head={ 195 * <js>"<link rel='icon' href='$U{servlet:/htdocs/mypageicon.ico}'>"</js> 196 * } 197 * ) 198 * </p> 199 * 200 * <ul class='notes'> 201 * <li> 202 * Format: HTML 203 * <li> 204 * Supports {@doc RestSvlVariables} 205 * (e.g. <js>"$L{my.localized.variable}"</js>). 206 * <li> 207 * A value of <js>"NONE"</js> can be used to force no value. 208 * <li> 209 * The head content from the parent can be included by adding the literal <js>"INHERIT"</js> as a value. 210 * <li> 211 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 212 * <li> 213 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 214 * parent class. 215 * </ul> 216 * 217 * <ul class='seealso'> 218 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_head} 219 * </ul> 220 */ 221 String[] head() default {}; 222 223 /** 224 * Configuration property: Header section contents. 225 * 226 * <p> 227 * Allows you to override the contents of the header section on the HTML page. 228 * The header section normally contains the title and description at the top of the page. 229 * 230 * <h5 class='section'>Example:</h5> 231 * <p class='bcode w800'> 232 * <ja>@HtmlDocConfig</ja>( 233 * header={ 234 * <js>"<h1>My own header</h1>"</js> 235 * } 236 * ) 237 * </p> 238 * 239 * <ul class='notes'> 240 * <li> 241 * Format: HTML 242 * <li> 243 * A value of <js>"NONE"</js> can be used to force no header. 244 * <li> 245 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 246 * <li> 247 * Supports {@doc RestSvlVariables} 248 * (e.g. <js>"$L{my.localized.variable}"</js>). 249 * <li> 250 * Multiple values are combined with newlines into a single string. 251 * <li> 252 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 253 * <li> 254 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 255 * parent class if not overridden. 256 * </ul> 257 * 258 * <ul class='seealso'> 259 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_header} 260 * </ul> 261 */ 262 String[] header() default {}; 263 264 /** 265 * Configuration property: Nav section contents. 266 * 267 * <p> 268 * Allows you to override the contents of the nav section on the HTML page. 269 * The nav section normally contains the page links at the top of the page. 270 * 271 * <h5 class='section'>Example:</h5> 272 * <p class='bcode w800'> 273 * <ja>@HtmlDocConfig</ja>( 274 * nav={ 275 * <js>"<p class='special-navigation'>This is my special navigation content</p>"</js> 276 * } 277 * ) 278 * </p> 279 * 280 * <ul class='notes'> 281 * <li> 282 * Format: HTML 283 * <li> 284 * When {@link #navlinks()} is also specified, this content is placed AFTER the navigation links. 285 * <li> 286 * Supports {@doc RestSvlVariables} 287 * (e.g. <js>"$L{my.localized.variable}"</js>). 288 * <li> 289 * A value of <js>"NONE"</js> can be used to force no value. 290 * <li> 291 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 292 * <li> 293 * Multiple values are combined with newlines into a single string. 294 * <li> 295 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 296 * <li> 297 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 298 * parent class. 299 * </ul> 300 * 301 * <ul class='seealso'> 302 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_nav} 303 * </ul> 304 */ 305 String[] nav() default {}; 306 307 /** 308 * Configuration property: Page navigation links. 309 * 310 * <p> 311 * Adds a list of hyperlinks immediately under the title and description but above the content of the page. 312 * 313 * <p> 314 * This can be used to provide convenient hyperlinks when viewing the REST interface from a browser. 315 * 316 * <p> 317 * The value is an array of strings with two possible values: 318 * <ul> 319 * <li>A key-value pair representing a hyperlink label and href: 320 * <br><js>"google: http://google.com"</js> 321 * <li>Arbitrary HTML. 322 * </ul> 323 * 324 * <p> 325 * Relative URLs are considered relative to the servlet path. 326 * For example, if the servlet path is <js>"http://localhost/myContext/myServlet"</js>, and the 327 * URL is <js>"foo"</js>, the link becomes <js>"http://localhost/myContext/myServlet/foo"</js>. 328 * Absolute (<js>"/myOtherContext/foo"</js>) and fully-qualified (<js>"http://localhost2/foo"</js>) URLs 329 * can also be used in addition to various other protocols specified by {@link UriResolver} such as 330 * <js>"servlet:/..."</js>. 331 * 332 * <h5 class='section'>Example:</h5> 333 * <p class='bcode w800'> 334 * <ja>@HtmlDocConfig</ja>( 335 * navlinks={ 336 * <js>"options: servlet:/?method=OPTIONS"</js>, 337 * <js>"stats: servlet:/stats"</js>, 338 * <js>"doc: doc"</js> 339 * } 340 * ) 341 * <jk>public class</jk> AddressBookResource <jk>extends</jk> BasicRestServletJena { 342 * </p> 343 * 344 * <ul class='notes'> 345 * <li> 346 * Supports {@doc RestSvlVariables} 347 * (e.g. <js>"$L{my.localized.variable}"</js>). 348 * <li> 349 * A value of <js>"NONE"</js> can be used to force no value. 350 * <li> 351 * The parent links can be included by adding the literal <js>"INHERIT"</js> as a value. 352 * <br>Use the syntax <js>"key[index]: value"</js> or <js>"[index]: value"</js> to specify an index location 353 * to place a link inside the list of parent links. 354 * <li> 355 * Supports {@doc MarshallingUris} (e.g. <js>"servlet:/..."</js>, <js>"request:/..."</js>). 356 * <li> 357 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 358 * <li> 359 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 360 * parent class. 361 * </ul> 362 * 363 * <ul class='seealso'> 364 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_navlinks} 365 * </ul> 366 */ 367 String[] navlinks() default {}; 368 369 /** 370 * Configuration property: No-results message. 371 * 372 * <p> 373 * Allows you to specify the string message used when trying to serialize an empty array or empty list. 374 * 375 * <h5 class='section'>Example:</h5> 376 * <p class='bcode w800'> 377 * <ja>@HtmlDocConfig</ja>( 378 * noResultsMessage=<js>"<b>This interface is great!</b>"</js> 379 * ) 380 * </p> 381 * 382 * <ul class='notes'> 383 * <li> 384 * Format: HTML 385 * <li> 386 * A value of <js>"NONE"</js> can be used to represent no value to differentiate it from an empty string. 387 * <li> 388 * Supports {@doc RestSvlVariables} 389 * (e.g. <js>"$L{my.localized.variable}"</js>). 390 * </ul> 391 * 392 * <ul class='seealso'> 393 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_noResultsMessage} 394 * </ul> 395 */ 396 String noResultsMessage() default ""; 397 398 /** 399 * Configuration property: Prevent word wrap on page. 400 * 401 * <p> 402 * Adds <js>"* {white-space:nowrap}"</js> to the CSS instructions on the page to prevent word wrapping. 403 * 404 * <ul class='notes'> 405 * <li> 406 * Possible values: 407 * <ul> 408 * <li><js>"true"</js> 409 * <li><js>"false"</js> (default) 410 * </ul> 411 * <li> 412 * Supports {@doc RestSvlVariables} 413 * (e.g. <js>"$L{my.localized.variable}"</js>). 414 * </ul> 415 * 416 * <ul class='seealso'> 417 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_nowrap} 418 * </ul> 419 */ 420 String nowrap() default ""; 421 422 /** 423 * Configuration property: Javascript code. 424 * 425 * <p> 426 * Adds the specified Javascript code to the HTML page. 427 * 428 * <h5 class='section'>Example:</h5> 429 * <p class='bpcode w800'> 430 * <ja>@HtmlDocConfig</ja>( 431 * script={ 432 * <js>"alert('hello!');"</js> 433 * } 434 * ) 435 * </p> 436 * 437 * <ul class='notes'> 438 * <li> 439 * Format: Javascript 440 * <li> 441 * Supports {@doc RestSvlVariables} 442 * (e.g. <js>"$L{my.localized.variable}"</js>). 443 * <li> 444 * A value of <js>"NONE"</js> can be used to force no value. 445 * <li> 446 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 447 * <li> 448 * Multiple values are combined with newlines into a single string. 449 * <li> 450 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 451 * <li> 452 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 453 * parent class. 454 * </ul> 455 * 456 * <ul class='seealso'> 457 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_script} 458 * </ul> 459 */ 460 String[] script() default {}; 461 462 /** 463 * Configuration property: CSS style code. 464 * 465 * <p> 466 * Adds the specified CSS instructions to the HTML page. 467 * 468 * <h5 class='section'>Example:</h5> 469 * <p class='bpcode w800'> 470 * <ja>@HtmlDocConfig</ja>( 471 * style={ 472 * <js>"h3 { color: red; }"</js>, 473 * <js>"h5 { font-weight: bold; }"</js> 474 * } 475 * ) 476 * </p> 477 * 478 * <ul class='notes'> 479 * <li> 480 * Format: CSS 481 * <li> 482 * Supports {@doc RestSvlVariables} 483 * (e.g. <js>"$L{my.localized.variable}"</js>). 484 * <li> 485 * A value of <js>"NONE"</js> can be used to force no value. 486 * <li> 487 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 488 * <li> 489 * Multiple values are combined with newlines into a single string. 490 * <li> 491 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 492 * <li> 493 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 494 * parent class. 495 * </ul> 496 * 497 * <ul class='seealso'> 498 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_style} 499 * </ul> 500 */ 501 String[] style() default {}; 502 503 /** 504 * Configuration property: Stylesheet import URLs. 505 * 506 * <p> 507 * Adds a link to the specified stylesheet URL. 508 * 509 * <p> 510 * Note that this stylesheet is controlled by the <code><ja>@Rest</ja>.stylesheet()</code> annotation. 511 * 512 * <ul class='notes'> 513 * <li> 514 * Format: URL 515 * <li> 516 * Supports {@doc RestSvlVariables} 517 * (e.g. <js>"$L{my.localized.variable}"</js>). 518 * <li> 519 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 520 * <li> 521 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 522 * parent class. 523 * </ul> 524 * 525 * <ul class='seealso'> 526 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_stylesheet} 527 * </ul> 528 */ 529 String[] stylesheet() default {}; 530 531 /** 532 * Configuration property: HTML document template. 533 * 534 * <p> 535 * Specifies the template to use for serializing the page. 536 * 537 * <p> 538 * By default, the {@link BasicHtmlDocTemplate} class is used to construct the contents of the HTML page, but 539 * can be overridden with your own custom implementation class. 540 * 541 * <h5 class='section'>Example:</h5> 542 * <p class='bcode w800'> 543 * <ja>@HtmlDocConfig</ja>( 544 * template=MySpecialDocTemplate.<jk>class</jk> 545 * ) 546 * </p> 547 * 548 * <ul class='notes'> 549 * <li> 550 * On methods, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the servlet/resource class. 551 * <li> 552 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDocConfig</ja> annotation on the 553 * parent class. 554 * </ul> 555 * 556 * <ul class='seealso'> 557 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_template} 558 * </ul> 559 */ 560 Class<? extends HtmlDocTemplate> template() default HtmlDocTemplate.Null.class; 561 562 /** 563 * Configuration property: HTML Widgets. 564 * 565 * <p> 566 * Defines widgets that can be used in conjunction with string variables of the form <js>"$W{name}"</js>to quickly 567 * generate arbitrary replacement text. 568 * 569 * <p> 570 * Widgets resolve the following variables: 571 * 572 * <ul class='spaced-list'> 573 * <li> 574 * <js>"$W{name}"</js> - Contents returned by {@link HtmlWidget#getHtml(VarResolverSession)}. 575 * </ul> 576 * 577 * <p> 578 * The following examples shows how to associate a widget with a REST method and then have it rendered in the links 579 * and aside section of the page: 580 * 581 * <p class='bcode w800'> 582 * <ja>@HtmlDocConfig</ja>( 583 * widgets={ 584 * MyWidget.<jk>class</jk> 585 * } 586 * navlinks={ 587 * <js>"$W{MyWidget}"</js> 588 * }, 589 * aside={ 590 * <js>"Check out this widget: $W{MyWidget}"</js> 591 * } 592 * ) 593 * </p> 594 * 595 * <ul class='notes'> 596 * <li> 597 * Widgets are inherited from parent to child, but can be overridden by reusing the widget name. 598 * <li> 599 * Values are appended to the existing list. 600 * </ul> 601 * 602 * <ul class='seealso'> 603 * <li class='link'>{@doc RestHtmlWidgets} 604 * </ul> 605 */ 606 Class<? extends HtmlWidget>[] widgets() default {}; 607}