2.0.0 Adding a New Field

This is a guide to help developers with all the technically things needed to add or modify a submission field in Vireo. Depending upon the particular-use case there are many places in the code base that may need to be modified for this task. The aim of this document is to give you an overview of all the places that you will need to look at or consider.

1. Data Model

You will likely need to store the new field somewhere in the database, probably associated with a submission object. Add the new field to the particular model, org.tdl.vireo.model.*, interface (probably the Submisison interface), and the base JPA implementation. Once you've added it there don't forget to add tests for the new field to check that everything at the model level is working correctly.

2. List Column

Most fields will be added as a new column available under the list tab. To add a new column you need to update the following locations:

• org.tdl.vireo.search.SearchOrder

  This enum defines a list of all the columns that are possible. Make sure each column has a unique identifier.

• org.tdl.vireo.search.impl.LuceneIndexerImpl

  You don't need to modify this class, but update the documentation at the top to indicate the index that is available for the new field. Each new list column must have a corresponding Lucene index so that the column may be sorted.

• org.tdl.vireo.search.impl.LuceneAbstractJobImpl

  This class handles the actually building of the lucene search index. In the method indexSubmission(sub) you need to make sure that the particular index for the column is added. The index needs to be added for both the submission and the log entry documents.

• org.tdl.vireo.search.impl.LuceneSearcherImpl

  This class handles searching the lucene index. So once the field is in the index you need to make sure that the results can be sorted by the column. Near the top of the file in a static block is a translation table of the column names. Add an entry for your new column to this table: SORT_SUB_FIELDS. If the datatype of this new field is something other than a string, then also add the type exception to SORT_TYPES mapping table.

• org.tdl.vireo.search.impl.LuceneSearcherImplTests

  This class tests that the lucene search index is build and searched correctly. You need to add your new field to several existing tests. Since results may be ordered by any columns you will always need to update the testSubmissionFilterSearchOrdering() test to include you new field as a test case. If your field has a new search facet associated with it then you will need to update both testSubmissionFilterSearch() and testActionLogFilterSearch() to confirm that your facet works on both submissions and action logs.

• views/FilterTab/results.include

  This is the view that displays the table of search results. Add a new case for to display the column for both submissions and logs.

• conf/messages

  When a column name is displayed in the UI the name for the particular column is pulled from the messages file.

3. Search Facet

If your new field requires a new search facet, i.e. something that you can use to narrow down the search, then you will need to update a few more fields:

• org.tdl.vireo.search.SearchFilter

  Update the abstract search filter interface to include settings for your new search facet. This object basically store all the parameters of the current filter search. There are two sub-interfaces from this class, ActiveSearchFilter and NamedSearchFilter. The active search filter represents the currently active filter that a user interacts with from the UI. While the named search filter are copies of the filter saved to the database. Next you will need to update those classes to accommodate the new facet.

• org.tdl.vireo.search.impl.UriActiveSearchFilterImpl

  The active search filter needs to be updated to add your new facet. The important thing about this implementation is that it can encode and decode the search filter to a simple URI formatted list. This encoding is used to store the search filter as a cookie on the users browser.

• org.tdl.vireo.search.impl.UriActiveSearchFilterImplTests

  Update the tests associated with the URI search filter. The first one is testProperties() which just checks that the values can be stored internally in memory. Next is testEncodeAndDecode() which checks that the facet's parameters may be encoded and decoded as a URI string. Finally update testCopyTo() and testCopyFrom() to ensure that the filter search can be cloned properly. These methods are used to save and retrieve from a named search filter.

• org.tdl.vireo.model.jpa.NamedSearchFilterImpl

  Simply add the new facet parameters to the implementation. This implementation is used whenever facets need to be saved to the database.

• org.tdl.vireo.search.impl.LuceneSearcherImpl

  Add your new field to the SORT_SUB_FIELDS array and add your filter with the others near the bottom of the class.

• org.tdl.vireo.model.jpa.NamedSearchFilterImplTests

  Update the tests to account for the new search facet. If the facet is a simple data type you probably only need to update the testPersistance() test to make sure that the values are saved to the database correctly.

