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.rest.annotation; 014 015import org.apache.juneau.html.*; 016import org.apache.juneau.rest.*; 017import org.apache.juneau.rest.widget.*; 018 019/** 020 * Contains all the configurable annotations for the {@link HtmlDocSerializer}. 021 * 022 * <p> 023 * Used with {@link RestResource#htmldoc() @RestResource(htmldoc)} and {@link RestMethod#htmldoc() @RestMethod(htmldoc)} 024 * to customize the HTML view of serialized POJOs. 025 * 026 * <p> 027 * All annotations specified here have no effect on any serializers other than {@link HtmlDocSerializer} and is 028 * provided as a shorthand method of for specifying configuration properties. 029 * 030 * <p> 031 * For example, the following two methods for defining the HTML nav links are considered equivalent: 032 * <p class='bcode w800'> 033 * <jc>// Defined via properties.</jc> 034 * <ja>@RestResource</ja>( 035 * properties={ 036 * <ja>@Property</ja>(name=HtmlDocSerializer.<jsf>HTMLDOC_navlinks</jsf>, value=<js>"{options:'?method=OPTIONS',doc:'doc'}"</js>) 037 * } 038 * ) 039 * 040 * <jc>// Defined via annotation.</jc> 041 * <ja>@RestResource</ja>( 042 * htmldoc=<ja>@HtmlDoc</ja>( 043 * navlinks={ 044 * <js>"options: ?method=OPTIONS"</js>, 045 * <js>"doc: doc"</js> 046 * } 047 * ) 048 * ) 049 * </p> 050 * 051 * <p> 052 * The purpose of these annotation is to populate the HTML document view which by default consists of the following 053 * structure: 054 * <p class='bcode w800'> 055 * <xt><html> 056 * <head> 057 * <style <xa>type</xa>=<xs>'text/css'</xs>> 058 * <xv>CSS styles and links to stylesheets</xv> 059 * </style> 060 * </head> 061 * <body> 062 * <header> 063 * <xv>Page header</xv> 064 * </header> 065 * <nav> 066 * <xv>Navigation links</xv> 067 * </nav> 068 * <aside> 069 * <xv>Side-bar text</xv> 070 * </aside> 071 * <article> 072 * <xv>Contents of serialized object</xv> 073 * </article> 074 * <footer> 075 * <xv>Footer message</xv> 076 * </footer> 077 * </body> 078 * </html></xt> 079 * </p> 080 * 081 * <h5 class='section'>See Also:</h5> 082 * <ul> 083 * <li class='link'>{@doc juneau-rest-server.HtmlDocAnnotation} 084 * </ul> 085 */ 086public @interface HtmlDoc { 087 088 /** 089 * Sets the HTML aside section contents. 090 * 091 * <p> 092 * The aside section typically floats on the right side of the page. 093 * 094 * <h5 class='section'>Example:</h5> 095 * <p class='bcode w800'> 096 * <ja>@RestResource</ja>( 097 * htmldoc=<ja>@HtmlDoc</ja>( 098 * aside={ 099 * <js>"<p>Custom aside content</p>"</js> 100 * } 101 * ) 102 * ) 103 * </p> 104 * 105 * <h5 class='section'>Notes:</h5> 106 * <ul class='spaced-list'> 107 * <li> 108 * The format of this value is HTML. 109 * <li> 110 * Supports {@doc DefaultRestSvlVariables} 111 * (e.g. <js>"$L{my.localized.variable}"</js>). 112 * <li> 113 * A value of <js>"NONE"</js> can be used to force no value. 114 * <li> 115 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 116 * <li> 117 * Multiple values are combined with newlines into a single string. 118 * <li> 119 * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class. 120 * <li> 121 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 122 * parent class. 123 * </ul> 124 * 125 * <h5 class='section'>See Also:</h5> 126 * <ul> 127 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_aside} 128 * <li class='jm'>{@link HtmlDocBuilder#aside(Object...)} 129 * </ul> 130 */ 131 String[] aside() default {}; 132 133 /** 134 * Sets the HTML footer section contents. 135 * 136 * <p> 137 * The footer section typically floats on the bottom of the page. 138 * 139 * <h5 class='section'>Example:</h5> 140 * <p class='bcode w800'> 141 * <ja>@RestResource</ja>( 142 * htmldoc=<ja>@HtmlDoc</ja>( 143 * footer={ 144 * <js>"<p>Custom footer content</p>"</js> 145 * } 146 * ) 147 * ) 148 * </p> 149 * 150 * <h5 class='section'>Notes:</h5> 151 * <ul class='spaced-list'> 152 * <li> 153 * The format of this value is 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 parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 161 * <li> 162 * Multiple values are combined with newlines into a single string. 163 * <li> 164 * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class. 165 * <li> 166 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 167 * parent class. 168 * </ul> 169 * 170 * <h5 class='section'>See Also:</h5> 171 * <ul> 172 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_footer} 173 * <li class='jm'>{@link HtmlDocBuilder#footer(Object...)} 174 * </ul> 175 */ 176 String[] footer() default {}; 177 178 /** 179 * Adds arbitrary content to the HTML <xt><head></xt> element on the page. 180 * 181 * <h5 class='section'>Example:</h5> 182 * <p class='bcode w800'> 183 * <ja>@RestResource</ja>( 184 * htmldoc=<ja>@HtmlDoc</ja>( 185 * head={ 186 * <jc>// Add a shortcut link in the browser tab</jc> 187 * <js>"<link rel='icon' href='$U{servlet:/htdocs/mypageicon.ico}'>"</js>, 188 * 189 * <jc>// Reload the page every 5 seconds </jc> 190 * <js>"<meta http-equiv='refresh' content='5'>"</js> 191 * } 192 * ) 193 * ) 194 * </p> 195 * 196 * <h5 class='section'>Notes:</h5> 197 * <ul class='spaced-list'> 198 * <li> 199 * The format of this value is HTML. 200 * <li> 201 * Supports {@doc DefaultRestSvlVariables} 202 * (e.g. <js>"$L{my.localized.variable}"</js>). 203 * <li> 204 * A value of <js>"NONE"</js> can be used to force no value. 205 * <li> 206 * The head content from the parent can be included by adding the literal <js>"INHERIT"</js> as a value. 207 * <li> 208 * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class. 209 * <li> 210 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 211 * parent class. 212 * </ul> 213 * 214 * <h5 class='section'>See Also:</h5> 215 * <ul> 216 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_head} 217 * <li class='jm'>{@link HtmlDocBuilder#head(Object...)} 218 * </ul> 219 */ 220 String[] head() default {}; 221 222 /** 223 * Sets the HTML header section contents. 224 * 225 * <p> 226 * The page header normally contains the title and description, but this value can be used to override the contents 227 * to be whatever you want. 228 * 229 * <h5 class='section'>Example:</h5> 230 * <p class='bcode w800'> 231 * <ja>@RestResource</ja>( 232 * htmldoc=<ja>@HtmlDoc</ja>( 233 * header={ 234 * <js>"<p>This is my REST interface</p>"</js> 235 * } 236 * ) 237 * ) 238 * </p> 239 * 240 * <h5 class='section'>Notes:</h5> 241 * <ul class='spaced-list'> 242 * <li> 243 * The format of this value is HTML. 244 * <li> 245 * A value of <js>"NONE"</js> can be used to force no header. 246 * <li> 247 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 248 * <li> 249 * Supports {@doc DefaultRestSvlVariables} 250 * (e.g. <js>"$L{my.localized.variable}"</js>). 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>@HtmlDoc</ja> annotation on the servlet/resource class. 255 * <li> 256 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 257 * parent class if not overridden. 258 * </ul> 259 * 260 * <h5 class='section'>See Also:</h5> 261 * <ul> 262 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_header} 263 * <li class='jm'>{@link HtmlDocBuilder#header(Object...)} 264 * </ul> 265 */ 266 String[] header() default {}; 267 268 /** 269 * Sets the HTML nav section contents. 270 * 271 * <p> 272 * The nav section of the page contains the links. 273 * 274 * <h5 class='section'>Example:</h5> 275 * <p class='bcode w800'> 276 * <ja>@RestResource</ja>( 277 * htmldoc=<ja>@HtmlDoc</ja>( 278 * nav={ 279 * <js>"<h5>Custom nav content</h5>"</js> 280 * } 281 * ) 282 * ) 283 * </p> 284 * 285 * <h5 class='section'>Notes:</h5> 286 * <ul class='spaced-list'> 287 * <li> 288 * The format of this value is HTML. 289 * <li> 290 * When {@link #navlinks()} is also specified, this content is placed AFTER the navigation links. 291 * <li> 292 * Supports {@doc DefaultRestSvlVariables} 293 * (e.g. <js>"$L{my.localized.variable}"</js>). 294 * <li> 295 * A value of <js>"NONE"</js> can be used to force no value. 296 * <li> 297 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 298 * <li> 299 * Multiple values are combined with newlines into a single string. 300 * <li> 301 * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class. 302 * <li> 303 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 304 * parent class. 305 * </ul> 306 * 307 * <h5 class='section'>See Also:</h5> 308 * <ul> 309 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_nav} 310 * <li class='jm'>{@link HtmlDocBuilder#nav(Object...)} 311 * </ul> 312 */ 313 String[] nav() default {}; 314 315 /** 316 * Sets the links in the HTML nav section. 317 * 318 * <p> 319 * The page links are positioned immediately under the title and text. 320 * 321 * <p> 322 * The value is an array of strings with two possible values: 323 * <ul> 324 * <li>A key-value pair representing a hyperlink label and href: 325 * <br><js>"google: http://google.com"</js> 326 * <li>Arbitrary HTML. 327 * </ul> 328 * 329 * <h5 class='section'>Example:</h5> 330 * <p class='bcode w800'> 331 * <ja>@RestResource</ja>( 332 * htmldoc=<ja>@HtmlDoc</ja>( 333 * navlinks={ 334 * <js>"up: request:/.."</js>, 335 * <js>"options: servlet:/?method=OPTIONS"</js> 336 * } 337 * ) 338 * ) 339 * </p> 340 * 341 * <h5 class='section'>Notes:</h5> 342 * <ul class='spaced-list'> 343 * <li> 344 * Supports {@doc DefaultRestSvlVariables} 345 * (e.g. <js>"$L{my.localized.variable}"</js>). 346 * <li> 347 * A value of <js>"NONE"</js> can be used to force no value. 348 * <li> 349 * The parent links can be included by adding the literal <js>"INHERIT"</js> as a value. 350 * <br>Use the syntax <js>"key[index]: value"</js> or <js>"[index]: value"</js> to specify an index location 351 * to place a link inside the list of parent links. 352 * <li> 353 * Supports {@doc juneau-marshall.URIs} (e.g. <js>"servlet:/..."</js>, <js>"request:/..."</js>). 354 * <li> 355 * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class. 356 * <li> 357 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 358 * parent class. 359 * </ul> 360 * 361 * <h5 class='section'>See Also:</h5> 362 * <ul> 363 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_navlinks} 364 * <li class='jm'>{@link HtmlDocBuilder#navlinks(Object...)} 365 * </ul> 366 */ 367 String[] navlinks() default {}; 368 369 /** 370 * Specifies the text to display when serializing an empty array or collection. 371 * 372 * <h5 class='section'>Notes:</h5> 373 * <ul class='spaced-list'> 374 * <li> 375 * Supports {@doc DefaultRestSvlVariables} 376 * (e.g. <js>"$L{my.localized.variable}"</js>). 377 * </ul> 378 * 379 * <h5 class='section'>See Also:</h5> 380 * <ul> 381 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_noResultsMessage} 382 * <li class='jm'>{@link HtmlDocBuilder#noResultsMessage(Object)} 383 * </ul> 384 */ 385 String noResultsMessage() default "no results"; 386 387 /** 388 * Shorthand method for forcing the rendered HTML content to be no-wrap. 389 * 390 * <p> 391 * This only applies to the rendered data portion of the page. 392 * 393 * <h5 class='section'>See Also:</h5> 394 * <ul> 395 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_nowrap} 396 * <li class='jm'>{@link HtmlDocBuilder#nowrap(boolean)} 397 * </ul> 398 */ 399 String nowrap() default ""; 400 401 /** 402 * Sets the HTML script section contents. 403 * 404 * <h5 class='section'>Example:</h5> 405 * <p class='bcode w800'> 406 * <ja>@RestResource</ja>( 407 * htmldoc=<ja>@HtmlDoc</ja>( 408 * script={ 409 * <js>"alert('Hello!')"</js> 410 * } 411 * ) 412 * ) 413 * </p> 414 * 415 * <h5 class='section'>Notes:</h5> 416 * <ul class='spaced-list'> 417 * <li> 418 * The format of this value is Javascript. 419 * <li> 420 * Supports {@doc DefaultRestSvlVariables} 421 * (e.g. <js>"$L{my.localized.variable}"</js>). 422 * <li> 423 * A value of <js>"NONE"</js> can be used to force no value. 424 * <li> 425 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 426 * <li> 427 * Multiple values are combined with newlines into a single string. 428 * <li> 429 * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class. 430 * <li> 431 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 432 * parent class. 433 * </ul> 434 * 435 * <h5 class='section'>See Also:</h5> 436 * <ul> 437 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_script} 438 * <li class='jm'>{@link HtmlDocBuilder#script(Object[])} 439 * </ul> 440 */ 441 String[] script() default {}; 442 443 /** 444 * Sets the HTML CSS style section contents. 445 * 446 * <h5 class='section'>Example:</h5> 447 * <p class='bcode w800'> 448 * <ja>@RestResource</ja>( 449 * htmldoc=<ja>@HtmlDoc</ja>( 450 * style={ 451 * <js>".red{color:red;}"</js>, 452 * <js>".blue{color:blue;}"</js> 453 * } 454 * ) 455 * ) 456 * </p> 457 * 458 * <h5 class='section'>Notes:</h5> 459 * <ul class='spaced-list'> 460 * <li> 461 * The format of this value is CSS. 462 * <li> 463 * Supports {@doc DefaultRestSvlVariables} 464 * (e.g. <js>"$L{my.localized.variable}"</js>). 465 * <li> 466 * A value of <js>"NONE"</js> can be used to force no value. 467 * <li> 468 * The parent value can be included by adding the literal <js>"INHERIT"</js> as a value. 469 * <li> 470 * Multiple values are combined with newlines into a single string. 471 * <li> 472 * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class. 473 * <li> 474 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 475 * parent class. 476 * </ul> 477 * 478 * <h5 class='section'>See Also:</h5> 479 * <ul> 480 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_style} 481 * <li class='jm'>{@link HtmlDocBuilder#style(Object[])} 482 * </ul> 483 */ 484 String[] style() default {}; 485 486 /** 487 * Sets the CSS URL in the HTML CSS style section. 488 * 489 * <p> 490 * Specifies the URL to the stylesheet to add as a link in the style tag in the header. 491 * 492 * <h5 class='section'>Example:</h5> 493 * <p class='bcode w800'> 494 * <ja>@RestResource</ja>( 495 * htmldoc=<ja>@HtmlDoc</ja>( 496 * stylesheet=<js>"http://someOtherHost/stealTheir.css"</js> 497 * ) 498 * ) 499 * </p> 500 * 501 * <h5 class='section'>Notes:</h5> 502 * <ul class='spaced-list'> 503 * <li> 504 * The format of this value is a URL. 505 * <li> 506 * Supports {@doc DefaultRestSvlVariables} 507 * (e.g. <js>"$L{my.localized.variable}"</js>). 508 * <li> 509 * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class. 510 * <li> 511 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 512 * parent class. 513 * </ul> 514 * 515 * <h5 class='section'>See Also:</h5> 516 * <ul> 517 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_stylesheet} 518 * <li class='jm'>{@link HtmlDocBuilder#stylesheet(Object[])} 519 * </ul> 520 */ 521 String[] stylesheet() default {}; 522 523 /** 524 * Specifies the template class to use for rendering the HTML page. 525 * 526 * <p> 527 * By default, uses {@link BasicHtmlDocTemplate} to render the contents, although you can provide your own custom 528 * renderer or subclasses from the basic class to have full control over how the page is rendered. 529 * 530 * <h5 class='section'>Notes:</h5> 531 * <ul class='spaced-list'> 532 * <li> 533 * On methods, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the servlet/resource class. 534 * <li> 535 * On servlet/resource classes, this value is inherited from the <ja>@HtmlDoc</ja> annotation on the 536 * parent class. 537 * </ul> 538 * 539 * <h5 class='section'>See Also:</h5> 540 * <ul> 541 * <li class='jf'>{@link HtmlDocSerializer#HTMLDOC_template} 542 * <li class='jm'>{@link HtmlDocBuilder#template(Class)} 543 * <li class='jm'>{@link HtmlDocBuilder#template(HtmlDocTemplate)} 544 * </ul> 545 */ 546 Class<? extends HtmlDocTemplate> template() default HtmlDocTemplate.class; 547 548 /** 549 * Configuration property: HTML Widgets. 550 * 551 * <p> 552 * Defines widgets that can be used in conjunction with string variables of the form <js>"$W{name}"</js>to quickly 553 * generate arbitrary replacement text. 554 * 555 * <p> 556 * Widgets resolve the following variables: 557 * 558 * <ul class='spaced-list'> 559 * <li> 560 * <js>"$W{name}"</js> - Contents returned by {@link Widget#getHtml(RestRequest)}. 561 * <li> 562 * <js>"$W{name.script}"</js> - Contents returned by {@link Widget#getScript(RestRequest)}. 563 * <br>The script contents are automatically inserted into the <xt><head/script></xt> section 564 * in the HTML page. 565 * <li> 566 * <js>"$W{name.style}"</js> - Contents returned by {@link Widget#getStyle(RestRequest)}. 567 * <br>The styles contents are automatically inserted into the <xt><head/style></xt> section 568 * in the HTML page. 569 * </ul> 570 * 571 * <p> 572 * The following examples shows how to associate a widget with a REST method and then have it rendered in the links 573 * and aside section of the page: 574 * 575 * <p class='bcode w800'> 576 * <ja>@RestMethod</ja>( 577 * widgets={ 578 * MyWidget.<jk>class</jk> 579 * } 580 * htmldoc=<ja>@HtmlDoc</ja>( 581 * navlinks={ 582 * <js>"$W{MyWidget}"</js> 583 * }, 584 * aside={ 585 * <js>"Check out this widget: $W{MyWidget}"</js> 586 * } 587 * ) 588 * ) 589 * </p> 590 * 591 * <h5 class='section'>Notes:</h5> 592 * <ul class='spaced-list'> 593 * <li> 594 * Widgets are inherited from parent to child, but can be overridden by reusing the widget name. 595 * <li> 596 * Values are appended to the existing list. 597 * </ul> 598 * 599 * <h5 class='section'>See Also:</h5> 600 * <ul> 601 * <li class='link'>{@doc juneau-rest-server.HtmlDocAnnotation.Widgets} 602 * </ul> 603 */ 604 Class<? extends Widget>[] widgets() default {}; 605}