001/*
002 * (C) Copyright 2010 Nuxeo SA (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 *     Anahide Tchertchian
016 */
017package org.nuxeo.ecm.platform.contentview.jsf;
018
019import java.io.Serializable;
020import java.util.List;
021
022import javax.faces.context.FacesContext;
023
024import org.nuxeo.ecm.core.api.DocumentModel;
025import org.nuxeo.ecm.core.api.SortInfo;
026import org.nuxeo.ecm.platform.query.api.PageProvider;
027
028/**
029 * A content view is a notion to handle lists of objects rendering, as well as query filters to build the list.
030 * <p>
031 * It has a name that will be the resulting page provider name too. It handles a page provider and accepts configuration
032 * needed to handle rendering, like the search layout (for filtering options), the result layout (for results
033 * rendering), actions (for buttons available when selecting result objects), the selection list name...
034 * <p>
035 * It also handles refresh or reset of its provider, depending on its cache key and refresh events configuration.
036 *
037 * @author Anahide Tchertchian
038 * @since 5.4
039 */
040public interface ContentView extends Serializable {
041
042    public static final String SEARCH_DOCUMENT_EL_VARIABLE = "searchDocument";
043
044    /**
045     * Seam event to be fired when the current page of the content view's page provider has changed
046     *
047     * @since 5.7
048     */
049    public static final String CONTENT_VIEW_PAGE_CHANGED_EVENT = "contentViewPageChanged";
050
051    /**
052     * Seam event to be fired when the content view's page provider has refreshed
053     *
054     * @since 5.7
055     */
056    public static final String CONTENT_VIEW_REFRESH_EVENT = "contentViewRefresh";
057
058    /**
059     * Seam event to be fired when the page size of the content view has changed
060     *
061     * @since 5.7
062     */
063    public static final String CONTENT_VIEW_PAGE_SIZE_CHANGED_EVENT = "contentViewPageSizeChanged";
064
065    /**
066     * Returns the name of this content view
067     */
068    String getName();
069
070    /**
071     * Returns a title for this content view
072     */
073    String getTitle();
074
075    /**
076     * Returns a boolean stating if title has to be translated
077     *
078     * @see #getTitle()
079     */
080    boolean getTranslateTitle();
081
082    /**
083     * Returns true is the title should be displayed before the result layout selector.
084     *
085     * @since 5.4.2
086     */
087    boolean getShowTitle();
088
089    /**
090     * Returns the selection list name
091     */
092    String getSelectionListName();
093
094    /**
095     * Returns the pagination type to be used in pagination rendering
096     */
097    String getPagination();
098
099    /**
100     * Returns the list of action categories to display buttons available on selection of items.
101     */
102    List<String> getActionsCategories();
103
104    /**
105     * Returns the list of flags set on this content view, useful to group them, see
106     * {@link ContentViewService#getContentViewNames(String)}
107     */
108    List<String> getFlags();
109
110    /**
111     * Returns the search layout, used to filter results.
112     */
113    ContentViewLayout getSearchLayout();
114
115    /**
116     * Returns the result layouts, used to display results.
117     */
118    List<ContentViewLayout> getResultLayouts();
119
120    /**
121     * Returns the current result layout, as set using {@link #setCurrentResultLayout(ContentViewLayout)}, or the first
122     * of defined result layouts when not set.
123     */
124    ContentViewLayout getCurrentResultLayout();
125
126    /**
127     * Sets the current result layout.
128     */
129    void setCurrentResultLayout(ContentViewLayout layout);
130
131    /**
132     * Sets the current result layout given its name.
133     *
134     * @since 5.7
135     */
136    void setCurrentResultLayout(String resultLayoutName);
137
138    /**
139     * @since 6.0
140     */
141    boolean hasResultLayoutBinding();
142
143    /**
144     * Returns the current page size, as set using {@link #setCurrentPageSize(Long)}, or the page size set on current
145     * page provider if not null.
146     */
147    Long getCurrentPageSize();
148
149    /**
150     * Sets the current page size.
151     */
152    void setCurrentPageSize(Long pageSize);
153
154    /**
155     * @deprecated use {@link #getCurrentResultLayoutColumns()} instead
156     */
157    @Deprecated
158    List<String> getResultLayoutColumns();
159
160    /**
161     * Returns the list of selected result layout columns, resolving the bound EL expression set in the content view
162     * definition if columns where not explicitely set with {@link #setCurrentResultLayoutColumns(List)}.
163     *
164     * @since 5.4.2
165     */
166    List<String> getCurrentResultLayoutColumns();
167
168    /**
169     * Sets the list of result layout columns.
170     *
171     * @since 5.4.2
172     */
173    void setCurrentResultLayoutColumns(List<String> resultColumns);
174
175    /**
176     * @since 6.0
177     */
178    boolean hasResultLayoutColumnsBinding();
179
180    /**
181     * Returns the cache key for this content view provider, resolving from the current {@link FacesContext} instance if
182     * it's an EL expression.
183     */
184    String getCacheKey();
185
186    /**
187     * Returns the cache size for this content view.
188     */
189    Integer getCacheSize();
190
191    /**
192     * Returns the icon relative path for this content view.
193     */
194    String getIconPath();
195
196    /**
197     * Returns the query parameters for this content view provider provider, resolving from the current
198     * {@link FacesContext} instance if they are EL expressions.
199     */
200    Object[] getQueryParameters();
201
202    /**
203     * Returns the list of event names that should trigger a refresh of this content view page provider.
204     */
205    List<String> getRefreshEventNames();
206
207    /**
208     * Returns the list of event names that should trigger a reset of this content view page provider.
209     */
210    List<String> getResetEventNames();
211
212    /**
213     * Gets page provider according to given parameters
214     *
215     * @param searchDocument document that will be set on the page provider. If this document is null, we try to
216     *            retrieve the content view document model calling {@link #getSearchDocumentModel()}. If it is not null,
217     *            it is set on the page provider.
218     * @param sortInfos if not null, will override default sort info put in the page provider XML description
219     * @param pageSize if not null, will override default page size put in the page provider XML description
220     * @param currentPage if not null, will set the current page to given one
221     * @param params if not null, will set the parameters on provider. If null, will take parameters as resolved on the
222     *            content view from the XML configuration, see {@link #getQueryParameters()}
223     */
224    PageProvider<?> getPageProvider(DocumentModel searchDocument, List<SortInfo> sortInfos, Long pageSize,
225            Long currentPage, Object... params);
226
227    /**
228     * Gets page provider according to given parameters
229     *
230     * @see #getPageProvider(DocumentModel, List, Long, Long, Object...) using null as every argument except params
231     */
232    PageProvider<?> getPageProviderWithParams(Object... params);
233
234    /**
235     * Gets page provider according to given parameters
236     *
237     * @see #getPageProvider(DocumentModel, List, Long, Long, Object...) , using null as every argument
238     */
239    PageProvider<?> getPageProvider();
240
241    /**
242     * Returns the current page provider, or null if methods {@link #getPageProvider()},
243     * {@link #getPageProvider(DocumentModel, List, Long, Long, Object...)} or
244     * {@link #getPageProviderWithParams(Object...)} were never called before.
245     */
246    PageProvider<?> getCurrentPageProvider();
247
248    /**
249     * Resets the page provider.
250     * <p>
251     * A new page provider will be computed next time {@link #getPageProviderWithParams(Object...)} is called. Sort
252     * information and query parameters will have to be re-generated.
253     */
254    void resetPageProvider();
255
256    /**
257     * Refreshes the current page provider if not null, see {@link PageProvider#refresh()}.
258     * <p>
259     * Sort information and query parameters and current page are kept.
260     */
261    void refreshPageProvider();
262
263    /**
264     * Refreshes the current page provider if not null, see {@link PageProvider#refresh()}, and resets the current page
265     * to the first one.
266     * <p>
267     * Sort information and query parameters are kept.
268     */
269    void refreshAndRewindPageProvider();
270
271    /**
272     * Reset the page provider aggregates.
273     *
274     * @since 6.0
275     */
276    void resetPageProviderAggregates();
277
278    /**
279     * Returns true is this content view can use the global page size set on the application.
280     */
281    boolean getUseGlobalPageSize();
282
283    /**
284     * Returns true is the page size selector should be displayed.
285     *
286     * @since 5.4.2
287     */
288    boolean getShowPageSizeSelector();
289
290    /**
291     * Returns true is the refresh command should be displayed.
292     *
293     * @since 5.4.2
294     */
295    boolean getShowRefreshCommand();
296
297    /**
298     * Returns true is the filter form should be displayed.
299     * <p>
300     * Filter form is displayed on top of content view results, using the search document model and search layout if
301     * they have been set on the content view.
302     *
303     * @since 5.4.2
304     */
305    public boolean getShowFilterForm();
306
307    /**
308     * Returns the search document model as set on the content view.
309     * <p>
310     * If this document is null and a EL binding has been set on the content view description, the document model will
311     * be resolved from this binding, and set as the search document model.
312     * <p>
313     * Else, if the content view is using a provider that needs a search document model, a new one is created and
314     * attached to it thanks to the document type held in the definition.
315     */
316    DocumentModel getSearchDocumentModel();
317
318    /**
319     * Sets the search document model to be passed on the page provider, and set it also on the current page provider if
320     * not null.
321     */
322    void setSearchDocumentModel(DocumentModel doc);
323
324    /**
325     * Resets the search document model, setting it to null so that it's recomputed when calling
326     * {@link #getSearchDocumentModel()}
327     */
328    void resetSearchDocumentModel();
329
330    /**
331     * Returns the search document model type as defined in the XML configuration.
332     */
333    String getSearchDocumentModelType();
334
335    /**
336     * Returns a sentence to display when this content view is empty
337     *
338     * @since 5.4.2
339     */
340    String getEmptySentence();
341
342    /**
343     * Returns a boolean stating if sentence to display is empty has to be translated
344     *
345     * @see #getEmptySentence()
346     * @since 5.4.2
347     */
348    boolean getTranslateEmptySentence();
349
350    /**
351     * Returns the sentence to display when content view is waiting for a first execution.
352     *
353     * @since 7.4
354     */
355    String getWaitForExecutionSentence();
356
357    /**
358     * Returns true if content view will not display results until an explicit search is executed.
359     *
360     * @see ContentView#isExecuted()
361     * @since 7.4
362     */
363    boolean isWaitForExecution();
364
365    /**
366     * Returns true if content view has been executed.
367     * <p>
368     * Execution is detected when either {@link #refreshPageProvider()} or {@link #refreshAndRewindPageProvider()}
369     * methods are called, or when {@link #setExecuted(boolean)} is called explicitely.
370     *
371     * @since 7.4
372     */
373    public boolean isExecuted();
374
375    /**
376     * Sets the content view execution status.
377     *
378     * @since 7.4
379     */
380    public void setExecuted(boolean executed);
381
382}