001    // Copyright 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // 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
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry.form;
016    
017    import org.apache.tapestry.IComponent;
018    import org.apache.tapestry.json.JSONObject;
019    
020    /**
021     * Object that provides support to objects that implement
022     * {@link org.apache.tapestry.form.FormComponentContributor}. For the moment, at least, this is all
023     * about client-side JavaScript generation.
024     * <p>
025     * TODO: Having support for regular expressions might be useful (and would allow a single
026     * {@link RegexpMatcher to be shared).
027     * 
028     * @author Howard Lewis Ship
029     * @since 4.0
030     */
031    public interface FormComponentContributorContext extends ValidationMessages
032    {
033        /**
034         * Includes the indicated script; the path is a path on the classpath.
035         */
036    
037        void includeClasspathScript(String path);
038    
039        /**
040         * Adds initialization to register a submit handler on the client side. A submit handler is a
041         * JavaScript method that accepts a single parameter, a (JavaScript) FormSubmitEvent.
042         * 
043         * @param submitListener
044         *            either the name of a submit listener ("myListener"), or an inline implementation
045         *            of a listener function ("function(event) { ... } ").
046         */
047    
048        void addSubmitHandler(String handler);
049        
050        /**
051         * Adds initialization javascript code that will be executed on page/content/etc load.
052         * @param target 
053         *          The component the script is being added for.
054         * @param script
055         *          The javascript code to execute.
056         */
057        void addInitializationScript(IComponent target, String script);
058        
059        /**
060         * Registers a field for automatic focus. The goal is for the first field that is in error to
061         * get focus; failing that, the first required field; failing that, any field.
062         * 
063         * @param priority
064         *            a priority level used to determine whether the registered field becomes the focus
065         *            field. Constants for this purpose are defined in {@link ValidationConstants}.
066         * @see org.apache.tapestry.FormBehavior#registerForFocus(IFormComponent, int)
067         */
068    
069         void registerForFocus(int priority);
070         
071         /**
072          * The javascript object profile being built by this context to validate/translate
073          * form values. This is really just a delegate to {@link FormBehavior}.
074          * @return {@link JSONObject} profile.
075          */
076         JSONObject getProfile();
077    }