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
015package 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 */
028public 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}