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