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.FormBehavior;
018    import org.apache.tapestry.IComponent;
019    import org.apache.tapestry.json.JSONObject;
020    import org.apache.tapestry.util.RegexpMatcher;
021    import org.apache.tapestry.valid.ValidationConstants;
022    
023    /**
024     * Object that provides support to objects that implement
025     * {@link org.apache.tapestry.form.FormComponentContributor}. For the moment, at least, this is all
026     * about client-side JavaScript generation.
027     * <p>
028     * TODO: Having support for regular expressions might be useful (and would allow a single
029     * {@link RegexpMatcher to be shared}).
030     * 
031     * @author Howard Lewis Ship
032     * @since 4.0
033     */
034    public interface FormComponentContributorContext extends ValidationMessages
035    {
036        /**
037         * Includes the indicated script; the path is a path on the classpath.
038         */
039    
040        void includeClasspathScript(String path);
041    
042        /**
043         * Adds initialization to register a submit handler on the client side. A submit handler is a
044         * JavaScript method that accepts a single parameter, a (JavaScript) FormSubmitEvent.
045         * 
046         * @param handler
047         *            either the name of a submit listener ("myListener"), or an inline implementation
048         *            of a listener function ("function(event) { ... } ").
049         * @deprecated To be removed in 4.2 with no replacement. The new preferred way to do this is by using simple
050         * <code>dojo.event.connect("formName", "event", object, "functionName)</code> style connections.
051         */
052    
053        void addSubmitHandler(String handler);
054        
055        /**
056         * Adds initialization javascript code that will be executed on page/content/etc load.
057         * @param target 
058         *          The component the script is being added for.
059         * @param script
060         *          The javascript code to execute.
061         */
062        void addInitializationScript(IComponent target, String script);
063        
064        /**
065         * Registers a field for automatic focus. The goal is for the first field that is in error to
066         * get focus; failing that, the first required field; failing that, any field.
067         * 
068         * @param priority
069         *            a priority level used to determine whether the registered field becomes the focus
070         *            field. Constants for this purpose are defined in {@link ValidationConstants}.
071         * @see org.apache.tapestry.FormBehavior#registerForFocus(IFormComponent, int)
072         */
073    
074         void registerForFocus(int priority);
075         
076         /**
077          * The javascript object profile being built by this context to validate/translate
078          * form values. This is really just a delegate to {@link FormBehavior}.
079          * @return {@link JSONObject} profile.
080          */
081         JSONObject getProfile();
082    }