14 Embed the Web User Interface

You can embed the Oracle Content and Experience web user interface into your own web applications in an HTML inline frame (iframe tag).

The embedded interface removes the default branding and resizes the content to fit the enclosing frame, allowing you to integrate Oracle Content and Experience into your own web applications.

The following topics describe how to embed the interface and use it to access digital assets, folders, and files in Oracle Content and Experience from your applications and to display content from other domains.

For content, you need to use application links (applinks) to access folders and files. An applink provides access to a folder or file for a user with a particular role for a period of time. You can use the applink on subsequent calls that access the associated folder or file without having to establish user credentials with each call. For more information, see Applinks Resource.

Note:

Before implementing an interface solution that uses inline frames, be sure you understand the possible security risks associated with hosting external sites in inline frames. Security measures vary between different browsers and different browser versions. For more information, see http://www.w3.org/TR/UISecurity/.

Embed the Web User Interface for Assets

Embed the web user interface for assets into your own web applications to get access to digital assets in an Oracle Content and Experience asset repository.

The next two figures show both versions of the user interface. The first figure shows the user's assets with an asset repository selected in the standard interface

The following figure shows an example of the same asset selection using the embedded interface, in the Assets View. Note that the banner and side panels are not displayed in the embedded user interface.

To embed the Oracle Content and Experience user interface for assets in an inline frame, add /embed immediately after the /assets element in the URL used to populate the inline frame. For example, the following URL calls the standard user interface for assets:

https://www.example.com/assets

Note:

The embedded user interface adjusts the content to fit within windows as small as 320 pixels wide. Windows smaller than 320 pixels begin to hide content on the right edge of the window.

You can specify configuration parameters on the URL that control some aspects of the browser display. For information about configuring the appearance of the embedded user interface, see Browser Configuration Parameters.

Embed the Web User Interface for Documents

Embed the web user interface for Oracle Content and Experience documents into your own web applications to get access to the folder and document management features of the service.

To embed the Oracle Content and Experience user interface for documents in an inline frame, add /embed to any member or public folder link immediately after the /documents element in the URL used to populate the inline frame. For example, the following URL calls the standard user interface for documents and shows the home folder for the current user:

https://www.example.com/documents/home/nameasc

To display the home folder in the embedded user interface, use the following form of the URL:

https://www.example.com/documents/embed/home/nameasc

To open a specified folder in the embedded interface, use the folder element in the URL and specify the globally unique identifier (GUID) of the folder. For example, the following link opens the specified folder in the embedded user interface.

https://www.example.com/documents/embed/folder/1713A5712BE73C37891915A0127B594F/nameasc 

Note:

The embedded user interface adjusts the content to fit within windows as small as 320 pixels wide. Windows smaller than 320 pixels begin to hide content on the right edge of the window.

You can also embed member links and public links to folders and specify configuration parameters on the URL that control some aspects of the browser display. For information about configuring the appearance of the embedded user interface, see Browser Configuration Parameters.

Authentication and SSO Environments

If you have signed in to the full web client in another tab, then the embedded web user interface will load without additional authentication, using the already established session in the browser.

If there is no existing browser session, then the behavior of the /embed URL is to present a sign in screen in a popup browser window. Once credentials are provided in the popup sign in window, the embedded client will reload without further authentication.

Note:

This behavior requires that any browser popup blockers are configured to allow the popup to display.

When the page hosting the embedded web user interface is within the same Oracle Access Manager Domain (Single Sign On), the /embedsegment of the URL should be replaced with /ssoembed. In ssoembed mode, the web user interface assumes that there is an existing SSO session established in the browser and no popup authentication is required. For example:

https://www.example.com/documents/ssoembed/home/nameasc

Real-Time Updates for Embedded Conversations

Using embedEnterHive enables real-time updates to a conversation from other users who may be posting in the conversation as well as presence indicators for users as displayed in the conversation header, such as Active or Idle.

Embedding a conversation view in the web user interface disables back-channel communication with the server by default. This means the view is a static display of the conversation at the time it was loaded, and the view will not display real-time updates. To get real-time updates, you must add the parameter embedEnterHive to the URL used to load the embedded view. For example:

https://www.example.com/documents/embed/conversation/12345?embedEnterHive

The embedEnterHive parameter can also be used to display a folder or file view that has a side-by-side conversation in the side bar, to get real-time updates on the conversation.

Using embedEnterHive is required in an embedded file view for annotations to function properly. For example:

https://www.example.com/documents/embed/fileview/fileid/_file.doc?embedEnterHive

The web user interface cannot accurately detect when the iframe containing it is destroyed. When the embedEnterHive parameter is used, the hosting code must signal to the web user interface in the iframe to close the service. This done through a postMessage call as follows:

iframewindow.postMessage({message: "closeService"}, *);

This ensures the client properly sends an "exit hive" call to the server, discontinuing back-channel communication.

