23 Integrating the Tags Service

23.1.1 Understanding the Tags Service

You can apply one or more meaningful terms, called tags, to remind yourself and alert other users of the content they might expect to find at the tagged location. Anywhere you see the Tags icon (Figure 23-1), you can apply a tag.

Figure 23-1 The Tags Icon

Description of "Figure 23-1 The Tags Icon"

Tags let you apply your own classifications to items. For example, you could apply the tag phone to a product page that provides useful information about new phones. When you or other users search for phone, the tagged page displays in the search results.

When you access the Tag Center, you see all users who applied the same tag anywhere else in the application. Within the Tag Center, a tag cloud (Figure 23-2) displays all currently applied tags.

Figure 23-2 A Tag Cloud

Description of "Figure 23-2 A Tag Cloud"

A tag cloud is a visual depiction of all tags. Tags are presented according to the frequency of their use—the larger the font, the more the tag has been applied to items. Click a tag in the tag cloud to run a search that returns a list of all items that use the tag.

23.1.2 Requirements for the Tags Service

The Tags service requires that you set up the WebCenter schema and create a database connection to the schema. Tag information is stored in the database. For details, see Section 23.2.1, "Setting up Connections for the Tags Service."

There are no additional requirements to use the Tags service. However, to enable the ability to tag pages, you must manually add the Page service libraries to your project. Right-click your ViewController project and select Project Properties and then Libraries and Classpath. Click Add Library and select the WebCenter Page Service and WebCenter Page Service View libraries, as shown in Figure 23-3. Click OK.

Figure 23-3 Page Service Libraries

Description of "Figure 23-3 Page Service Libraries"

Similarly, to enable the ability to tag documents, you must manually add the Document Library service libraries to your project, as shown in Figure 23-4.

Figure 23-4 Documents Service Libraries

Description of "Figure 23-4 Documents Service Libraries"

23.1.3 What Happens at Runtime

At runtime, you can tag custom components, find those tags either through a search or in the Tag Center, and access tagged items through their associated tags. By default, tagged items that are accessed through their tags are rendered in a popup window, but you can override this by specifying other types of open behavior.

For more information about the service at runtime, see Oracle Fusion Middleware User's Guide for Oracle WebCenter.

23.2.1 Setting up Connections for the Tags Service

The Tags service requires a connection to the database with the WebCenter schema installed. The script to create the WebCenter schema is included with the product.

For details about installing the database and the WebCenter schema, see Oracle Fusion Middleware Installation Guide for Oracle WebCenter.

23.2.2 Adding the Tags Service at Design Time

To enable basic tagging, you must add either the Tagging Button component or the Tagging Menu Item component and the Tagging - Dialog task flow. In addition, to tag custom objects, you must register a resource viewer to visualize the tagged component when it is discovered by users.

This section describes how to enable tagging by adding the Tagging Button and the Tagging - Dialog task flow.

<af:form id="f1">
        <af:region value="#{bindings.searchtoolbar1.regionModel}" id="r1"/>
        <tag:taggingButton resourceId="#{facesContext.viewRoot.viewId}"
                           serviceId="oracle.webcenter.page"
                           resourceName="#{facesContext.veiwRoot.viewId}"
                           id="tb1"/>
        <af:region value="#{bindings.tagginglaunchdialog1.regionModel}"
                   id="r2"/>
      </af:form>

23.2.3 Setting Security for the Tags Service

The Tags service does not require ADF security.

However, the Tagging - Personal View and Tagging - Dialog task flows do require authentication. Also, if the application is not secured, then pages are not returned in search results for tagged items.

When users are not authenticated, the user name associated with tags in the user's bookmarks are "anonymous." Multiple users using the same unprotected custom WebCenter applications risk overwriting each other's tags.

For information about configuring ADF security, see Section 3.5, "Implementing Security in Your Application."

23.3.1 Optional Way to Show Tags on Pages

While it is possible to add the Tagging Button and task flows on a page-by-page basis, typically you want to add the search toolbar and tags as part of a page template that you can apply whenever building a page that requires it. To add tags through a page template:

1. Open the project where you plan to create pages with the Tags service.

2. Right-click the project name and select New from the context menu.

3. Under Categories, select JSF and, under Items, select JSF Page Template.

4. For File Name, enter looksee1template.

   Figure 23-10 Create JSF Page Template Dialog

   
   Description of "Figure 23-10 Create JSF Page Template Dialog"
   
   

5. Click OK.

6. Go to the Source view and modify the code to be similar to that in Example 23-2.

   Example 23-2 Sample JSF Page Template

   <af:pageTemplateDef var="attrs">
     <af:xmlContent>
       <component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
         <display-name>looksee1template1</display-name>
         <facet>
           <facet-name>content</facet-name>
         </facet>
       </component>
     </af:xmlContent>
     <af:panelGroupLayout layout="vertical">
       <!-- Our toolbar -->
       <af:panelGroupLayout id="toolbar" layout="horizontal" halign="end"
                            inlineStyle="background-color:cyan;width:100%">
       </af:panelGroupLayout>
       <af:panelStretchLayout startWidth="300"
                              inlineStyle="height:600px; width:100%;">
         <f:facet name="start">
           <af:panelSplitter id="sidebar" orientation="vertical">
             <f:facet name="first">
               </f:facet>
             <f:facet name="second">
             </f:facet>
           </af:panelSplitter>
         </f:facet>
         <f:facet name="center">
           <af:facetRef facetName="content"/>
         </f:facet>
       </af:panelStretchLayout>
     </af:panelGroupLayout>
   </af:pageTemplateDef>
   

