juneau-doc/docs/ReleaseNotes/6.3.1.html

<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

6.3.1 (Aug 1, 2017)

<p>
	Juneau 6.3.1 is a minor release.
</p>

<h5 class='topic w800'>org.apache.juneau</h5>
<ul class='spaced-list'>
	<li>
		{@link oaj.utils.PojoQuery} improvements.
	<li>
		New <dc>RemoteMethod.returns()</dc> annotation.
		<br>Allows you to specify whether the remote method returns the HTTP body or status code.
	<li>
		Fixed bugs with <dc>BEAN_includeProperties</dc> and <dc>BEAN_excludeProperties</dc> settings.
	<li>
		New/modified settings in <dc>HtmlDocSerializerContext</dc>:
		<ul>
			<li><dc>HTMLDOC_script</dc>
			<li><dc>HTMLDOC_style</dc> - Was <jsf>HTMLDOC_css</jsf>.
			<li><dc>HTMLDOC_stylesheet</dc> - Was <jsf>HTMLDOC_cssUrl</jsf>.  Now an array.
		</ul>
	<li>
		New <dc>ResourceFinder</dc> utility class.
		Allows you to search for resources up the parent hierarchy chain.
		Also allows you to search for localized resources.
	<li>
		Eliminated the following properties from <dc>HtmlDocSerializerContext</dc>:
		<jsf>HTMLDOC_title</jsf>, <jsf>HTMLDOC_description</jsf>, <jsf>HTMLDOC_description</jsf>
		<br>See below on changes to simplify HTML headers.
	<li>
		{@link oaj.svl.Var} implementations can now throw exceptions and will be converted to
		<js>""{exceptionMessage}"</js> values.
</ul>

