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