...
Content Distribution Networks (CDNs)
...
| Info |
|---|
Hold off on using CDN URLs until | Jira Legacy |
|---|
| server | System JIRA |
|---|
| serverId | d8d429a7-dc92-3696-85f0-1de5d4e9bcf6 |
|---|
| key | RESSERV-82 |
|---|
|
is implemented. Otherwise it becomes a problem when you are attempting to work on uPortal or do demos in offline mode. |
Some popular libraries are hosted on CDNs. To decrease load times (browser accesses a different domain) and potentially improve performance (a different application may have downloaded the JS library from the CDN and have it in the browser's cache), a CDN can be used instead of obtaining the library from the Resource Server. The CDN must support HTTPS to access the library so user's don't get security warnings.
...
- jQuery, jQuery UI
- Bootstrap (though see Bootstrap below for use in portlets)
Resources Preferred way to access resources from a CDN should use the resourceURL tag library to load them rather than accessing the CDNs directly. This allows the URL to be modified to a non-minified version when JS aggregation is disabled or running in off-line mode (though the resourceURL tag currently does not do this). E.g. access like:
| Code Block |
|---|
<script src="<rs:resourceURL value='//code.jquery.com/jquery-1.10.2.min.js'/>" type="text/javascript"></script> |
Loading Javascript
Below is an example of loading jQuery 1.10.2, jQuery TreeView 1.4.0 and assigning them under the myPortletName is to put them in a skin.xml file and use the rs:aggregatedResources tag so you get the non-minified versions when desired. The below example assumes
| Code Block |
|---|
| title | Preferred way to access CDN content |
|---|
|
skin.xml:
<resources xmlns="http://www.jasig.org/uportal/web/skin" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.jasig.org/uportal/web/skin https://source.jasig.org/schemas/resource-server/skin-configuration/skin-configuration-v1.2.xsd">
<js included="plain">//code.jquery.com/jquery-1.10.2.js</js>
<js included="aggregated">//code.jquery.com/jquery-1.10.2.min.js</js>
<js included="plain">//code.jquery.com/ui/1.10.3/jquery-ui.js</js>
<js included="aggregated">//code.jquery.com/ui/1.10.3/jquery-ui.min.js</js>
</resources>
JSP file:
<%-- This example assumes the portlet.xml defines a portlet preference includeJsLibs=false that the installer can override to set to true if needed.
The portletPreferencesValues variable comes from the defineObjects tag library. --%>
<%@ taglib prefix="portlet" uri="http://java.sun.com/portlet_2_0" %>
<portlet:defineObjects/>
<c:if test="${portletPreferencesValues['includeJsLibs'][0] != 'false'}">
<rs:aggregatedResources path="/resources.xml"/>
</c:if>
<script type="text/javascript"><rs:compressJs>
var ${n} = {}; <%-- This is one way to namespace this portlet's version of jQuery --%>
<c:choose>
<c:when test="${portletPreferencesValues['includeJsLibs'][0] != 'false'}">
${n}.jQuery = jQuery.noConflict(true)
</c:when>
<c:otherwise>
${n}.jQuery = up.jQuery;
</c:otherwise>
</c:choose>
${n}.jQuery(function(){
...
}
</rs:compressJs></script> |
The alternative is to load them from the CDNs directly as you would in any webapp.
| Code Block |
|---|
| title | non-preferred way to access CDN content |
|---|
|
<script src="//code.jquery.com/jquery-1.10.2.min.js" type="text/javascript"></script> |
Loading Javascript
Below is an example of loading jQuery 1.10.2, jQuery TreeView 1.4.0 and assigning them under the myPortletName var with the portlet's namespace key. The myPortletName var with the portlet namespace property is used as a namespace for this portlet's JavaScript, allowing the portlet to declare its own functions without placing them in the global namespace.
| Code Block |
|---|
|
<!-- Store the portlet namespace string in the JSP page variable "n" -->
<c:set var="n"><portlet:namespace/></c:set>
<!-- Use a resource URL for common javascript libraries that multiple portlets may share and is present in the Resource Serving Webapp. -->
<script src="<rs:resourceURL value='//code.jquery.com/jquery-1.10.2.min.js'/>" type="text/javascript"></script>
<script src="<rs:resourceURL value='/javascriptrs/jquery-treeview/1.4.0/jquery.treeview.js'/>" type="text/javascript" ></script>
<script src="${pageContext.request.contextPath}/javascript/myPortlet.js" type="text/javascript" ></script>
<!-- alternate style <script src="<c:url value='/javascript/myPortlet.js'/>" type="text/javascript" ></script> -->
<script type="text/javascript">
/*
* Don't overwrite an existing myPortletName variable, just add to it
*/
var myPortletName = myPortletName || {};
myPortletName["${n}"] = myPortletName["${n}"] || {};
/*
* Switch jQuery to extreme noConflict mode, keeping a reference to it in the myPortletName["${n}"] namespace
*/
myPortletName["${n}"].jQuery = jQuery.noConflict(true);
/**
* Use an anonymous function to initialize all JavaScript for this portlet.
*/
(function($) {
// treeview init
$('#${n}community ul.listing').treeview({
animated: {duration:300, easing:"swing"},
collapsed: true,
unique: false
});
$('#${n}community ul.treeview ul').siblings('a').click(function(e) {
e.preventDefault();
$(this).siblings('div.hitarea').trigger('click');
$(this).blur();
});
})(myPortletName["${n}"].jQuery);
</script>
|
...
| Code Block |
|---|
|
<script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
<script type="text/javascript">
// Bootstrap javascript fails if included multiple times on a page.
// uPortal Bootstrap best practice: include bootstrap if and only if it is not present and save it to
// portlets object. Bootstrap functions could be manually invoked via portlets.bootstrapjQuery variable.
// All portlets using Bootstrap Javascript must use this approach. Portlet's jQuery should be included
// prior to this code block.
var portlets = portlets || {};
// If bootstrap is not present at uPortal jQuery nor a community bootstrap, dynamically load it.
up.jQuery().carousel || portlets.bootstrapjQuery || document.write('<script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"><\/script>');
</script>
<script type="text/javascript">
// Must be in separate script tag to insure bootstrap was dynamically loaded.
portlets["${n}"] = {};
portlets["${n}"].jQuery = jQuery.noConflict(true);
// If bootstrap JS global variable was not defined, set it to the jQuery that has bootstrap attached to.
portlets.bootstrapjQuery = portlets.bootstrapjQuery || (up.jQuery().carousel ? up.jQuery : portlets["${n}"].jQuery);
</script> |
Development Tips
| Tip |
|---|
| title | Javascript aggregation tip |
|---|
|
On your local and dev instance, you can permanently disable JavaScript and CSS aggregation by adding to your .bash_profile: export JAVA_OPTS="$JAVA_OPTS -Dorg.jasig.resourceserver.utils.aggr.aggregated_theme=false” Also see UE Development Tips was not defined, set it to the jQuery that has bootstrap attached to.
portlets.bootstrapjQuery = portlets.bootstrapjQuery || (up.jQuery().carousel ? up.jQuery : portlets["${n}"].jQuery);
</script> |
Development Tips
| Tip |
|---|
| title | Javascript aggregation tip |
|---|
|
On your local and dev instance, you can permanently disable JavaScript and CSS aggregation by adding to your .bash_profile: export JAVA_OPTS="$JAVA_OPTS -Dorg.jasig.resourceserver.utils.aggr.aggregated_theme=false” Also see UE Development Tips |
| Tip |
|---|
To use JSTL expressions like ${portletPreferencesValues['includeJsLibs'][0] != 'false', make sure you have the portlet 2.0 version of the portlet tag, not the portlet 1.0 version; e.g. <%@ taglib prefix="portlet" uri="http://java.sun.com/portlet_2_0" %>
<portlet:defineObjects/>
not
<%@ taglib prefix="portlet" uri="http://java.sun.com/portlet" %>
<portlet:defineObjects/> |
| Info |
|---|
| icon | false |
|---|
| title | Additional References |
|---|
|
CSS Best Practices JSP Best Practices |