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    /**
018     * Object that provides support to objects that implement
019     * {@link org.apache.tapestry.form.FormComponentContributor}. For the moment, at least, this is all
020     * about client-side JavaScript generation.
021     * <p>
022     * TODO: Having support for regular expressions might be useful (and would allow a single
023     * {@link RegexpMatcher to be shared).
024     * 
025     * @author Howard Lewis Ship
026     * @since 4.0
027     */
028    public interface FormComponentContributorContext extends ValidationMessages
029    {
030        /**
031         * Includes the indicated script; the path is a path on the classpath.
032         */
033    
034        public void includeClasspathScript(String path);
035    
036        /**
037         * Adds initialization to register a submit handler on the client side. A submit handler is a
038         * JavaScript method that accepts a single parameter, a (JavaScript) FormSubmitEvent.
039         * 
040         * @param submitListener
041         *            either the name of a submit listener ("myListener"), or an inline implementation
042         *            of a listener function ("function(event) { ... } ").
043         */
044    
045        public void addSubmitHandler(String handler);
046    
047        /**
048         * Registers a field for automatic focus. The goal is for the first field that is in error to
049         * get focus; failing that, the first required field; failing that, any field.
050         * 
051         * @param priority
052         *            a priority level used to determine whether the registered field becomes the focus
053         *            field. Constants for this purpose are defined in {@link ValidationConstants}.
054         * @see org.apache.tapestry.FormBehavior#registerForFocus(IFormComponent, int)
055         */
056    
057        public void registerForFocus(int priority);
058    }