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