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