• org.tdl.vireo.search.impl.LuceneSearcherImplTests

  You will need to update two existing tests in this class to include your new search facet. Update both testSubmissionFilterSearch() and testActionLogFilterSearch() to confirm that your facet works on both submissions and action logs.

• controllers.FilterTab

  Update the filter tab controller so that the new search facet can be managed, things added to it or removed from it. There are two methods: doAddFilterParameter() which is called when adding a new parameter to a filter, and the opposite doRemoveFilterParameter() which is used to removed a parameter from an existing filter.

• views/FilterTab/filters.include

  Add your new search facet in two places, first at the top which displays the state of the current filter. Add a case for your new facet to show the parameters that are currently being filtered by. Then next add a case below to allow the user to add a new search filter.

• conf/messages

  Update the display name for the new facet search. This is used to display the heading of the search face, and will be displayed when customizing the shown search facet with a drag and drop interface.

4. View Tab

The view tab in the administrative interface allows Vireo reviewers and managers to view a record and detail and update values. You will need to update this view so that the new field is displayed somewhere. Next, you will need to allow a method for the manager to update the value probably using some sort of AJAX functionality to preserve the user friendliness of the system.

5. Student Submission

If the new field will be collected during the student's original submission then you will need to update the submission settings tab so that Vireo managers can configure how the field works. After the field configuration is ready then it can be added to the student submission form

• org.tdl.vireo.constant.FieldConfig

  This enum contains an entry for every field asked during the student's submission and defines the name of the configuration parameters concerning this field. Vireo Managers may make the field disabled, optional, or required; and in addition change the label or help text. Add a new entry for the field you are adding, and also add it to the appropriate array at the bottom. There is a constant array defined for each of the submission steps listing the fields which appear on that step.

• conf/defaults.properties

  This file describes the default values for most setting parameters. When vireo is first installed these values are used.

• controllers.submit.[step]

  The controller for the particular step you are working with needs to be updated so that it can handle the new field. The main methods needs to be updated along with the verify(submission) method to check for errors.

• views/Submit/[step].html

  Add the field's display to the particular step where this field will be requested of the student. There are a few tags that are available if you've defined the FieldConfig above properly. You can use the #{ifEnabled FIELD_NAME} to check if the field is either optional or required. The #{fieldClass FIELD_NAME /} works similar to the standard errorClass and will add a CSS class to indicate if the field is required or not. #{fieldLabel FIELD_NAME /} and #{fieldHelp FIELD_NAME /} will evaluate to the field's label and help text.

• views/viewSubmissions.include

  This include file displays an overview of a submission used in several places: the final step confirmation step of the submission form, faculty approval, and student review pages. Update the display so that the new field is displayed.

• controllers.submit.AbstractSubmissionTests

  This is a test-case toolbox. It provides a much of helpful methods to automate each step of the submission process verifying everything at each step. This allows for tests to be created that cross submission steps without being required to re-implement all the code to submit a test each time. Update the methods that deal with page on which your new field appears. For example if your field appeared on the Document Information step then you would need to modify the 'documentInfo()' toolbox so that it can handle and verify the new field.

• controllers.submit.BasicSubmissionTests

  These are the individual test case for the submission forms. If your field has an interesting property then you must add a new test to cover that property, however most field just need to be added to the testFullSubmission() to ensure that your new field works.

5. Export Formats

Often when we capture new information through new fields we want to be able to pass that information on to other systems through the export formats. Which formats should be updated depends highly on the information collected and usefulness to the individual external systems that use Vireo's data. However at a very minimum the field must be added to the conf/vireo.xml export. This internal format is designed to record all the information we collect about a submission, there's no schema or data definition to follow. So just add the new field to be as consistent as you can.

6. Test Data Loader

The last thing to update is the test data loader. It makes the casual testers life much easier if there exists some predefined test data. The TestDataLoader is exactly that it generates several test users, submissions, and settings to make it easier to jump right in and use the system when running under play test. Please update the test data loader to generate fake data for your new field to help everyone out.