Using jQuery in a theme

The jQuery library is a JavaScript library. IBM® WebSphere® Portal uses the Dojo JavaScript library.

About this task

The iWidget container, Tagging and Rating component, the Web Content Authoring portlet, the inline editing component in the Web Content Viewer portlet, and page editing capabilities from the Page Builder theme all rely on the Dojo library.

You can create a jQuery module and use that module to manipulate the portal page. The example here is not meant to show a full replacement of the Dojo framework with jQuery but rather to show the basics of how to use jQuery with WebSphere Portal. For the example, jQuery is used to create a tooltip over an element on the page. jQuery is supported by the jQuery Foundation at jquery.org, and not by IBM.

1. Create a jQuery core module.
   1. Create jquery folder in your theme's root folder in WebDAV fs-type1.
   2. Download the newest 1.x version of the jQuery core from jQuery into your jquery folder. Download both the compressed, production file, such as jquery-1.10.2.min.js, and uncompressed, developer file, such as jquery-1.10.2.js.
   3. Create a jquery.json module definition file in your theme's contributions folder. You can copy and paste the following code as the content of the file.

      {
      		"modules":[{
      			"id":"jquery",
      			"contributions":[{
      				"type":"head",
      				"sub-contributions":[{
      					"type":"js",
      					"uris":[{
      						"value":"/jquery/jquery-1.10.2.min.js"
      					},
      					{
      						"value":"/jquery/jquery-1.10.2.js",
      						"type":"debug"
      					}]
      				}]
      			}]
      		}]
      	}

2. Optional: If you want to use any plug-ins with the jQuery core do the following optional steps.
   1. Create a jquery_plugins folder in your theme's root folder in WebDAV fs-type1.
   2. Download the jQuery plug-in from jquery.com, such as the jquery.powertip-1.2.0.zip file from Powertip. In this example, use the PowerTip plug-in.
   3. Create a subfolder in your jquery_plugins folder for the plug-in, such as PowerTip in this example.
   4. Extract the contents of your plug-in file into your plug-in subfolder, \jquery_plugins\powertip in this example.
   5. Create a jquery_plugins.json module definition file in your theme's contributions folder. You can copy and paste the following code as an example, which shows a module definition for the useful PowerTip plug-in.

      {
      		"modules":[{
      			"id":"jquery_powertip",
      			"prereqs":[{
      				"id":"jquery"
      			}],
      			"contributions":[{
      				"type":"head",
      				"sub-contributions":[{
      					"type":"js",
      					"uris":[{
      						"value":"/jquery_plugins/powertip/jquery.powertip.min.js"
      					},
      					{
      						"value":"/jquery_plugins/powertip/jquery.powertip.js",
      						"type":"debug"
      					}]
      				}, {
      					"type":"css",
      					"uris":[{
      						"value":"/jquery_plugins/powertip/css/jquery.powertip.min.css"
      					}, {
      						"value":"/jquery_plugins/powertip/css/jquery.powertip.css",
      						"type":"debug"
      					}]
      				}]
      			}]
      		}]
      	}

      This example uses the default color scheme for the tips, but PowerTip comes with multiple color schemes as defined in separate css files in its css folder. You can change to one of the other color schemes or create one of your own by changing the css subcontribution URIs. For example, to get the light color scheme, you can change "/jquery_plugins/powertip/css/jquery.powertip.min.css" and "/jquery_plugins/powertip/css/jquery.powertip.css" to "/jquery_plugins/powertip/css/jquery.powertip-light.min.css" and "/jquery_plugins/powertip/css/jquery.powertip-light.css".

   6. 
      
3. If you have extra plug-ins, similar module definitions for them can be added into this jquery_plugins.json file.
   1. For each module definition, be sure to give the module an ID that starts with jquery_, such as jquery_powertip in this example.
   2. Prereq the jquery module.
   3. Use head type contributions for the css and js resources of the plug-in.
   4. Use the minified .min.css and .min.js version of the resources as your main subcontribution URIs.
   5. Use the non-minified .css and .js version of the resources as your debug type subcontribution URIs.
4. Add the module jquery to the module listings in one of your theme's profiles. Rather than modify one of the existing profile files, it is best to copy one of them and modify the copy. Copy the base profile file that you want to be similar to, such as profile_deferred.json, rename it to something such as profile_jquery_deferred.json and add the module jquery in it. When copying to create a profile file like this, be sure to adjust the titles and descriptions so that your profile has a unique and recognizable title and description. For example, change the titles and descriptions to the following code.

   "titles": [
         {
            "value": "jQuery Deferred",
            "lang": "en"
         }
      ],
      "descriptions": [
         {
            "value": "This profile has jQuery plus the full set of modules for the theme, but defers loading most of these modules unless actually needed.  This profile balances function and performance.",
            "lang": "en"
         }
      ]

