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