7. On the Component Palette, select the Tagging Button and drop it on the page, inside the PanelGroupLayout. Make it the first child of the PanelGroupLayout.

8. Fill out the Insert Tagging Button dialog as shown in Figure 23-11.

   Table 23-3 provides descriptions and example values for the fields in the dialog.

   Table 23-3 Fields in the Insert Tagging Button Dialog for a Page

   Field	Description
   ResourceId	Unique identifier of your page. In this case, because the resource ID is meant for a page, enter #{facesContext.viewRoot.viewId}.
   ResourceName	Name of the page. In this case, enter #{facesContext.viewRoot.viewId}. (You can enter a more user-friendly name.)
   ServiceId	Service identifier that you add to service-definition.xml when adding the resource viewer. In this case, enter oracle.webcenter.page. Note: Because oracle.webcenter.page is available in the Page service library, nothing must be added to service-definition.xml.

   
   

   Figure 23-11 Insert Tagging Button Dialog for a Page

   
   Description of "Figure 23-11 Insert Tagging Button Dialog for a Page"
   
   

9. Click OK.

10. From the Resource Palette, expand the WebCenter Services Catalog and the Task Flows.

11. Drag Tagging Dialog from the Resource Palette and drop it on the page inside of the panelGroupLayout.

12. When prompted, select Region as the way to create the task flow.

13. Drag Search Toolbar and drop it after the Tagging Dialog you just added to the page template in the panelGroupLayout.

14. When prompted, select Region as the way to create the task flow.

15. Drag Document Library - Recent Documents and drop it in the second facet of the panelSplitter with identifier sidebar.

16. When prompted, select Region as the way to create the task flow.

17. In the Edit Task Flow Binding dialog, for connectionName, enter the name of the connection to your document library's content repository; for example, ${'MyFileSystem'}. For information on how to set up a connection to your content repository, see Section 13.2, "Configuring Content Repository Connections."

18. The source for your page template should now look similar to Example 23-3.

    Example 23-3 JSF Page Template with Tagging and Search

    <af:pageTemplateDef var="attrs">
      <af:xmlContent>
        <component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
          <display-name>looksee1template1</display-name>
          <facet>
           <facet-name>content</facet-name>
          </facet>
        </component>
      </af:xmlContent>
      <af:panelGroupLayout layout="vertical">
       <!-- Our toolbar -->
       <af:panelGroupLayout id="top" layout="horizontal" halign="end"
                   inlineStyle="background-color:cyan;width:100%">
        <tag:taggingButton resourceId="#{facesContext.viewRoot.viewId}"
                         resourceName="#{facesContext.viewRoot.viewId}"
                            serviceId="oracle.webcenter.page"/>
         <af:region value="#{bindings.tagginglaunchdialog1.regionModel}"
                    id="tagginglaunchdialog1"/>
         <af:region value="#{bindings.searchtoolbar1.regionModel}"
                    id="searchtoolbar1"/>
       </af:panelGroupLayout>
        <af:panelStretchLayout startWidth="300"
                              inlineStyle="height:600px; width:100%;">
         <f:facet name="start">
         <af:panelSplitter orientation="vertical">
          <f:facet name="first">
           <af:region value="#{bindings.taskservicetaskflowdefinition1.regionModel}"
                      id="taskservicetaskflowdefinition1"
                      inlineStyle="position:absolute; left:0px; width:100%;
                       height:100%"/>
          </f:facet>
          <f:facet name="second">
           <af:region value="#{bindings.doclibrecentdocuments1.regionModel}"
                      id="doclibrecentdocuments1"/>
          </f:facet>
           </af:panelSplitter>
          </f:facet>
          <f:facet name="center">
           <af:facetRef facetName="content"/>
          </f:facet>
        </af:panelStretchLayout>
       </af:panelGroupLayout>
      </af:pageTemplateDef>
    

19. Create two new pages based upon the page template you just created. In the Create JSF Page dialog, select looksee1template1 from the Use Page Template list.

    • Create a page called Search.jspx and add the Search task flow in the center facet.

    • Create a page called Documents.jspx and add the Document Library - List View task flow as the center facet. In the Edit Task Flow Binding dialog, for connectionName, enter the name of the connection to your document library's content repository; for example, ${'MyFileSystem'}. For information on how to set up a connection to your content repository, see Section 13.2, "Configuring Content Repository Connections."

20. Save your pages.

To run your pages with tags:

1. In the Applications Navigator, run the Search.jspx page.