Embed Documents Manager on a Site Page

You can embed documents manager on a site page to provide a view of your home page or files in Oracle Content and Experience.

See Documents in Creating Experiences with Oracle Content and Experience.

Security for Content in Other Domains

When you embed the Oracle Content and Experience web user interface, it’s enclosed in an inline frame. Security policies are enforced to minimize the security risks of hosting external sites in inline frames.

In general, inline frames can host content if the protocol, domain, and port of the inline frame are identical to those for the content it displays. For example, by default, an inline frame on the page http://www.example.com:12345/home.html can host content only if the content's protocol is also http, the domain is www.example.com and the port is 12345.

An administrator can explicitly identify domains outside of the host domain and allow content from those domains to display in the embedded web user interface.

Note:

Before implementing an interface integration that uses inline frames, be sure you understand the possible security risks associated with hosting external sites in inline frames. Security measures vary between different browsers and different browser versions. For more information, see http://www.w3.org/TR/UISecurity/.

Oracle Content and Experience displays content for authorized users in the embedded interface. Supported content includes folders, member links, and views of individual files.

All unsupported content, such as public links and content from unauthorized domains, opens in a new browser tab or window (depending on the browser settings).

Embed Content in Other Domains

You can display content from Oracle Content and Experience within other domains. For example, you might embed the Oracle Content and Experience web user interface into your own web applications to access folder and document management features inside your application.

To allow users to embed content, enable embedded content and add domains:

  1. After you sign in to the Oracle Content and Experience web application as an administrator, click Settings in the Administration area of the navigation menu.

  2. In the Settings menu, click Security.

  3. Under Embedded Content , select Enabled.

  4. In the Allowed domains box, enter a list of permitted domains, separated by commas. Domains must be in the form www.example.com.
    • To restrict the domain to a particular port, include the port in the specification. For example, www.example.com:12345.

    • If you want to allow a domain that has multiple sub-domains, you can use the * wildcard character. For example, www.example.* includes the domains www.example.com, www.example.co.uk, and so on.

Browser Configuration Parameters

You can include optional parameters in the URL for a folder or folder link to control some aspects of the browser display. This can be very useful for embedding the user interface in other applications.

Layout Configuration

You can append the layout configuration parameter (lyt) and a single value to the end of a URL for a folder or folder link using the following format:

{URL}/lyt={value}

For example, the following URL uses a member link to display the associated folder in the embedded interface with a grid layout:

https://www.example.com/documents/embed/folder/FDB8AC67BE3FCFB4984E1327T0000DEFAULT00000000/_Resources/lyt=grid

Note:

You can use the layout parameter with folders and folder links in both the standard and embedded interfaces.
Value Description

list

Displays the folder content in the standard list layout.

grid

Displays the folder content in the standard grid layout.

Embed Mode Configuration

You can specify an embed mode configuration as a URL query parameter:

  • hide: Hides elements that are visible by default when embedded.

  • show: Shows elements that are visible by default when embedded.

Options of the embed mode configuration apply only when you use embed mode URLs, including applink URLs. You can use the following embedded views:

  • Assets View (embed/assets)

  • Folder View (embed/folder/{folderId}) or (embed/folder/home)

  • File View (embed/fileview/{fileId})

  • Conversations List (embed/conversations)

  • Conversation View (embed/conversations/{conversationId})

  • Themes View (embed/themes)

For example:

/documents/embed/folder/{folderId}?hide=header+actions&show=branding&singlesel

In the Assets View, you can use the repository configuration parameter to preselect the Repository filter value:

https://www.example.com/embed/assets/repository/{repositoryID}

You can add individual options directly as parameters. Combine multiple hide and show options with either a plus sign (+) or comma (,). For example:

hide=header+breadcrumbs+sidebar

The following table lists the options you can use for embed mode configuration.

Parameter Value Description
autoplay   Auto play video and audio content
channel <channelId> Preselect the channel filter value. Must be valid for the initially loaded (preselected) repository.
channeloptions

<channelId>+

<channelId>+...

Limit the Channel filter control to the provided list
channeloptions none Hide the Channel filter control altogether
collapsetn   Start with thumbnails area collapsed
collection <collectionId> Preselect the collection filter value. Must be valid for the initially loaded (preselected) repository.
collectionoptions

<collectionId>+

<collectionId>+...

