Quadriga - where is what?

Once you set up your computer and cloned the Quadriga repository (see Setting up your Quadriga development environment (Java)), you're ready to start developing! If everything is set up correct, you should see a project structure like this:

The following folders are of relevance to you:

• Java Resources
  Here you can find the different Java and resource folders of the project: the main code (in src/main/java), resources such as property files (in src/main/resources), test classes (in src/test/java), and resource files for the test classes (in src/test/resources).

• src
  This folder contains the folders also shown under Java Resources (you can regard "Java Resources" like a shortcut to certain folders), and additional folders required for you web application. Of main importance here is the folder "webapp", which will be described in more detail below.
  
• target
  The target folder is used by Maven to store the files it generates like the web application to be deployed in Tomcat, or code coverage reports.

The webapp folder

Next to the Java code base, the webapp folder is probably the folder you will be concerned most with. It has the following structure:

In the resources folder (right under webapp), you will find mainly files necessary for the layout of the website (css files, js files, images). If you have to work on any general layout changes, you will most likely have to edit some of the files in this folder.

The WEB-INF folder contains configuration files (in "spring" folder) and all the jsp pages (in "views" folder) and tiles files (in"tiles" folder and tiles-defs.xml) that are used to generate the webpages. If you have to change a specific page, you will most likely find the corresponding jsp page in the "views" folder. If you have to add a new page, you will have to modify the the tiles-defs.xml. If you need to make general change to the menu bar or footer, you will probably edit a file in the "tiles" folder (which contains the tiles skeletons).

The Java source files

The root package for all Quadriga classes and packages is "edu.asu.spring.quadriga". When you open this package, you should see something like this (assuming you use the hierarchical package presentation in Eclipse):

A lot of these package names are (hopefully) self-explanatory, e.g. the package "domain" contains classes for the domain objects, the folder "dto" contains classes for Data Transfer Objects. Other important packages are:

• dao: classes for Data Access Objects
• exceptions: exception classes
• rest: controller for the REST API
• validator: validator classes
• web: controller classes for the jsp pages

How to locate what jsp page I need to change?

Locating what jsp page generates a specific webpage can be tricky. In general, to find a specific jsp do the following:

1. Go to the page you want to change (e.g. http://diging.asu.edu:8080/quadriga-test/auth/workbench/projects/PROJ_8108362c-f977-47ac-8826-1bb391e3c132) and note the URL for that page.
2. Examine the URL and find out which of the URL parts are static and which ones are depending on the object you're looking at. For example, in the above URL "http://diging.asu.edu:8080/quadriga-test/auth/workbench/projects" is static but the last part "PROJ_8108362c-f977-47ac-8826-1bb391e3c132" is the id of a project, so it changes depending on what project you look at.
3. In the static part of the URL, remove the host and application name (in the example "http://diging.asu.edu:8080/quadriga-test"), you should be left with "auth/workbench/projects" and the dynamic part (if there is one).
4. Go to the "web" package in the Java Resources. Find the controller that has a method annotated with @RequestMapping that has an attribute "value" with the static part from step 3 and placeholders for the dynamic parts. In our example, you would find the controller annotated with "auth/workbench/projects/{projectid}". Placeholders are surrounded with curly brackets.

5. Find the path used in the ModelAndView return value of the method or the return value if the method returns a string. For example, in the method:

   @RequestMapping(value="auth/workbench/projects/{projectid}", method = RequestMethod.GET)
   public ModelAndView getProjectDetails(@PathVariable("projectid") String projectid,Principal principal) throws QuadrigaStorageException
   {
   	ModelAndView model = new ModelAndView("auth/workbench/project");
   	String userName = principal.getName();
   	IProject project = projectManager.getProjectDetails(projectid);
   	model.getModelMap().put("project", project);
   	return model;
   }

   The path would be "auth/workbench/project" in line 4.
   If the method returns a string like in the following example, you just need the returned string.
   

   @RequestMapping(value="sites/{ProjectUnixName}", method=RequestMethod.GET)
   	public String showProject(@PathVariable("ProjectUnixName") String unixName,Model model) throws QuadrigaStorageException {
   	IProject project = projectManager.getProjectDetailsByUnixName(unixName);
   	if(project!=null){
   		model.addAttribute("project", project);
   		return "website";
   	}
   	return "forbidden";
   }

    If there is a project with the provided "unix name", "website" will be "returned", otherwise "forbidden".

6. Now, open tiles-def.xml and find the definition that has as its name the string you located in the last step (e.g. "auth/workbench/project" or "website"):

   <definition name="auth/workbench/project" extends="base.definition.workbench.nav">
   	<put-attribute name="title" value="Quadriga - Project Details" />
   	<put-attribute name="left-navigation"
   		value="/WEB-INF/views/navigation/nav-workspace.jsp" />
   	<put-attribute name="content"
   		value="/WEB-INF/views/workbench/project.jsp" />
   </definition>

   In the put-attribute tags, you can find what jsp pages are rendered for what part of the website. E.g. the jsp page "/WEB-INF/views/navigation/nav-workspace.jsp" is rendered for the left navigation. The jsp page "/WEB-INF/views/workbench/project.jsp" is rendered for the content of the project page. These are the pages you need to edit.