2. After you log in and the page comes up, click the Tags link.

3. In the Tag this Page dialog, enter search page test customapp for Tags (Figure 23-12).

   Figure 23-12 Tag this Page Dialog for Search Page

   
   Description of "Figure 23-12 Tag this Page Dialog for Search Page"
   
   

4. Click Save.

5. Navigate to Documents.jspx (or run it separately).

6. Click the Tags link.

7. In the Tag this Page dialog, enter doclib documents page test customapp for Tags (Figure 23-13).

   Figure 23-13 Tag this Page Dialog for Documents Page

   
   Description of "Figure 23-13 Tag this Page Dialog for Documents Page"
   
   

8. Click Save.

9. In the search toolbar for the Documents.jspx page, enter search and click the Search icon.

10. Under Tags, click search.

23.3.2 Using the Resource Action Handling Framework to Tag Custom Objects

For WebCenter services exposing resources to be tagged (and therefore searched and viewed) WebCenter provides a Resource Action Handling framework. For example, rows in a table can be tagged.

To register a resource viewer, see Section 4.2, "Extending Your Application with Custom Components."

23.3.3 Using Tagged Cloud and Tagged Items Together

Using the events mechanism, you should wire together the Tagging - Tag Cloud and Tagging - Tagged Items task flows to show tagged items only for the selected tags in the tag cloud. This avoids tagged items displaying all items that have been tagged by all users, improving performance.

After adding the Tagging - Tag Cloud and Tagging - Tagged Items task flows to a page, there are two ways to wire them together.

The first, and easiest, way is to cut and paste the following snippet to the page definition, and then replace the region name relatedresources1 with the task flow name used in your page definition.

<eventMap xmlns="http://xmlns.oracle.com/adfm/contextualEvent">
    <event name="refreshAllRelated">
      <producer region="*">
        <consumer region="relatedresources1"
                  handler="oracle_webcenter_tagging_view_jsf_fragments_tag_center_related_resourcesPageDef.getTagRelatedResources">
          <parameters>
            <parameter name="p0" value="${payLoad}"/>
          </parameters>
        </consumer>
      </producer>
    </event>
    <event name="setShowSystemResources">
      <producer region="*">
        <consumer region="relatedresources1"
                  handler="oracle_webcenter_tagging_view_jsf_fragments_tag_center_related_resourcesPageDef.setShowSystemResources"/>
      </producer>
    </event>
     <event name="setShowPersonalResources">
      <producer region="*">
        <consumer region="relatedresources1"
                  handler="oracle_webcenter_tagging_view_jsf_fragments_tag_center_related_resourcesPageDef.setShowPersonalResources"/>
      </producer>
    </event>
  </eventMap>

Figure 23-14 shows an example of this.

Figure 23-14 Page Definition Replacement

Description of "Figure 23-14 Page Definition Replacement"

The second way to wire the together the Tagging - Tag Cloud and Tagging - Tagged Items task flows is to follow these steps. The following example shows steps for adding the refreshAllRelated event.

1. Right-click your page, then choose Go to Page Definition from the context menu.

2. On the Structure window, on lower left hand side, right-click bindings, and select Insert after bindings and then eventMap.

   Figure 23-15 Page Definition - Structure Window

   
   Description of "Figure 23-15 Page Definition - Structure Window"
   
   

3. Right-click the eventMap, and select Insert inside eventMap and then event.

   Figure 23-16 Page Definition - Event Map

   
   Description of "Figure 23-16 Page Definition - Event Map"
   
   

4. In the dialog, enter the event name from the snippet above. For this example, enter refreshAllRelated.

5. Right-click refreshAllRelated, select Insert inside refreshAllRelated and then Producer.

6. When the dialog asks for the producer region, enter *.

7. Right-click the producer, select Insert inside product, and select Consumer.

8. When the dialog asks for the handler name, enter oracle_webcenter_tagging_view_jsf_fragments_tag_center_related_resourcesPageDef.getTagRelatedResources.

9. Because that dialog asks only for the consumer handler name and not the consumer region, you must add it manually. From the main window, select the consumer node. From the Property Inspector, you see a region field. Enter the related resources task flow name in your pageDef. By default, when you drag and drop the task flow to the page, Oracle JDeveloper names it relatedresources1. If you later change the name, then make sure to use that new name instead of relatedresources1. (Figure 23-17)

   Figure 23-17 Related Resources in the Page Definition

   
   Description of "Figure 23-17 Related Resources in the Page Definition"
   
   

10. Right-click the consumer, Insert inside consumer, and then parameters.

11. Right-click parameters, Insert inside parameters, and then parameter.

12. When the dialog asks for the parameter name, enter anything; for example, p0. For the value, enter ${payLoad}.

Simply repeat the steps for the other events, substituting the corresponding event name and the consumer handler.

Table 23-4 shows the information for the refreshAllRelated event.

You can then click a tag in the tag cloud to see associated tagged items.

These are the only two task flows that talk to each other using events, but you can design your own task flows that listen to WebCenter events.