View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.myfaces.trinidad.convert;
20  
21  import java.util.Collection;
22  
23  import javax.faces.component.UIComponent;
24  import javax.faces.context.FacesContext;
25  
26  /**
27   * <p>
28   * Interface implemented by Objects that wish to perform client-side
29   * conversion in addition to server-side conversion.  Client side conversion
30   * should always be the same as or more lenient than the server-side
31   * conversion.
32   * </p>
33   *
34   * <P>
35   *     One of the benefits of Apache Trinidad is that it supports client-side versions of converters and validators. This means that errors can be caught on the client and a round trip avoided. This interface can be used to add client-side conversion to a converter.
36   *     </P>
37   *     <p>
38   *     The basic idea of Apache Trinidad client-side conversion is that it works on the client in a very similar way to how it works on the server, except the language on the client is javascript instead of java. Apache Trinidad supports javascript Converter objects that support the methods getAsString() and getAsObject(). A Converter can throw a ConverterException.
39   *     </p>      Let's say you've written a javax.faces.convert.Converter implementation and now you want to add client-side conversion. The first thing to do is write a version of the converter in javascript. Here is the javascript code for the converter "interface".
40   *     </p>
41   *       <p>
42   *  <pre><code>
43   * /**
44   *  * Converter "interface" similar to javax.faces.convert.Converter,
45   *  * except that all relevant information must be passed to the constructor
46   *  * as the context and component are not passed to the getAsString or getAsObject method
47   *  *
48   *  * /
49   * function Converter()
50   * {
51   * }
52   *
53   *  /**
54   *  * Convert the specified model object value, into a String for display
55   *  *
56   *  * @param value Model object value to be converted
57   *  * /
58   * Converter.prototype.getAsString = function(value){}
59   *
60   * /**
61   *  * Convert the specified string value into a model data object
62   *  * which can be passed to validators
63   *  *
64   *  * @param value String value to be converted
65   *  * /
66   * Converter.prototype.getAsObject = function(value){}
67   * </code></pre>
68   * Converters can throw a ConverterException, here is the signature:
69   * <ul>
70   * <li>ConverterException(detail)
71   *  <ul>
72   *    <li>detail - Localized detail message text </li>
73   *   </ul>
74   * </li>
75   * </ul>
76   * The method
77   * <ul>
78   *   <li><code>getClientLibrarySource()</code> is expected to return a library
79   * that has an implementation of the javascript Converter object.</li>
80   *   <li><code>getClientConversion()</code> is expected to return a
81   * javascript constructor which will be used to instantiate an instance of the converter.</li>
82   *   <li><code>getClientScript()</code> can be used to write out inline js.</li>
83   *   <li><code>getClientImportNames()</code> is used to import the built-in scripts provided by Apache Trinidad.</li>
84   *  </ul>
85   * </p>
86   * <p>
87   * @see javax.faces.convert.Converter
88   */
89  public interface ClientConverter
90  {
91  
92    /**
93     * Gets the URI specifying the location of the js lib resource.
94     * Only the first reference to a library will result in its being imported.
95     */
96    public String getClientLibrarySource(
97     FacesContext context);
98  
99    /**
100    * Supports importing the built-in scripts provided by Apache Trinidad.
101    * It can be used to ensure that a Javascript function is available
102    * before using it in a Javascript handler.
103    * Only the first reference to a script will result in its being imported.
104    * <p>If this function returns null "Converter()" will be used.
105    * @return a collection of function names
106    */
107   public Collection<String> getClientImportNames();
108 
109 
110   /**
111    * Opportunity for the ClientConverter to return script content.
112    * For HTML, this will be javascript that will be embedded in a
113    * script tag. For HTML this method is expected to return an
114    * implementation of the javascript Converter object.
115    * <p>Do not rely on this content being ppr updated.
116    * <p>This method will be called once per converter instance.
117    * Content that should only be written once per request
118    * should only be returned once.
119    */
120   public String getClientScript(
121    FacesContext context,
122    UIComponent component);
123 
124   /**
125    * Called to retrieve the appropriate client
126    * conversion code for the node and context.
127    * For HTML, this will be javascript that will be embedded in a
128    * script tag. For HTML this method is expected to return a
129    * constructor of the javascript Converter object
130    * returned by getClientScript().
131    */
132   public String getClientConversion(
133    FacesContext context,
134    UIComponent component);
135 
136   static public final String ALERT_FORMAT_KEY =
137     "org.apache.myfaces.trinidad.convert.ALERT_FORMAT";
138 }