Limit the Collection filter control to the provided list. The list can contain collections from any repository in the repositoryOptions list. Control will display only collection validation for any selected repository. 
collectionoptions none Hide the Collection filter control altogether
contenttype article+blog+... Preselect the listed content type filters for the Assets View
contenttypeoptions none Hide the Content Items section in the Assets View
contenttypeoptions article+blog... Display the listed content type filters as available options
docsonly   Include only documents in list
fitoriginal   Start document at original size
fitpage   Start with document fit to page
fitwidth   Start with document fit to width
foldersonly   Include only folders in list
hide actions Hide all document actions
hide add Hide action Add in the Assets view header
hide breadcrumbs Hide breadcrumb area
hide collections Hide action Collections in the Assets view header
hide copy Hide action copy
hide delete Hide action delete
hide dnload Hide action download
hide favs Hide Favorite actions and View menu
hide fitpage Hide fit to page action in file view
hide fitwidth Hide fit to with action in File View
hide header Hide content header
hide move Hide action move
hide new Hide header create action (new folder)
hide nextprev Hide next and previous controls (File View)
hide pin Hide annotation mode pin
hide props Hide action props
hide rename Hide action rename
hide reserve Hide action reserve
hide share Hide action share
hide sidebar Hide sidebar
hide thumbs Hide viewer thumbnail area
hide toolbar Hide toolbar (Folder View)
hide trash Hide Trash View menu
hide upload Hide action upload
languageoptions en-US+fr-FR+... Limit the Language filter control to the provided list
languageoptions none Hide the Language filter control altogether
launch   Launch documents on view (opens new tab versus inline)
loop   Loop video and audio content
mute   Mute video and audio content
nofocus   Don’t take focus
noopen   Disable action open for folders in Folder View and conversations in conversation list (conversation list becomes multiselect)
novidctls   Hide video controls
noview   Disable action view for files in Folder View
repository <repositoryId> Preselect the Repository filter value in the Assets View
repositoryoptions

<repositoryId>+

<repositoryId>+...

Limit the Repository filter control to the provided list. Must include the repository parameter value, if provided.
show backbutton Add a back arrow
show branding Show branding header (hidden in embed mode)
simpleDisplay   Simplified select list
singlesel   Single select
status published+approved+rejected+draft+pending Preselect the lists status filters
statusoptions none Hide the Status panel altogether
statusoptions published+approved+rejected+draft+pending Display the listed status filters as available options
type images+video+documents Preselect the listed type filters for the Assets View
typeoptions images+video+documents Display the listed type filters as available options
typeoptions none Hide the Digital Assets Type section or Type panel in the Assets View
wide   Display wide content area

Browser Configuration

The embed mode configuration has replaced the legacy browser /cfg settings. Existing /cfg settings are supported in embed mode if no legacy query parameters are specified.

Embed Search Results

In an embedded web user interface for Oracle Content and Experience, search results are available through an embed URL.

For example, the embed URL format for displaying search results for document and folder types follows:

https://domain-name/documents/embed/search/search-string/documents?hide=titlemenu

The hide=titlemenu option parameter must be passed in the URL to hide the list filter drop-down menu. The search type cannot be filtered in an embed URL.

In an embed URL, you can use the same search string that you can use in a URL that is not embedded. For information about search strings, see Search Content and Conversations in Managing Content with Oracle Content and Experience.

You can use these search types in an embed URL:

  • documents

  • conversations

  • folder (scoped folder)

For example, the embed URL format for displaying search results within a scoped folder follows, sorted by last updateds:

https://domain-name/documents/search/search-string/folder/lastupdated/folder_guid?hide=titlemenu

You can use these sort-by types in an embed:

  • lastupdated

  • filesize

  • name

For example, the format for displaying search results for conversation types follows, sorted by last updated:

https://domain-name/documents/embed/search/search-string/conversations/lastupdated?hide=titlemenu

Embed Sites Content in Another Domain

You can embed an Oracle Content and Experience site or a site page into a page served from another domain.

To embed a site or site page into an iframe on an external site page that is served from another domain, set the Embeddable Site property to Yes on the site properties page.

See Embed Content in Other Domains in Administering Oracle Content and Experience.

Configure the File Picker with the SitesSDK.filePicker Method

You can use the SitesSDK.filePicker() method to pass configuration parameters in a URL for the embeddable File Picker user interface.

Browser Configuration Parameters in Embed the Web User Interface describes the configuration parameters you can pass.

You can specify a configuration parameter with either of two options:

  • Name-value pair

    		SitesSDK.filePicker({
    				<name>: <value-in-string>

    For example:

    		SitesSDK.filePicker({
    				statusoptions: 'published+draft',	
  • Name only

    		SitesSDK.filePicker({
    				<name>: <value-in-boolean>

    For example:

    		SitesSDK.filePicker({
    				autoplay: true,

Custom options are enabled in an asset URL or a document URL.

The following example uses the hello-there app:

        SitesSDK.filePicker({
                statusoptions: 'published+draft',
                autoplay: true,
                showReset: true,
                hide: 'sidebar',
                docsonly: true,
                singlesel: true,
                'multiSelect': false,
                'supportedFileExtensions': ['jpg', 'png']

This example would generate the following URL for the embedded File Picker:

http://localhost:8080/documents/embed/folder/home/nameasc?scheme=light&thinheader=true&layout=grid&docsonly&noview&wide&singlesel&statusoptions=published+draft&autoplay&hide=sidebar