001    /**
002     * Copyright 2005-2013 The Kuali Foundation
003     *
004     * Licensed under the Educational Community License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     * http://www.opensource.org/licenses/ecl2.php
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.kuali.rice.krad.uif.component;
017    
018    import java.lang.annotation.Documented;
019    import java.lang.annotation.ElementType;
020    import java.lang.annotation.Retention;
021    import java.lang.annotation.RetentionPolicy;
022    import java.lang.annotation.Target;
023    
024    /**
025     * Annotation that can be used on <code>Component</code> properties to indicate the property
026     * value should be exposed in the client and populated back from the client
027     *
028     * <p>
029     * Some components have state that can be altered on the client without making a server call. An
030     * example of this is the open state for an <code>Disclosure</code>. When the View is refreshed
031     * from the server, the refreshed state needs to reflect the last state before the refresh was made. The
032     * framework supports this exposure of state in the client and syncing of the client state to the server
033     * component by means of this annotation.
034     *
035     * During the finalize phase, values for properties that contain this annotation will be pulled and added
036     * to the ViewState object that is exposed through JavaScript. The property name/value pair is associated
037     * with the component id on the ViewState object so that the state can be updated when the view is refreshed.
038     *
039     * Properties exposed client side can also be accessed and updated by custom script.
040     * e.g.
041     * var componentState = ViewState['componentId']; // or ViewState.componentId
042     * var propertyValue = componentState['propertyName'];
043     * </p>
044     *
045     * <p>
046     * The property will be exposed client side with the identifier given by {@link #variableName()}. If not specified,
047     * the name of the property for which the annotation applies will be used
048     * </p>
049     *
050     * @author Kuali Rice Team (rice.collab@kuali.org)
051     */
052    @Target({ElementType.FIELD})
053    @Retention(RetentionPolicy.RUNTIME)
054    @Documented
055    public @interface ClientSideState {
056    
057        /**
058         * Identifier to expose the client side variable as, can be left blank in which case
059         * the name of the property the annotation is associated with will be used
060         *
061         * @return String client side variable name
062         */
063        public String variableName() default "";
064    
065    }