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