Resource Library Contracts

Resource library contracts allow you to define a different look and feel for different parts of one or more applications, instead of either having to use the same look and feel for all or having to specify a different look on a page-by-page basis.

To do this, you create a contracts section of your web application. Within the contracts section, you can specify any number of named areas, each of which is called a contract. Within each contract you can specify resources such as template files, stylesheets, JavaScript files, and images.

For example, you could specify two contracts named c1 and c2, each of which uses a template and other files:

src/main/webapp
    WEB-INF/
    contracts
        c1
            template.xhtml
            style.css
            myImg.gif
            myJS.js
        c2
            template.xhtml
            style2.css
            img2.gif
            JS2.js
    index.xhtml
    ...

One part of the application can use c1, while another can use c2.

Another way to use contracts is to specify a single contract that contains multiple templates:

src/main/webapp
    contracts
        myContract
            template1.xhtml
            template2.xhtml
            style.css
            img.png
            img2.png

You can package a resource library contract in a JAR file for reuse in different applications. If you do so, the contracts must be located under META-INF/contracts. You can then place the JAR file in the WEB-INF/lib directory of an application. This means that the application would be organized as follows:

src/main/webapp/
    WEB-INF/lib/myContract.jar
    ...

You can specify the contract usage within an application’s faces-config.xml file, under the resource-library-contracts element. You need to use this element only if your application uses more than one contract, however.

The hello1-rlc Example Application

The hello1-rlc example modifies the simple hello1 example from A Web Module That Uses JavaServer Faces Technology: The hello1 Example to use two resource library contracts. Each of the two pages in the application uses a different contract.

The managed bean for hello1-rlc, Hello.java, is identical to the one for hello1 (except that it replaces the @Named and @RequestScoped annotations with @Model).

The source code for this application is in the tut-install`/examples/web/jsf/hello1-rlc/` directory.

The following topics are addressed here:

Configuring the hello1-rlc Example
The Facelets Pages for the hello1-rlc Example
To Build, Package, and Deploy the hello1-rlc Example Using NetBeans IDE
To Build, Package, and Deploy the hello1-rlc Example Using Maven
To Run the hello1-rlc Example

Configuring the hello1-rlc Example

The faces-config.xml file for the hello1-rlc example contains the following elements:

<resource-library-contracts>
    <contract-mapping>
        <url-pattern>/reply/*</url-pattern>
        <contracts>reply</contracts>
    </contract-mapping>
    <contract-mapping>
        <url-pattern>*</url-pattern>
        <contracts>hello</contracts>
    </contract-mapping>
</resource-library-contracts>

The contract-mapping elements within the resource-library-contracts element map each contract to a different set of pages within the application. One contract, named reply, is used for all pages under the reply area of the application (/reply/*). The other contract, hello, is used for all other pages in the application (*).

The application is organized as follows:

hello1-rlc
    pom.xml
    src/main/java/javaeetutorial/hello1rlc/Hello.java
    src/main/webapp
        WEB-INF
            faces-config.xml
            web.xml
        contracts
            hello
                default.css
                duke.handsOnHips.gif
                template.xhtml
            reply
                default.css
                duke.thumbsup.gif
                template.xhtml
        reply
            response.xhtml
        greeting.xhtml

The web.xml file specifies the welcome-file as greeting.xhtml. Because it is not located under src/main/webapp/reply, this Facelets page uses the hello contract, whereas src/main/webapp/reply/response.xhtml uses the reply contract.

The Facelets Pages for the hello1-rlc Example

The greeting.xhtml and response.xhtml pages have identical code calling in their templates:

<ui:composition template="/template.xhtml">

The template.xhtml files in the hello and reply contracts differ only in two respects: the placeholder text for the title element ("Hello Template" and "Reply Template") and the graphic that each specifies.

The default.css stylesheets in the two contracts differ in only one respect: the background color specified for the body element.

To Build, Package, and Deploy the hello1-rlc Example Using NetBeans IDE

Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).
From the File menu, choose Open Project.
In the Open Project dialog box, navigate to:
```
tut-install/examples/web/jsf
```
Select the hello1-rlc folder.
Click Open Project.
In the Projects tab, right-click the hello1-rlc project and select Build.

This option builds the example application and deploys it to your GlassFish Server instance.

To Build, Package, and Deploy the hello1-rlc Example Using Maven

Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).

In a terminal window, go to:

tut-install/examples/web/jsf/hello1-rlc/

Enter the following command:
```
mvn install
```
This command builds and packages the application into a WAR file, hello1-rlc.war, that is located in the target directory. It then deploys it to your GlassFish Server instance.

To Run the hello1-rlc Example

Enter the following URL in your web browser:
```
http://localhost:8080/hello1-rlc
```
The greeting.xhtml page looks just like the one from hello1 except for its background color and graphic.
In the text field, enter your name and click Submit.
The response page also looks just like the one from hello1 except for its background color and graphic.

The page displays the name you submitted. Click Back to return to the greeting.xhtml page.