public interface Action extends ModelObject
ModelObject
(more specifically Actionable
objects, which most interesting ModelObject
s are.)
Action
s added to a model object creates additional URL subspace under the parent model object,
through which it can interact with users. Action
s are also capable of exposing themselves
to the left hand side menu of a ModelObject
(for example to Project
, Build
, and etc.)
Some actions use the latter without the former (for example, to add a link to an external website),
while others do the former without the latter (for example, to just draw some graphs in floatingBox.jelly
),
and still some others do both.
If an action has a view named floatingBox.jelly
,
it will be displayed as a floating box on the top page of
the target ModelObject
. (For example, this is how
the JUnit test result trend shows up in the project top page.
See TestResultProjectAction
.)
On the target ModelObject
page, actions are rendered as an item in the side panel
by the "/lib/hudson:actions" jelly tag, but you can override this for your action by
writing action.jelly
. See the "actions" tag for what the default handling is and
tweak from there. One of the use cases of this is to show nested actions, like where
Jenkins show the option to wipe out the workspace inside the workspace link:
<l:task icon="icon-folder icon-md" href="${url}/ws/" title="${%Workspace}">
<l:task icon="icon-delete icon-md" href="${url}/wipeOutWorkspace" title="${%Wipe Out Workspace}" />
</l:task>
Actions are often persisted as a part of Actionable
(for example with Build
) via XStream. In some other cases,
Action
s are transient and not persisted (such as
when it's used with Job
).
The Actionable.replaceAction(Action)
, Actionable.addOrReplaceAction(Action)
, and
Actionable.removeAction(Action)
methods use Object.equals(java.lang.Object)
to determine whether to update
or replace or remove an Action
. As such, Action
subclasses that provide a deep
Object.equals(java.lang.Object)
will assist in reducing the need for unnecessary persistence.
Modifier and Type | Method and Description |
---|---|
String |
getDisplayName()
Gets the string to be displayed.
|
String |
getIconFileName()
Gets the file name of the icon.
|
String |
getUrlName()
Gets the URL path name.
|
@CheckForNull String getIconFileName()
/images/24x24
.
This is useful for using one of the stock images.
If an absolute file name that starts from '/' is returned (like "/plugin/foo/abc.gif'), then it will be interpreted as a path from the context root of Jenkins. This is useful to pick up image files from a plugin.
Finally, return null to hide it from the task list. This is normally not very useful,
but this can be used for actions that only contribute floatBox.jelly
and no task list item. The other case where this is useful is
to avoid showing links that require a privilege when the user is anonymous.
Functions.isAnonymous()
,
Functions.getIconFilePath(Action)
@CheckForNull String getDisplayName()
getDisplayName
in interface ModelObject
@CheckForNull String getUrlName()
For example, if this method returns "xyz", and if the parent object (that this action is associated with) is bound to /foo/bar/zot, then this action object will be exposed to /foo/bar/zot/xyz.
This method should return a string that's unique among other Action
s.
The returned string can be an absolute URL, like "http://www.sun.com/", which is useful for directly connecting to external systems.
If the returned string starts with '/', like '/foo', then it's assumed to be relative to the context path of the Jenkins webapp.
getIconFileName()
.Functions.getActionUrl(String, Action)
Copyright © 2004–2021. All rights reserved.