Home » tapestry-src-5.0.19 » org.apache.tapestry5.corelib.components » [javadoc | source]

    1   // Copyright 2007, 2008 The Apache Software Foundation
    2   //
    3   // Licensed under the Apache License, Version 2.0 (the "License");
    4   // you may not use this file except in compliance with the License.
    5   // You may obtain a copy of the License at
    6   //
    7   //     http://www.apache.org/licenses/LICENSE-2.0
    8   //
    9   // Unless required by applicable law or agreed to in writing, software
   10   // distributed under the License is distributed on an "AS IS" BASIS,
   11   // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   12   // See the License for the specific language governing permissions and
   13   // limitations under the License.
   14   
   15   package org.apache.tapestry5.corelib.components;
   16   
   17   import org.apache.tapestry5;
   18   import org.apache.tapestry5.annotations.Component;
   19   import org.apache.tapestry5.annotations.Parameter;
   20   import org.apache.tapestry5.annotations.Property;
   21   import org.apache.tapestry5.annotations.SupportsInformalParameters;
   22   import org.apache.tapestry5.beaneditor.BeanModel;
   23   import org.apache.tapestry5.internal.beaneditor.BeanModelUtils;
   24   import org.apache.tapestry5.ioc.annotations.Inject;
   25   import org.apache.tapestry5.services.BeanModelSource;
   26   
   27   /**
   28    * A component that creates an entire form editing the properties of a particular bean. Inspired by <a
   29    * href="http://www.trailsframework.org/">Trails</a> and <a href="http://beanform.sourceforge.net/">BeanForm</a> (both
   30    * for Tapestry 4). Generates a simple UI for editing the properties of a JavaBean, with the flavor of UI for each
   31    * property (text field, checkbox, drop down list) determined from the property type (or by other means, such as an
   32    * annotation), and the order and validation for the properties determined from annotations on the property's getter and
   33    * setter methods.
   34    * <p/>
   35    * You may add &lt;t:parameter&gt;s to the component; when the name matches (case insensitive) the name of a property,
   36    * then the corresponding Block is renderered, rather than any of the built in property editor blocks. This allows you
   37    * to override specific properties with your own customized UI, for cases where the default UI is insufficient, or no
   38    * built-in editor type is appropriate.
   39    *
   40    * @see org.apache.tapestry5.beaneditor.BeanModel
   41    * @see org.apache.tapestry5.services.BeanModelSource
   42    * @see org.apache.tapestry5.corelib.components.PropertyEditor
   43    * @see org.apache.tapestry5.beaneditor.DataType
   44    */
   45   @SupportsInformalParameters
   46   public class BeanEditForm implements ClientElement, FormValidationControl
   47   {
   48       /**
   49        * The text label for the submit button of the form, by default "Create/Update".
   50        */
   51       @Parameter(value = "message:submit-label", defaultPrefix = BindingConstants.LITERAL)
   52       @Property
   53       private String submitLabel;
   54   
   55       /**
   56        * The object to be edited. This will be read when the component renders and updated when the form for the component
   57        * is submitted. Typically, the container will listen for a "prepare" event, in order to ensure that a non-null
   58        * value is ready to be read or updated. Often, the BeanEditForm can create the object as needed (assuming a public,
   59        * no arguments constructor).  The object property defaults to a property with the same name as the component id.
   60        */
   61       @Parameter(required = true, autoconnect = true)
   62       @Property
   63       private Object object;
   64   
   65       /**
   66        * A comma-separated list of property names to be retained from the {@link org.apache.tapestry5.beaneditor.BeanModel}.
   67        * Only these properties will be retained, and the properties will also be reordered. The names are
   68        * case-insensitive.
   69        */
   70       @SuppressWarnings("unused")
   71       @Parameter(defaultPrefix = BindingConstants.LITERAL)
   72       private String include;
   73   
   74       /**
   75        * A comma-separated list of property names to be added to the {@link org.apache.tapestry5.beaneditor.BeanModel}.
   76        */
   77       @Parameter(defaultPrefix = BindingConstants.LITERAL)
   78       private String add;
   79   
   80       /**
   81        * A comma-separated list of property names to be removed from the {@link org.apache.tapestry5.beaneditor.BeanModel}.
   82        * The names are case-insensitive.
   83        */
   84       @SuppressWarnings("unused")
   85       @Parameter(defaultPrefix = BindingConstants.LITERAL)
   86       private String exclude;
   87   
   88       /**
   89        * A comma-separated list of property names indicating the order in which the properties should be presented. The
   90        * names are case insensitive. Any properties not indicated in the list will be appended to the end of the display
   91        * order.
   92        */
   93       @SuppressWarnings("unused")
   94       @Parameter(defaultPrefix = BindingConstants.LITERAL)
   95       private String reorder;
   96   
   97       /**
   98        * May be bound, to override the Form's default for clientValidation.
   99        */
  100       @Parameter
  101       private boolean clientValidation;
  102   
  103       /**
  104        * Binding the zone parameter will cause the form submission to be handled as an Ajax request that updates the
  105        * indicated zone.  Often a BeanEditForm will update the same zone that contains it.
  106        */
  107       @Parameter(defaultPrefix = BindingConstants.LITERAL)
  108       private String zone;
  109   
  110       @Component(parameters = {"clientValidation=inherit:clientValidation",
  111               "validationId=componentResources.id",
  112               "zone=inherit:zone"})
  113       private Form form;
  114   
  115       /**
  116        * The model that identifies the parameters to be edited, their order, and every other aspect. If not specified, a
  117        * default bean model will be created from the type of the object bound to the object parameter.
  118        */
  119       @SuppressWarnings("unused")
  120       @Parameter
  121       @Property
  122       private BeanModel model;
  123   
  124       @Inject
  125       private ComponentResources resources;
  126   
  127       @Inject
  128       private BeanModelSource beanModelSource;
  129   
  130   
  131       void onPrepareFromForm()
  132       {
  133           resources.triggerEvent(EventConstants.PREPARE, null, null);
  134   
  135           if (model == null)
  136           {
  137               Class beanType = resources.getBoundType("object");
  138   
  139               model = beanModelSource.createEditModel(beanType, resources.getContainerMessages());
  140           }
  141   
  142           BeanModelUtils.modify(model, add, include, exclude, reorder);
  143       }
  144   
  145   
  146       /**
  147        * Returns the client id of the embedded form.
  148        */
  149       public String getClientId()
  150       {
  151           return form.getClientId();
  152       }
  153   
  154       public void clearErrors()
  155       {
  156           form.clearErrors();
  157       }
  158   
  159       public boolean getHasErrors()
  160       {
  161           return form.getHasErrors();
  162       }
  163   
  164       public boolean isValid()
  165       {
  166           return form.isValid();
  167       }
  168   
  169       public void recordError(Field field, String errorMessage)
  170       {
  171           form.recordError(field, errorMessage);
  172       }
  173   
  174       public void recordError(String errorMessage)
  175       {
  176           form.recordError(errorMessage);
  177       }
  178   }

Home » tapestry-src-5.0.19 » org.apache.tapestry5.corelib.components » [javadoc | source]