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