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