In this manual we'll setup and enable jQuery javascript libraries instead of default scriptaculous ones, they both have great effects and functionalities so we can choose the one that best fits our interest, or knowledge.
Note: We'll add jqueryui (jquery user interface) libraries too. With them will be easy to generate visual effects or use widgets like calendars, progressbars ...
Using simple on/off switches defined in <dspace:layout> element we'll allow DSpace .jsp pages to load or not this script files. Example:
Code Block |
---|
language | html/xml |
---|
title | Enable jQuery |
---|
|
<dspace:layout titlekey="jsp.search.results.title" navbar="off" locbar="off" scriptaculous="off" jquery="on"> |
Code Block |
---|
language | html/xml |
---|
title | Enable scriptaculous |
---|
|
<dspace:layout titlekey="jsp.search.results.title" navbar="off" locbar="off" scriptaculous="on" jquery="off"> |
Code Block |
---|
language | html/xml |
---|
title | Disable all |
---|
|
<dspace:layout titlekey="jsp.search.results.title" navbar="off" locbar="off" scriptaculous="off" jquery="off"> |
First we'll take a look to the current use of script libraries in DSpace and later we'll start modifying source files.
script.aculo.us libraries
DSpace JSPUI interface bundles scriptaculous javascript libraries in every page head section. We can check that looking at source code of DSpace home page, we'll see this few lines:
Code Block |
---|
|
<script type="text/javascript" src="/jspui/static/js/scriptaculous/prototype.js"> </script>
<script type="text/javascript" src="/jspui/static/js/scriptaculous/effects.js"> </script>
<script type="text/javascript" src="/jspui/static/js/scriptaculous/builder.js"> </script>
<script type="text/javascript" src="/jspui/static/js/scriptaculous/controls.js"> </script> |
Doing a litle browsing we can check that this libraries (prototype) are used in a library function:
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/static/js/choice-support.js |
Code Block |
---|
language | javascript |
---|
title | function DSpaceChoiceLookup(...) |
---|
collapse | true |
---|
|
// Create popup window with authority choices for value of an input field.
// This is intended to be called by onClick of a "Lookup" or "Add" button.
function DSpaceChoiceLookup(url, field, formID, valueInput, authInput,
confIndicatorID, collectionID, isName, isRepeating)
{
...
cOffset = $(inputField).cumulativeOffset();
...}
|
This function is called on the following java server pages:
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/submit/edit-metadata.jsp |
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp//tools/edit-item-form.jsp |
By now we know which pages use scriptaculous, , let's see jQuery.
jQuery libraries
DSpace already uses a copy of jQuery, but in a local form. The library function that uses it is:
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/dspace-admin/js/bitstream-ordering.js |
Code Block |
---|
language | javascript |
---|
title | function ($) |
---|
collapse | true |
---|
|
function ($) {
$(document).ready(function() {
var bitstreamTable = $("table#bitstream-edit-form-table");
...
})(jQuery); |
This function is called on the following java server page:
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/tools/edit-item-form.jsp |
And jQuery library file can be located on:
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/dspace-admin/js/jquery-1.4.2.min.js |
Now that every script file and script file caller is located we'll start to code.
First steps
In this examples we'll overwrite existing source code files, if you feel comfortable working with JSPUI modules can move this modifications to "dspace/modules/jspui" folder.
Copying jQuery files to JSPUI webapp folder
We'll create a folder to accommodate jQuery and jQuery-UI script files in
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/static/js/jqueryui/
|
First we must download jquery and jquery-ui script libraries from jQuery UI webpage, we'll download it's full version so we can use more functionalities on future modifications. All files are zipped inside a structure like this:
- Folder - css
- Folder - js
- Folder - development-bundle
- File - index.html
We'll use only js and css folders for our purposes. I'll describe selected folders content:
- js : Contains jquery-1.7.2.min.js and jquery-ui-1.8.21.custom.min.js script files
- css: Contains ui-lightness folder, here are all necessary .css style files and images to display ui-lightness visual theme, (name may vary if we select another visual theme on jQuery UI page)
Warning |
---|
|
Newer versions of jqueryui can contain different filenames that the ones provided in this manual, take care that your downloaded files match the references on your .jsp file |
We'll create a new folder inside dspace-source/dspace-jspui/dspace-jspui-webapp/src/main/webapp/static/js/jqueryui and copy all previously described files inside it..Structure will look like this:* dspace-source/dspace-jspui/dspace-jspui-webapp/src/main/webapp/static/js/jqueryui/jquery-1.7.2.min.js
- dspace-source/dspace-jspui/dspace-jspui-webapp/src/main/webapp/static/js/jqueryui/jquery-ui-1.8.21.custom.min.js
- dspace-source/dspace-jspui/dspace-jspui-webapp/src/main/webapp/static/js/jqueryui/css/...
We must define inside dspace tag library descriptor a pair of variables that will be used in LayoutTag class file: scriptaculous and jquery.
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/WEB-INF/dspace-tags.tld
|
Code Block |
---|
language | html/xml |
---|
title | dspace-tags.tld |
---|
collapse | true |
---|
|
<tag>
<name>layout</name>
<tagclass>org.dspace.app.webui.jsptag.LayoutTag</tagclass>
<info>Lays out an HTML page</info>
...
<attribute>
<name>scriptaculous</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
</attribute>
<attribute>
<name>jquery</name>
<required>false</required>
<rtexprvalue>true</rtexprvalue>
</attribute>
...
</tag> |
Then we must add the private variables and it's getter and setters:
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/webui/jsptag/LayoutTag.java
|
Code Block |
---|
|
public class LayoutTag extends TagSupport
{
...
/** scriptaculous flag */
private String scriptaculous;
public String getScriptaculous()
{
return scriptaculous;
}
public void setScriptaculous(String scriptaculous)
{
this.scriptaculous = scriptaculous;
}
/** jquery flag **/
private String jquery;
public String getJquery()
{
return jquery;
}
public void setJquery(String jquery)
{
this.jquery = jquery;
}
...
public int doStartTag() throws JspException
{
ServletRequest request = pageContext.getRequest();
...
if (scriptaculous != null)
{
request.setAttribute("dspace.layout.scriptaculous", scriptaculous);
}
if (jquery != null)
{
request.setAttribute("dspace.layout.jquery", jquery);
}
...
}
...
}
|
Once our variables are declared in our layout tag, we'll use them in header-default.jsp file. The one that renders header section of every page displayed by DSpace.
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp
|
Code Block |
---|
|
<%--
The contents of this file are subject to the license and copyright
detailed in the LICENSE and NOTICE files at the root of the source
tree and available online at
http://www.dspace.org/license/
--%>
<%--
- HTML header for main home page
--%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt" %>
<%@ taglib uri="http://www.dspace.org/dspace-tags.tld" prefix="dspace" %>
<%@ page contentType="text/html;charset=UTF-8" %>
<%@ page import="java.util.List"%>
<%@ page import="java.util.Enumeration"%>
<%@ page import="org.dspace.app.webui.util.JSPManager" %>
<%@ page import="org.dspace.app.webui.util.UIUtil" %>
<%@ page import="org.dspace.core.ConfigurationManager" %>
<%@ page import="org.dspace.app.util.Util" %>
<%@ page import="org.dspace.browse.BrowseIndex" %>
<%@ page import="org.dspace.browse.BrowseInfo" %>
<%@ page import="javax.servlet.jsp.jstl.core.*" %>
<%@ page import="javax.servlet.jsp.jstl.fmt.*" %>
<%
String title = (String) request.getAttribute("dspace.layout.title");
String navbar = (String) request.getAttribute("dspace.layout.navbar");
boolean locbar = ((Boolean) request.getAttribute("dspace.layout.locbar")).booleanValue();
String siteName = ConfigurationManager.getProperty("dspace.name");
String scriptaculous = (String) request.getAttribute("dspace.layout.scriptaculous"); //Added code
String jquery = (String) request.getAttribute("dspace.layout.jquery"); //Added code
String feedRef = (String)request.getAttribute("dspace.layout.feedref");
boolean osLink = ConfigurationManager.getBooleanProperty("websvc.opensearch.autolink");
String osCtx = ConfigurationManager.getProperty("websvc.opensearch.svccontext");
String osName = ConfigurationManager.getProperty("websvc.opensearch.shortname");
List parts = (List)request.getAttribute("dspace.layout.linkparts");
String extraHeadData = (String)request.getAttribute("dspace.layout.head");
String dsVersion = Util.getSourceVersion();
String generator = dsVersion == null ? "DSpace" : "DSpace "+dsVersion;
%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title><%= siteName %>: <%= title %></title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="Generator" content="<%= generator %>" />
<link rel="stylesheet" href="<%= request.getContextPath() %>/styles.css" type="text/css" />
<link rel="stylesheet" href="<%= request.getContextPath() %>/print.css" media="print" type="text/css" />
<link rel="shortcut icon" href="<%= request.getContextPath() %>/favicon.ico" type="image/x-icon"/>
<%
if (!"NONE".equals(feedRef))
{
for (int i = 0; i < parts.size(); i+= 3)
{
%>
<link rel="alternate" type="application/<%= (String)parts.get(i) %>" title="<%= (String)parts.get(i+1) %>" href="<%= request.getContextPath() %>/feed/<%= (String)parts.get(i+2) %>/<%= feedRef %>"/>
<%
}
}
if (osLink)
{
%>
<link rel="search" type="application/opensearchdescription+xml" href="<%= request.getContextPath() %>/<%= osCtx %>description.xml" title="<%= osName %>"/>
<%
}
if (extraHeadData != null)
{ %>
<%= extraHeadData %>
<%
}
if (scriptaculous == null || scriptaculous.equals("on")) //Added code starts here
{
%>
<script type="text/javascript" src="<%= request.getContextPath() %>/static/js/scriptaculous/prototype.js"> </script>
<script type="text/javascript" src="<%= request.getContextPath() %>/static/js/scriptaculous/effects.js"> </script>
<script type="text/javascript" src="<%= request.getContextPath() %>/static/js/scriptaculous/builder.js"> </script>
<script type="text/javascript" src="<%= request.getContextPath() %>/static/js/scriptaculous/controls.js"> </script>
<% }
if (jquery != null && jquery.equals("on"))
{
%>
<script src="<%= request.getContextPath() %>/static/js/jqueryui/jquery-1.7.2.min.js" type="text/javascript"></script>
<script src="<%= request.getContextPath() %>/static/js/jqueryui/jquery-ui-1.8.21.custom.min.js" type="text/javascript"></script>
<link type="text/css" href="<%= request.getContextPath() %>/static/js/jqueryui/css/ui-lightness/jquery-ui-1.8.21.custom.css" rel="stylesheet"/><!-- Check that .css filename is the same as you downloaded and placed in jqueryui folder-->
<%
} //Added code ends here
%>
<script type="text/javascript" src="<%= request.getContextPath() %>/utils.js"></script>
<!-- remove following references to scriptaculous libraries --> // Important!
<script type="text/javascript" src="<%= request.getContextPath() %>/static/js/choice-support.js"> </script>
...
|
With this code all .jsp pages that use <dspace:layout> (majority in DSpace) will load only scriptaculous libraries. In other words will behave as previous modifications.
Modifying *.jsp files
Now all we have to do is change <dspace:layout> tag with our new variables where we want to load jQuery libraries. To test that everything is working properly we'll try to set focus on search textbox in JSPUI home page using jQuery .focus() function. We'll modify this file:
No Format |
---|
[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp
|
Code Block |
---|
language | html/xml |
---|
title | home.jsp |
---|
collapse | true |
---|
|
<dspace:layout locbar="nolink" titlekey="jsp.home.title" feedData="<%= feedData %>" scriptaculous="off" jquery="on">
<script type="text/javascript">
$(document).ready(function() {
$("#tquery").focus();
});
</script> |
Then just run package and ant update to watch your function in action.
Note: If you want to work with only one version of jQuery you must delete jquery-1.4.2.min.js file, enable jquery on edit-item-form.jsp layout tag and delete jquery-1.4.2 library reference.
The advantage of using variables is that our pages will load only necessary script libraries and it makes easier to update library versions site-wide. And you can change jQuery for any other script library of you choice or add more libraries.