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