001/*
002 * (C) Copyright 2007-2016 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 *     Nuxeo - initial API and implementation
018 */
019package org.nuxeo.ecm.platform.ui.web.api;
020
021import java.util.List;
022
023import org.nuxeo.ecm.core.api.DocumentModel;
024import org.nuxeo.ecm.platform.actions.Action;
025import org.nuxeo.ecm.platform.actions.ActionContext;
026import org.nuxeo.ecm.platform.actions.ejb.ActionManager;
027
028/**
029 * Component that handles actions retrieval as well as current tab(s) selection.
030 *
031 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
032 */
033public interface WebActions {
034
035    String NULL_TAB_ID = "";
036
037    /**
038     * The category of actions for default tabs
039     */
040    String DEFAULT_TABS_CATEGORY = "VIEW_ACTION_LIST";
041
042    /**
043     * The category of actions for main tabs
044     *
045     * @since 5.5
046     */
047    String MAIN_TABS_CATEGORY = "MAIN_TABS";
048
049    String SUBTAB_CATEGORY_SUFFIX = "_sub_tab";
050
051    /**
052     * Identifier of main tab for the "Documents management" area
053     *
054     * @since 5.5
055     */
056    String DOCUMENTS_MAIN_TAB_ID = "documents";
057
058    /**
059     * Request parameter used for tab ids settings
060     *
061     * @since 5.5
062     */
063    String TAB_IDS_PARAMETER = "tabIds";
064
065    /**
066     * Request parameter used for main tab id settings
067     *
068     * @since 5.5
069     */
070    String MAIN_TAB_ID_PARAMETER = "mainTabId";
071
072    /**
073     * Event raised when the current tab has changed, with 2 parameters: first parameter is a String representing the
074     * tab category, and second parameter is a String representing the new tab id (or null if current tab is reset for
075     * this category).
076     *
077     * @since 5.4.2
078     */
079    String CURRENT_TAB_CHANGED_EVENT = "currentTabChanged";
080
081    /**
082     * Event raised when the current tab is selected, with 2 parameters: first parameter is a String representing the
083     * tab category, and second parameter is a String representing the new tab id (or null if current tab is reset for
084     * this category).
085     * <p>
086     * This event is sent also when current tab did not change.
087     *
088     * @since 5.6
089     */
090    String CURRENT_TAB_SELECTED_EVENT = "currentTabSelected";
091
092    /**
093     * Framework property to control ajaxified behaviour of document tabs.
094     *
095     * @since 5.8
096     */
097    String AJAX_TAB_PROPERTY = "nuxeo.jsf.useAjaxTabs";
098
099    /**
100     * Return actions in given document context for given category.
101     *
102     * @param removeFiltered: if true, do not return filtered actions. Useful to display filtered actions as disabled
103     *            (by using using value false).
104     * @param postFilter: if true, do not filter actions. Actions will need to be filtered or disabled at render time.
105     *            Useful to filter actions when filtering context is available at render time only (for instance when
106     *            displaying actions in listings inside a JSF iteration done at render time).
107     * @since 8.2
108     */
109    List<Action> getDocumentActions(DocumentModel document, String category, boolean removeFiltered,
110            boolean postFilter);
111
112    /**
113     * Return action in given document context for given id.
114     * <p>
115     * Returns null if action is not found or filtered (depending on additional parameters).
116     *
117     * @param removeFiltered: if true, do not return filtered actions. Useful to display filtered actions as disabled
118     *            (by using using value false).
119     * @param postFilter: if true, do not filter actions. Actions will need to be filtered or disabled at render time.
120     *            Useful to filter actions when filtering context is available at render time only (for instance when
121     *            displaying actions in listings inside a JSF iteration done at render time).
122     * @since 8.2
123     */
124    Action getDocumentAction(DocumentModel document, String actionId, boolean includeFiltered, boolean postFilter);
125
126    /**
127     * Return actions in given action context for given category.
128     *
129     * @param removeFiltered: if true, do not return filtered actions. Useful to display filtered actions as disabled
130     *            (by using using value false).
131     * @param postFilter: if true, do not filter actions. Actions will need to be filtered or disabled at render time.
132     *            Useful to filter actions when filtering context is available at render time only (for instance when
133     *            displaying actions in listings inside a JSF iteration done at render time).
134     * @since 8.2
135     */
136    List<Action> getActions(ActionContext context, String category, boolean includeFiltered, boolean postFilter);
137
138    /**
139     * Return action in given action context for given id.
140     * <p>
141     * Returns null if action is not found or filtered (depending on additional parameters).
142     *
143     * @param removeFiltered: if true, do not return filtered actions. Useful to display filtered actions as disabled
144     *            (by using using value false).
145     * @param postFilter: if true, do not filter actions. Actions will need to be filtered or disabled at render time.
146     *            Useful to filter actions when filtering context is available at render time only (for instance when
147     *            displaying actions in listings inside a JSF iteration done at render time).
148     * @since 8.2
149     */
150    Action getAction(ActionContext context, String actionId, boolean includeFiltered, boolean postFilter);
151
152    /**
153     * Returns true if filters evaluation for given action, in given document context, grants access.
154     *
155     * @since 8.2
156     */
157    boolean isAvailableForDocument(DocumentModel document, Action action);
158
159    /**
160     * Returns true if filters evaluation for given action, in given action context, grants access.
161     *
162     * @since 8.2
163     */
164    boolean isAvailable(ActionContext context, Action action);
165
166    /**
167     * Returns all filtered actions for a given category and given resolution context.
168     * <p>
169     * Actions are filtered according to filters set on the actions definitions.
170     * <p>
171     * Since 5.8, the category can be a list of categories, separated by commas.
172     */
173    List<Action> getActionsList(String category, ActionContext context);
174
175    /**
176     * Returns all filtered actions for a given category and given resolution context, creating a new context for the
177     * filters resolution.
178     * <p>
179     * Actions are filtered according to filters set on the actions definitions.
180     * <p>
181     * Since 5.8, the category can be a list of categories, separated by commas.
182     *
183     * @since 5.7
184     */
185    List<Action> getActionsList(String category, Boolean removeFiltered);
186
187    /**
188     * Returns all filtered actions for a given category and a context built with given current document context,
189     * creating a new context for the filters resolution.
190     * <p>
191     * Actions are filtered according to filters set on the actions definitions.
192     * <p>
193     * Since 5.8, the category can be a list of categories, separated by commas.
194     *
195     * @since 5.7.3
196     */
197    List<Action> getActionsListForDocument(String category, DocumentModel document, boolean removeFiltered);
198
199    /**
200     * Returns all filtered actions for a given category and given resolution context.
201     * <p>
202     * Actions are filtered according to filters set on the actions definitions.
203     * <p>
204     * Since 5.8, the category can be a list of categories, separated by commas.
205     *
206     * @since 5.7
207     */
208    List<Action> getActionsList(String category, ActionContext context, boolean removeFiltered);
209
210    /**
211     * Returns all filtered actions for a given category, creating a new context for the filters resolution.
212     * <p>
213     * Since 5.8, the category can be a list of categories, separated by commas.
214     *
215     * @see #getActionsList(String, ActionContext)
216     */
217    List<Action> getActionsList(String category);
218
219    /**
220     * Returns all actions for a given category, without filtering.
221     */
222    List<Action> getAllActions(String category);
223
224    /**
225     * Returns filtered actions for the category {@link #DEFAULT_TABS_CATEGORY}
226     */
227    List<Action> getTabsList();
228
229    /**
230     * Returns filtered actions for a category computed from the current tab action id and the suffix
231     * {@link #SUBTAB_CATEGORY_SUFFIX}.
232     */
233    List<Action> getSubTabsList();
234
235    /**
236     * Returns the current action for category {@link #DEFAULT_TABS_CATEGORY}
237     */
238    Action getCurrentTabAction();
239
240    /**
241     * Sets the current action for category {@link #DEFAULT_TABS_CATEGORY}
242     */
243    void setCurrentTabAction(Action tabAction);
244
245    /**
246     * Returns the current sub tab for a category computed from the current tab action id and the suffix
247     * {@link #SUBTAB_CATEGORY_SUFFIX}.
248     */
249    Action getCurrentSubTabAction();
250
251    /**
252     * Sets the current sub tab for a category computed from the current tab action id and the suffix
253     * {@link #SUBTAB_CATEGORY_SUFFIX}.
254     */
255    void setCurrentSubTabAction(Action tabAction);
256
257    /**
258     * Returns the current action id for category {@link #DEFAULT_TABS_CATEGORY}
259     */
260    String getCurrentTabId();
261
262    /**
263     * Sets the current action id for category {@link #DEFAULT_TABS_CATEGORY}.
264     * <p>
265     * Does nothing if tabId is null, but resets current tab for this category when using an empty string instead.
266     */
267    void setCurrentTabId(String tabId);
268
269    /**
270     * Returns the current sub tab id for a category computed from the current tab action id and the suffix
271     * {@link #SUBTAB_CATEGORY_SUFFIX}.
272     */
273    String getCurrentSubTabId();
274
275    /**
276     * Sets the current sub tab id for a category computed from the current tab action id and the suffix
277     * {@link #SUBTAB_CATEGORY_SUFFIX}.
278     * <p>
279     * Does nothing if sub tab id is null, but resets current tab for this category when using an empty string instead.
280     */
281    void setCurrentSubTabId(String tabId);
282
283    /**
284     * Resets actions resolved for category {@link #DEFAULT_TABS_CATEGORY} so that they're recomputed. Also calls
285     * {@link #resetCurrentTab()}
286     */
287    void resetTabList();
288
289    /**
290     * Resets current tab information (includes sub tab information) for category {@link #DEFAULT_TABS_CATEGORY}.
291     */
292    void resetCurrentTab();
293
294    /**
295     * Returns the current action for given category.
296     */
297    Action getCurrentTabAction(String category);
298
299    /**
300     * Returns the current sub tab action for given parent action, computing the category from parent action id with
301     * suffix {@link #SUBTAB_CATEGORY_SUFFIX}.
302     */
303    Action getCurrentSubTabAction(String parentActionId);
304
305    /**
306     * Sets the current action for given category.
307     * <p>
308     * If given action is null, it resets the current action for this category.
309     */
310    void setCurrentTabAction(String category, Action tabAction);
311
312    /**
313     * Returns the current action id for given category
314     */
315    String getCurrentTabId(String category);
316
317    /**
318     * Indicates if the current tab id is set for given category
319     *
320     * @since 5.5
321     */
322    boolean hasCurrentTabId(String category);
323
324    /**
325     * Sets the current action for given category, with additional sub tabs.
326     */
327    void setCurrentTabId(String category, String tabId, String... subTabIds);
328
329    /**
330     * Returns current tab ids as a string, encoded as is: CATEGORY_1:ACTION_ID_1,CATEGORY_2:ACTION_ID_2,...
331     *
332     * @since 5.4.2
333     */
334    String getCurrentTabIds();
335
336    /**
337     * Sets current tab ids as a String, splitting on commas ',' and parsing each action information as is:
338     * CATEGORY:ACTION_ID[:OPTIONAL_SUB_ACTION_ID[:OPTIONAL_SUB_ACTION_ID]...]
339     * <p>
340     * If category is omitted or empty, the category {@link #DEFAULT_TABS_CATEGORY} will be used (if there is no subtab
341     * information).
342     * <p>
343     * The resulting string looks like: CATEGORY_1:ACTION_ID_1,CATEGORY_2:ACTION_ID_2_SUB_ACTION_ID_2,...
344     *
345     * @since 5.4.2
346     */
347    void setCurrentTabIds(String tabIds);
348
349    /**
350     * Resets all current tabs information.
351     *
352     * @since 5.4.2
353     */
354    void resetCurrentTabs();
355
356    /**
357     * Resets current tabs for given category, taking subtabs into account by resetting actions in categories computed
358     * from reset actions id with suffix {@link #SUBTAB_CATEGORY_SUFFIX}.
359     */
360    void resetCurrentTabs(String category);
361
362    /**
363     * Calls {@link #setCurrentTabAndNavigate(DocumentModel, String)} for the current document.
364     * <p>
365     * Given action should hold the category {@link #DEFAULT_TABS_CATEGORY}
366     *
367     * @see NavigationContext#getCurrentDocument()
368     */
369    String setCurrentTabAndNavigate(String currentTabActionId);
370
371    /**
372     * Navigate to the given document and opens the view page of the given document selecting the given tab.
373     * <p>
374     * Given action should hold the category {@link #DEFAULT_TABS_CATEGORY}
375     *
376     * @param document to document which will be shown in the view page
377     * @param currentTabActionId the tab that will be selected in the view page
378     * @return the JSF view for the given document.
379     */
380    String setCurrentTabAndNavigate(DocumentModel document, String currentTabActionId);
381
382    /**
383     * @since 5.6
384     * @see ActionManager#checkFilter(String, ActionContext)
385     */
386    boolean checkFilter(String filterId);
387
388    /**
389     * @since 5.7
390     * @see ActionManager#getAction(String, ActionContext, boolean)
391     */
392    Action getAction(String actionId, boolean removeFiltered);
393
394    /**
395     * Return action with given id, with context filled with given document.
396     *
397     * @since 5.7.3
398     * @see ActionManager#getAction(String, ActionContext, boolean)
399     */
400    Action getActionForDocument(String actionId, DocumentModel document, boolean removeFiltered);
401
402    /**
403     * @since 5.6
404     * @see ActionManager#getAction(String, ActionContext, boolean)
405     */
406    Action getAction(String actionId, ActionContext context, boolean removeFiltered);
407
408    /**
409     * Returns true if ajaxified behaviour of tabs is activated on the server, and if history push state is supported by
410     * browser.
411     *
412     * @since 5.8
413     * @see #AJAX_TAB_PROPERTY
414     * @see #canUseAjaxTabs()
415     */
416    boolean useAjaxTabs();
417
418    /**
419     * Returns true if history push state is supported by browser.
420     *
421     * @since 5.8
422     * @see #useAjaxTabs()
423     */
424    boolean canUseAjaxTabs();
425
426}