5. Add the plug-in modules to the module listings in your profile. In this example, add the module jquery_powertip.
6. Invalidate the cache so that your profile and module changes are picked up by the Portal server. Click Administration > Theme Analyzer > Utilities > Control Center > Invalidate Cache > Click to invalidate. If you don't have the Theme Analyzer portlet, you can get it from the catalog atGreenhouse. The Theme Analyzer portlet is useful for developing modules and themes. If you don't, restart your Portal server.
7. Apply your profile to a page. Under Edit Page Properties > Advanced, select your profile: jQuery Deferred.
8. To verify that jQuery is loaded on a page and what version it is, you can run $().jquery in the console of your browser's developer tools and it echoes the jQuery version number.

   Now the jQuery core and your plug-ins are ready and available for use. A good place to learn the basics about jQuery core usage is at jQuery core. And then you can learn the usage of your plug-ins at the same site where you downloaded the plug-in, such as at jQuery powertip. for this example.

   The PowerTip offers flexible tip positioning at the compass points, the option to smart position the tip so it is never clipped off the edge of the view port, and the option to have the tip remain visible while it is in focus so the user can interact with the contents of the tip. This mouse onto behavior is very commonly needed, and the south positioning with smart positioning is common, so here is an example of PowerTip usage code for those options:

   <script type="text/javascript">
   	$(function() {
   		$('#myelement').data('powertiptarget', 'mytip');
   		$('#myelement').powerTip({ placement: 's', mouseOnToPopup: true, smartPlacement: true });
   	});
   </script>
   <div id="mytip" style="display:none">
   	<input type="text" />
   	<input type="button" value="Search" />
   </div>

   Replace myelement with the ID of the element on the page that you want to add the tip to. And mytip is the ID of the div that is the tip itself, which is defined by the div in the example. Notice that the tip div is set to display:none initially. The PowerTip code shows it when the user mouses over the myelement element.

   Multiple tooltips can easily be defined by replicating the data and powerTip lines for each tooltip and replicating the div block for each tooltip, modifying the ids for each one. Add the code anywhere on the page. You can use the theme content spots, or through a config markup subcontribution of the module.

9. If your markup is visible and therefore needs to be injected at a specific location on the page, then use option 1. However, this markup is all hidden at first and can be located anywhere on the page. To use a configuration markup subcontribution of the module, follow these steps.
   1. Create a markup folder in your theme's root folder.
   2. Create a jquery_theme_tooltips.html markup file in your markup folder. You can copy and paste the following code as an example:

      <script type="text/javascript">
      	$(function() {
      		$('#wpthemeHelp img').data('powertiptarget', 'wpthemeHelpTip');
      		$('#wpthemeHelp img').powerTip({ placement: 's', mouseOnToPopup: true, smartPlacement: true });
      	});
      </script>
      <div id="wpthemeHelpTip" style="display:none">
      	<form method="get" action="http://www-10.lotus.com/ldd/portalwiki.nsf/xpSearch.xsp" target="wiki">
      		<input type="text" name="searchValue" />
      		<input type="submit" value="Search" />
      	</form>
      </div>

      This example assumes that your theme has a help element with id wpthemeHelp similar to the default theme. If your theme does not have an element with id wpthemeHelp, then change the two instances of '#wpthemeHelp img' to a selector that identifies one of the elements in your theme, and rename the two instances of wpthemeHelpTip.

      Also note that this example uses a simple form on the tooltip that searches the Portal documentation. You can change the markup in your tooltip div entirely to whatever you need to appear on your tooltip.

   3. Create a theme_powertips.json module definition file in your theme's contributions folder to load your markup file. You can copy and paste the following code as an example:

      {
      	"modules":[{
      		"id":"theme_powertips",
      		"prereqs":[{
      			"id":"jquery_powertip"
      		}],
      		"contributions":[{
      			"type":"config",
      			"sub-contributions":[{
      				"type":"markup",
      				"uris":[{
      					"value":"/markup/theme_powertips.html"
      				}]
      			}]
      		}]
      	}]
      }

      Notice that the module was given an id such as theme_powertips and that it prereqs module jquery_powertip.

   4. Add the module "theme_powertips" to the module listings in your jquery profile file.
   5. Invalidate the cache or restart your portal server to pick up your profile and module changes.
   6. Go to your page that has your jquery profile that is applied, move the mouse over the help icon, or whichever theme element you specified in step 2, and your tip appears.