001/**
002 * Copyright 2005-2018 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 */
016package org.kuali.rice.krad.uif.layout;
017
018import org.kuali.rice.krad.uif.container.CollectionGroup;
019import org.kuali.rice.krad.uif.container.Group;
020import org.kuali.rice.krad.uif.container.collections.LineBuilderContext;
021import org.kuali.rice.krad.uif.field.Field;
022import org.kuali.rice.krad.uif.field.FieldGroup;
023import org.kuali.rice.krad.uif.element.Pager;
024
025/**
026 * Layout manager implementations that work with a collection (such as a table layout) should implement
027 * this interface for building the collection component instances.
028 *
029 * <p>Unlike other group instances, collection group instances need to generate new instances of the
030 * configured components for each line of the collection. The field instances for each line
031 * are wrapped differently depending on what layout manager is being applied. Therefore as the collection lines
032 * are being built (during the applyModel phase) this method will be invoked on the manager so that it may
033 * setup the line as needed.</p>
034 *
035 * @author Kuali Rice Team (rice.collab@kuali.org)
036 * @see org.kuali.rice.krad.uif.container.CollectionGroupBuilder
037 */
038public interface CollectionLayoutManager extends LayoutManager {
039
040    /**
041     * Call to the layout manager to build the components necessary for the given collection line,
042     * within an active view lifecycle.
043     *
044     * <p>As the collection is being iterated over by the {@link org.kuali.rice.krad.uif.container.CollectionGroupLineBuilder}
045     * this method is invoked for each line. The builder will create copies of the configured fields and actions for
046     * the line and pass into the layout manager so they can be assembled</p>
047     *
048     * @param lineBuilderContext context for the line to be built
049     */
050    void buildLine(LineBuilderContext lineBuilderContext);
051
052    /**
053     * Invoked when a paging request occurs to carry out the paging request.
054     *
055     * @param model object containing the view's data
056     * @param collectionGroup collection group the request was made for
057     */
058    void processPagingRequest(Object model, CollectionGroup collectionGroup);
059
060    /**
061     * Group for rendering the add line when separate (always the case for stacked layout, and a configuration
062     * for table layout).
063     *
064     * <p>This group can be used to configure how the add line will be rendered. For example the layout
065     * manager configured on the group will be used to rendered the add line fields. If the header
066     * (title) is not set on the group, it will be set from
067     * {@link org.kuali.rice.krad.uif.container.CollectionGroup#getAddLabel()}. In addition,
068     * {@link org.kuali.rice.krad.uif.container.CollectionGroup#getAddLineActions()} will be added
069     * to the group footer items.</p>
070     *
071     * @return Group instance for the collection add line
072     */
073    Group getAddLineGroup();
074
075    /**
076     * @see CollectionLayoutManager#getAddLineGroup()
077     */
078    void setAddLineGroup(Group addLineGroup);
079
080    /**
081     * Field group instance that is used as a prototype for creating the sub-collection field groups.
082     *
083     * @return GroupField instance to use as prototype
084     */
085    FieldGroup getSubCollectionFieldGroupPrototype();
086
087    /**
088     * @see CollectionLayoutManager#getSubCollectionFieldGroupPrototype()
089     */
090    void setSubCollectionFieldGroupPrototype(FieldGroup subCollectionFieldGroupPrototype);
091
092    /**
093     * Field instance that serves as a prototype for creating the select field on each line when
094     * {@link org.kuali.rice.krad.uif.container.CollectionGroup#isIncludeLineSelectionField()} is
095     * true.
096     *
097     * <p>This prototype can be used to set the control used for the select field (generally will be a
098     * checkbox control) in addition to styling and other setting. The binding path will be formed
099     * with using the
100     * {@link org.kuali.rice.krad.uif.container.CollectionGroup#getLineSelectPropertyName()} or if
101     * not set the framework will use
102     * {@link org.kuali.rice.krad.web.form.UifFormBase#getSelectedCollectionLines()}</p>
103     *
104     * @return select field prototype instance
105     */
106    Field getSelectFieldPrototype();
107
108    /**
109     * @see CollectionLayoutManager#getSelectFieldPrototype()
110     */
111    void setSelectFieldPrototype(Field selectFieldPrototype);
112
113    /**
114     * Widget used to page the collection.
115     *
116     * <p>The settings in this widget are only used by TableLayoutManagers which DO NOT take advantage
117     * of the RichTable option (this has its own paging implementation). To turn off RichTable and
118     * use a basic table with server paging set richTable.render="false" and useServerPaging="true"
119     * on the CollectionGroup which uses this layout manager.</p>
120     *
121     * @return the Pager widget
122     */
123    Pager getPagerWidget();
124
125    /**
126     * @see CollectionLayoutManager#getPagerWidget()
127     */
128    void setPagerWidget(Pager pagerWidget);
129}