<h5 class='topic w800'>org.apache.juneau.rest</h5>
<ul class='spaced-list'>
	<li>
		New 'light' stylesheet:
		<br><img src='doc-files/ReleaseNotes.631.LightStyle.png'>
		<br>Compared with previous 'devops':
		<br><img src='doc-files/ReleaseNotes.631.DevopsStyle.png'>
		<br>For those nolstalgic for old times, there's also 'original':
		<br><img src='doc-files/ReleaseNotes.631.OriginalStyle.png'>
	<li>
		Simplified the stylesheets and HTML code.
		<br>For example, the nav links are now an ordered list of elements which makes rendering as as side-bar
		(for example) easier to do in CSS.
	<li>
		Modifications to the following <ja>@HtmlDoc</ja> annotations:
		<ul>
			<li>{@link oajr.annotation.HtmlDoc#navlinks() navlinks()} - Now an array of strings instead of a JSON object.  Simplified syntax.
				<br>For example:
				<p class='bcode w800'>
	<jc>// Old syntax</jc>
	htmldoc=<ja>@HtmlDoc</ja>(
		links=<js>"{"</js>
			+ <js>"up:'request:/..',"</js>
			+ <js>"options:'servlet:/?method=OPTIONS',"</js>
			+ <js>"contentTypes:'$W{ContentTypeMenuItem}',"</js>
			+ <js>"styles:'$W{StyleMenuItem}',"</js>
			+ <js>"source:'$C{Source/gitHub}/org/apache/juneau/examples/rest/PetStoreResource.java'"</js>
		+ <js>"}"</js>
	)
	
	<jc>// New syntax</jc>
	htmldoc=<ja>@HtmlDoc</ja>(
		navlinks={
			<js>"up: request:/.."</js>,
			<js>"options: servlet:/?method=OPTIONS"</js>,
			<js>"$W{ContentTypeMenuItem}"</js>,
			<js>"$W{StyleMenuItem}"</js>,
			<js>"source: $C{Source/gitHub}/org/apache/juneau/examples/rest/PetStoreResource.java"</js>
		}
	)
				</p>
				Previous syntax will still work, but you're encouraged to use the simplified syntax.
			<li>Several annotations are now arrays of strings instead of simple strings.
				Values are simply concatenated with newlines which makes multi-line values cleaner.
				<ul>
					<li>{@link oajr.annotation.HtmlDoc#header() header()}
					<li>{@link oajr.annotation.HtmlDoc#nav() nav()}
					<li>{@link oajr.annotation.HtmlDoc#aside() aside()}
					<li>{@link oajr.annotation.HtmlDoc#footer() footer()}
					<li>{@link oajr.annotation.HtmlDoc#script() script()}
					<li>{@link oajr.annotation.HtmlDoc#style() style()}
				</ul>
				Additionally, the <js>"INHERIT"</js> string literal can be used to combine the value with
				the value defined on the servlet or parent class.  Links can also be inserted at specific
				index positions.
		</ul>
	<li>
		Improvements made to the {@link oajr.widget.Widget} API.
		<ul>
			<li>
				You can now add arbitrary CSS and Javascript along with your widgets through new methods:
				<ul>
					<li><dc>Widget#getHtml(RestRequest)</dc>
					<li><dc>Widget#getScript(RestRequest)</dc>
					<li><dc>Widget#getStyle(RestRequest)</dc>
				</ul>
			</li>
			<li>
				Declaration of widgets moved to {@link oajr.annotation.HtmlDoc#widgets() @HtmlDoc(widgets)} 
				instead of separately on <dc>@RestResource</dc> and <ja>@RestMethod</ja> annotations.
			<li>
				{@link oajr.widget.Widget#getName()} now defaults to the simple class name.
				<br>So now you can just refer to the class name: <js>"$W{ContentTypeMenuItem}"</js>.
			<li>
				Renamed widgets:
				<ul>
					<li><c>PoweredByApacheWidget</c> -&gt; <c>PoweredByApache</c>  
					<li><c>PoweredByJuneauWidget</c> -&gt; <c>PoweredByJuneau</c>  
				</ul>
			<li>
				New {@link oajr.widget.MenuItemWidget} can be used as a starting point for creatint pull-down menu items.
			<li>
				New {@link oajr.widget.ContentTypeMenuItem} widget that provides a pull-down menu 
				with hyperlinks for all supported languages for that page:
				<br><img src='doc-files/ReleaseNotes.631.ContentTypeMenuItem.png'>
			<li>
				Improved {@link oajr.widget.QueryMenuItem} widget that provides a pull-down menu
				of a search/view/order-by/page form:
				<br><img src='doc-files/ReleaseNotes.631.QueryMenuItem.png'>
				<br>Fields are now pre-filled with current query parameters.
			<li>
				New {@link oajr.widget.ThemeMenuItem} widget that provides a pull-down menu 
				with hyperlinks to show the content in the default stylesheets:
				<br><img src='doc-files/ReleaseNotes.631.StyleMenuItem.png'>
		</ul>
	<li>
		New/modified annotations on {@link oajr.annotation.HtmlDoc @HtmlDoc}:
		<ul>
			<li>{@link oajr.annotation.HtmlDoc#style() style()} - Renamed from <c>css()</c>.
			<li>{@link oajr.annotation.HtmlDoc#stylesheet() stylesheet()} - Renamed from <c>cssUrl()</c>.
				<br>Can now be a comma-delimited list of URLs.
			<li>{@link oajr.annotation.HtmlDoc#script() script()} - Add arbitrary Javascript to page header.
		</ul>

	<li>
		Bug fix with {@link oajr.annotation.HtmlDoc#nowrap() @HtmlDoc(nowrap)} so that the setting only applies
		to the data contents, not the whole page.
	<li>
		Two convenience methods added to {@link oajr.RestRequest}:
		<ul>
			<li>{@link oajr.RestRequest#attr(String,Object) attr(String,Object)}
			<li>{@link oajr.RestRequest#prop(String,Object) prop(String,Object)}
		</ul>
	</li>
	<li>
		Annotations added:
		<ul>
			<li><dc>@RestResource(siteName)</dc>
			<li><dc>@RestResource(flags)</dc>
			<li>{@link oajr.annotation.RestMethod#flags() @RestMethod(flags)}
		</ul>
	</li>
	<li>
		Eliminated the <dc>@RestResource(stylesheet)</dc> annotation.  
		It's no longer needed now that you can easily specify styles via <ja>@Htmldoc</ja>.
	<li>
		Eliminated the following annotations since they are now redundant with {@link oajr.annotation.HtmlDoc#header() @HtmlDoc(header)}:
		<ul>
			<li><c>title()</c>
			<li><c>description()</c>
			<li><c>branding()</c>
		</ul>
		Instead, the {@link oajr.BasicRestServlet} class defines the following default header
		that can be easily overridden: 
		<p class='bcode w800'>
	htmldoc=<ja>@HtmlDoc</ja>(
		header={
			<js>"&lt;h1&gt;$R{resourceTitle}&lt;/h1&gt;"</js>,
			<js>"&lt;h2&gt;$R{methodSummary,resourceDescription}&lt;/h2&gt;"</js>,
			<js>"&lt;a href='http://juneau.apache.org'&gt;&lt;img src='$U{servlet:/htdocs/juneau.png}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/&gt;&lt;/a&gt;"</js>
		}
	)
		</p>
		Note that the subtitle first tries using the method summary and then the servlet description.
	<li>
		New {@link oajr.vars.FileVar $F} variable resolver for resolving the contents of 
		files in the classpath.
		<br>The <c>DockerRegistryResource</c> examples shows how it can be used to pull in a localized
		file from the classpath to populate the aside section of a page.
		<p class='bcode w800'>
	htmldoc=<ja>@HtmlDoc</ja>(
		<jc>// Pull in aside contents from file.</jc>
		aside=<js>"$F{resources/DockerRegistryResourceAside.html}"</js>
	)
		</p>
	<li>
		New <dc>ReaderResource.toCommentStrippedString()</dc> method.
	<li>
		The <c>bpIncludes()</c> and <c>bpExcludes()</c> annotations on <ja>@RestMethod</ja>
		has been replaced with the following:
		<ul>
			<li>{@link oajr.annotation.RestMethod#bpi() bpi()} - Now an array of simplified values instead of LAX JSON.
			<li>{@link oajr.annotation.RestMethod#bpx() bpx()} - Now an array of simplified values instead of LAX JSON.
		</ul>
	<li>
		Two new variables added to <c>$R</c> variable: <js>"$R{servletClass}"</js>, <js>"$R{servletClassSimple}"</js>
</ul>

<h5 class='topic w800'>org.apache.juneau.rest.examples</h5>
<ul class='spaced-list'>
	<li>
		Added CONTENT-TYPE and STYLES menu items to most pages.
	<li>
		Added improved QUERY menu item to PetStore page.
</ul>