001/*
002 * (C) Copyright 2006-2007 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache 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.apache.org/licenses/LICENSE-2.0
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 * Contributors:
017 *     <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
018 *
019 * $Id: Layout.java 26053 2007-10-16 01:45:43Z atchertchian $
020 */
021
022package org.nuxeo.ecm.platform.forms.layout.api;
023
024import java.io.Serializable;
025import java.util.Map;
026
027/**
028 * Layout interface.
029 * <p>
030 * A layout is a group of {@link Widget} instances, built from a {@link LayoutDefinition} in a given mode.
031 *
032 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
033 */
034public interface Layout extends Serializable {
035
036    /**
037     * Returns the layout id, unique within the facelet context.
038     */
039    String getId();
040
041    /**
042     * Returns the unique identifier of this widget to be used in tag configuration.
043     * <p>
044     * In JSF, layouts are rendered dynamically and re-use the tag configuration of the tag rendering them when adding
045     * handlers to the facelet hierarchy. Since this tag identifier is used to perform some kind of caching on the JSF
046     * layer, it needs to change when the layout definition changes, so that JSF components are not mistaken for another
047     * one.
048     * <p>
049     * This identifier is unique to a given layout definition and always returns the same result given the same layout
050     * definition.
051     *
052     * @since 5.4.2
053     */
054    String getTagConfigId();
055
056    /**
057     * Sets the layout id, unique within the facelet context.
058     */
059    void setId(String id);
060
061    /**
062     * Returns the layout name used to identify it within the layout service.
063     */
064    String getName();
065
066    /**
067     * Returns the layout type.
068     *
069     * @since 6.0
070     */
071    String getType();
072
073    /**
074     * Returns the layout type category.
075     *
076     * @since 6.0
077     */
078    String getTypeCategory();
079
080    /**
081     * Returns the layout mode.
082     */
083    String getMode();
084
085    /**
086     * Returns the template used to render widgets.
087     */
088    String getTemplate();
089
090    /**
091     * Returns the table of widgets.
092     * <p>
093     * This list is computed from the {@link LayoutDefinition} rows.
094     * <p>
095     * Widgets that are not found are ignored.
096     */
097    LayoutRow[] getRows();
098
099    /**
100     * Returns the maximum number of columns.
101     */
102    int getColumns();
103
104    /**
105     * Returns widget with given name.
106     * <p>
107     * Only widgets of the first level are retrieved.
108     *
109     * @since 5.2M4
110     */
111    Widget getWidget(String name);
112
113    /**
114     * Returns a widget map, with widget name as key.
115     * <p>
116     * Only widgets of the first level are retrieved.
117     *
118     * @since 5.2M4
119     */
120    Map<String, Widget> getWidgetMap();
121
122    /**
123     * Get properties to use in this mode.
124     * <p>
125     * The way that properties will be mapped to rendered components is managed by the widget type.
126     *
127     * @since 5.3.1
128     */
129    Map<String, Serializable> getProperties();
130
131    /**
132     * Returns property with given name in this mode.
133     *
134     * @param name the property name.
135     * @return the property value or null if not found.
136     * @since 5.3.1
137     */
138    Serializable getProperty(String name);
139
140    /**
141     * Sets property with given name on the layout. If there is already a property with this name on the layout, it will
142     * be overridden.
143     *
144     * @param name the property name.
145     * @param value the property value or null if not found.
146     * @since 5.3.2
147     */
148    void setProperty(String name, Serializable value);
149
150    /**
151     * Gets the value name used to compute widget attributes.
152     *
153     * @since 5.7
154     */
155    String getValueName();
156
157    /**
158     * Sets the value name used to compute widget bindings.
159     *
160     * @since 5.7
161     */
162    void setValueName(String valueName);
163
164    /**
165     * Return true if this layout was generated from configuration on a service, and not generated on-the-fly using
166     * dynamic behaviors.
167     *
168     * @since 6.0
169     */
170    boolean isDynamic();
171
172    /**
173     * Returns the template to use for dev mode.
174     * <p>
175     * Is retrieved from layout definition templates, or from layout type templates, using the {@link BuiltinModes#DEV}.
176     *
177     * @since 6.0
178     */
179    String getDevTemplate();
180
181    /**
182     * Returns the definition from which this layout instance was generated.
183     * <p>
184     * Useful in dev mode to show the corresponding configuration in the UI.
185     *
186     * @since 6.0
187     */
188    LayoutDefinition getDefinition();
189
190}