- PortalRequest and Portal
- Retrieving Sites
- Creating a Site
- Deleting a Site
- Retrieving Navigation Nodes
- Creating a Navigation Node
- Deleting a Navigation Node
- Moving a Navigation Node
- OAuth Provider API
The Portal API provides access to retrieving, creating and deleting Portal Sites and Portal Pages. It also provides full support for the navigation and nodes associated with a site, which can be very useful for e.g. creating custom navigation portlets. This section only gives some basic examples of the API usage. For full documentation of all features available, please refer to the Javadoc.
The PortalRequest is the entry point to the API. It provides access to the Portal, and it also provides access to information associated with the current request (such as the logged in user and the page being requested).
The example below shows how to use the PortalRequest to obtain an instance of the Portal:
A Site is comprised of a set of pages, navigation definitions, and can be assigned a unique skin. There are three different types of sites: standard sites, group spaces and user dashboards.
A specific site can be retrieved by its SiteId. The SiteId is constructed by passing either the name for a standard site, the group for a group space or the user for a user dashboard. Alternatively it can be constructed by passing the SiteType and name.
Example of Retrieving Sites is Shown below:
It is also possible to query for sites using the SiteQuery. The SiteQuery supports filtering, sorting and pagination when querying for sites.
The example below finds standard sites that a user has access permissions to, limited to the 10 first results:
|The default number of results to return is 15. Which means that if no pagination is set while building the query, the maximum number of results will be 15. So be sure to set the correct pagination while querying.|
To create a site, first create a new site through the Portal, then set the configuration for the site (such as localized display names and skin), and finally saved it using the Portal.
The example below creates a new standard site with the name mysite and a non-localized display name:
The site is not visible (or persisted) until saveSite is invoked.
It is possible to change attributes for the site, supported attributes are:
- sessionAlive - sets if a session is kept alive or not. Valid values are "onDemand", "always", and "never" with the default being "onDemand"
- showPortletInfo - sets if the info bar is shown by default when adding applications to pages, the default is 'false'
The attributes are set by using the associated Key, the example below changes the sessionAlive attribute:
Associated with a site is an access permission and an edit permission, which controls what users and groups are allowed to access and edit the site respectively.
The example below makes a site accessible by everyone, but only editable by users in the /platform/administrators group:
The changed permissions do not take affect until saveSite is invoked.
A site is deleted by invoking removeSite on the Portal.
A Navigation for a site is retrieved from the Portal and allows accessing the node tree that represents the navigation entries for the site. There is a special root node which is not directly part of the navigation, but it's the parent of the first level of navigation entries. As the root node is not meant to be displayed it doesn't have a display name.
The example below retrieves the Navigation for the classic site:
When retrieving navigation nodes, it is possible to either retrieve the root node, or a specific node in the hierarchy. It is also possible to control which if any of the children are loaded.
This example below shows a very simple navigation portlet that displays the top level of entries in the navigation menu:
To retrieve a specific node in the tree it's retrieved by specifying the NodePath to the node:
|It is important to note that when you retrieve a node, it actually represents a tree of nodes and all operations (i.e. save, refresh) act on that entire tree. So if you retrieve the root node and it's children and make modifications to two children but only perform a save on one child, the other child will be saved since the save operation acts on the entire node tree.|
When retrieving navigation nodes, especially if there is a large number of nodes it is important to limit how many levels of nodes are retrieved. This is controlled by using either one of the built in NodeVisitor from the Nodes class, or by implementing your own NodeVisitor. The Nodes class contains the following visitors:
- visitAll - loads all nodes
- visitChildren - loads the immediate children
- visitNone - loads only the node
- visitNodes(int) - loads a specified depth of descendants
The example below retrieves the root node and 2 levels of nodes:
To find out if the children for a node is loaded use the isChildrenLoaded method. For example navigation.getRootNode(Nodes.visitChildren()).isChildrenLoaded() returns true while navigation.getRootNode(Nodes.visitNone()).isChildrenLoaded() returns false.
Nodes support a filtering mechanism which makes it simple to display only nodes that have certain properties. For example when creating a navigation portlet it is common to only want to display visible nodes where the user has access to view the page:
There is a number of methods available to control what nodes are displayed, and they all start with show. showDefault is a short-cut for showVisible().showHasAccess(PortalRequest.getInstance().getUser()).
It is also possible to add a custom filter. The example below displays uses a custom filter to only nodes with a display name that starts with "A":
To create a node, first retrieve the parent node you want to add it to, and invoke the addChild method on the parent node. Then set the configuration for the node (such as the display name and the page it should link to) and finally save it using saveNode on Navigation.
The example below creates a node as a child of the home node:
The node is not visible (or persisted) until saveNode is invoked.
Nodes can be visible, hidden or only visible at a specified publication date. By default a new node is visible.
A node can be hidden with node.setVisibility(false), or only shown until a specific date with node.setVisibility(PublicationDate.endingOn(date)) (it is also possible to set a starting date, or both). The changes to the node visiblity is not shown until saveNode is invoked on the Portal.
The display name for a node supports localization. The example below sets the display name for a node in English and French:
A node is deleted by removing it from the parent node. The example below removes the child with the name mynode:
The node is not removed until saveNode is invoked.
A node can be moved to a different parent, or it can be moved to a different index in the same parent. When moving to a different parent the new parent is required to be in the same tree.
The example belows moves a node from one parent to another:
Or to move a node to a different index in the same parent:
A more convinient way to sort children for a parent is to use the sort method on the parent, for example to sort the children of the root node by their display names:
As with creating a node, the changes are not visible (or persisted) until saveNode is invoked.
Portal Page aggregates content from one or more Portlets - see Portlet Primer.
A specific page can be retrieved by its PageId. The PageId is constructed by passing either the name for a standard site, the group for a group space or the user for a user dashboard, and the name of the page. Alternatively it can be constructed by passing the SiteId and name of the page.
Example of retrieving specific pages is shown below:
It is also possible to query for pages using the PageQuery. The PageQuery supports filtering, sorting and pagination when querying for pages.
The example below finds pages with a display name that starts with "A":
To create a page, first create a new page through the Portal, then set the configuration for the page (such as localized display names), and finally saved it using the Portal.
The example below creates a new page in the classic site with the name mypage and a non-localized display name:
The page is not visible (or persisted) until portal.savePage is invoked.
Associated with a page is an access permission and an edit permission, which controls what users and groups are allowed to access and edit the page respectively.
The example below makes a page accessible to everyone, but only editable by users in the /platform/administrators group:
The changed permissions do not take affect until savePage is invoked.
A page is deleted by invoking removePage on the Portal.
The interface OAuthProvider is a part of our public API. It is the entry point to perform operations on OAuth providers (social networks).
Please refer to OAuth section for details about the configuration of GateIn Portal which is necessare to use OAuth providers (Facebook, Google, Twitter) for authentication of users. Once a user is logged in (or his account is linked with OAuth provider), his access token is saved in GateIn Portal IDM database as a part of his User Profile. Then it is possible to retrieve his OAuth access token via OAuthProvider interface and run its operations. It is also possible to revoke or validate existing access tokens or send request to obtain new access tokens with more scopes (privileges).
|Except for the next two sections, where we present some basic use of the the OAuthProvider API, there is also a standalone code example called Social Portlets Quickstart in our Quickstarts Collection.|
First, you need to retrieve the appropriate instance of OAuthProvider from Portal:
Currently GateIn Portal supports three OAuth providers:
- OAuthProvider.FACEBOOK for Facebook
- OAuthProvider.GOOGLE for Google+
- OAuthProvider.TWITTER for Twitter
The following snippet shows some basic use of OAuthProvider API:
Method oauthProvider.getAuthorizedSocialApiObject() is useful for obtaining access to provider-specific operations. This method usually returns objects from a 3rd party library. Those objects are always initialized with access token of the current user and can be used to retrieve data from the related social network.
- Google - there are two supported types usable as arguments of this method:
- com.google.api.services.plus.Plus - Google Plus API class, which can be used to call operations on Google Plus - see GoogleActivitiesPortlet and GoogleFriendsPortlet in our Social Portlets Quickstart.
- com.google.api.services.oauth2.Oauth2 - Oauth2 class, which provides operations related to user, such as obtaining his Google user profile details or obtaining information about his access token - see GoogleUserInfoPortlet in our Social Portlets Quickstart.
- Twitter - there is only one supported type for Twitter: twitter4j.Twitter. An instance of this class can be used e.g. to retrieve user details, number of his tweets, number of his friends, his last tweets, etc. - see TwitterPortlet in our Social Portlets Quickstart.