Weblets

Setup Short summary:

Every basic JSF setup should work out of the box in a plug and play way. The only thing you which is needed is a valid path triggering pattern for the faces servlet.

Code 0: valid path pattern in the web.xml

   <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
  </servlet-mapping>

Of course file patterns can be used additionally.

Another limitation of this system is, if you use a Faces Servlet which is not the standard JSF one you have to do a fallback to the generic configuration! However you still can use all of the other features Weblets provides for jsf.

JSF 1.1

Although nowadays basically a legacy technology, but still widely used, JSF 1.1 has several limitations regarding its frontend technologies and the usage of EL. JSF 1.1 in most cases relies on JSP as frontend view technology with its own api providing the additional work, and as EL it provides its own EL technology.

Now to use Weblets in JSF 1.1, you have basically two options

1. For cases outside of the JSF area (areas in your page outside of f:view) rely on basic jsp mechanisms as described in JSP : Usage page
2. Within JSF areas you can rely on an EL dummy map provided automatically to your JSF system. To use it no additional configuration is needed

The following code example showcases the usage of this EL dummy map:

Code 3: Usage or resource and url in a JSF frontend environment

  <h:outputText value="#{weblet.url['weblets.demo']['/welcome.js']}" />
  <h:graphicImage value="#{weblet.resource['weblets.demo']['/img/icon_alert.gif']}" />

In this example you can precisely see why you need sometimes resource weblet.resource or url weblet.url , in this example h:graphicImage adds the application context itself so we dont need a full url including the web application context, instead we just need a path relative to it.

Code 4: Difference between url and resource in a JSF specific api

   #{weblet.url['weblets.demo']['/welcome.js']}

Is a typical JSF dummy map. One of JSF 1.1s EL implementation is, it does not allow functions which would easy the extension of the wel, all it allows is properties and maps. To allow a function like behavior you can map the functionality into dummy maps and pass the parameters over the map keys.

Facelets and JSF 1.2

The last years facelets has become the frontend technology for many projects. One of the advantages of facelets is that it already provides a JSP 2.x and JSF 1.2 el, so that you automatically can start to use the features of the EL in there. The above mentioned things also are valid for JSF 1.2 which also has the latest EL implementation available.

If you are in a facelet domain you have two options to utilize weblets

1. via EL functions (the same as in jsp 2.x)
2. via the above described dummy maps

Newer EL implementations provide so called EL functions, those are functions which can be added to the actual EL implementation to extend its functionality. If you are in a system which uses newer EL implementations, it is highly recommended to use those instead of the dummy maps.

The next example shows how to use the EL functions:

Code 5: Usage of EL functions in faclets

     xmlns:wbl="http://weblets.dev.java.net/facelet-tags"  this has to be added to your namespace definitions

      <h:outputText value="${weblet:url('weblets.demo','/welcome.js')}" />
      <h:graphicImage value="${weblet:resource('weblets.demo','/img/icon_alert.gif')}" />

     xmlns:wbl="http://weblets.dev.java.net/tags"
      <h:outputText value="${weblet:url('weblets.demo','/welcome.js')}" />
      <h:graphicImage value="${weblet:resource('weblets.demo','/img/icon_alert.gif')}" />

As you can see the calls are very similar, but instead of reverting into a (still available) JSF dummy map we call directly EL functions we added to our page by adding another xml namespace to our xmlns definitions.

For an extensive examples of the EL function calls, check out the weblets-demo application provided with your weblets download package