Ancient Graffiti Project Development

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Documentation ======

Our full documentation can be found in our files and at this [[https://github.com/sprenks18/CSCI335_AGP/blob/term_page/Graffiti/README.md|link]]
==== Development Tips ====

Welcome to the Ancient Graffiti Project! As you may have noticed this project is massive and can be a little intimidating at first, we ran into this problem as well and created this guide to help you out. While we try to give a good overview of the whole project, we're still discovering new things so feel free to correct and/or augment this guide with your knowledge. Best of luck

==== How the databases work ====

The databases are postgresql, to get easy access to them just ssh into fred and then navigate to whatever version of the database Sprenkle gave you access to. For a full list of databases go into [[https://github.com/sprenks18/CSCI335_AGP/blob/term_page/Graffiti/documentation/graffiti_schema.sql|documentation/graffiti_schema.sql]]

=== Setup ===

The setup process is fairly simple, in the setup folder the populate database class runs and calls a set of functions that populate the databases either directly by pulling data from csv files or indirectly by pulling data from other databases. **Note that populate database does not run on the startup so you'll have to call any setup functions manually for testing.** There's also a great guide to set up in [[https://github.com/sprenks18/CSCI335_AGP/blob/term_page/Graffiti/documentation/SetUpData.txt|documentation/SetUpData.txt]]

=== Beans! ===

Beans are java objects that encapsulate data taken from the database. In this project, beans are used to provide quick, easy, and controlled access to data pulled from a database. They tend to not do a lot of processing and really are just used for access.

=== Rowmappers and DAOs ===

Beans are generated by rowmappers. Rowmappers take the results from postgresql queries and turn them into beans using the constructor interface specified. Different beans are generally used for different queries and provide different interfaces. Rowmappers don't have to return beans though and can in fact just be used to map specific datatypes.

DAOs (data access objects) store and execute postgresql queries and handle all the errors that can come from such requests.

==== How the web pages work ====

Web pages are all stored in the WEB-INF folder and are all jsp files. It is common to break up a page into a series of imports such that the page itself can basically be run in two lines. The imports contain all the structure of the page and allow for a consistent look. Check out [[https://github.com/sprenks18/CSCI335_AGP/blob/term_page/Graffiti/src/main/webapp/WEB-INF/jsp/termIndex.jsp|termIndex.jsp]] and [[https://github.com/sprenks18/CSCI335_AGP/blob/term_page/Graffiti/src/main/webapp/WEB-INF/jsp/termIndexList.jsp|termIndexList.jsp]] for an example.

=== Accessing a jsp in WEB-INF ===

Jsp sites are accessed through controllers. For each site that can be accessed their is an associated mapping in a controller that runs a function when the associated url is executed. These can be very short and just return the page or they can contain a lot of processing and data storage for the resulting web page.

=== Search ===

Search and pages that depend on special characters pass their values as arguments in the url rather than as elements of the url itself. This handles a whole host of errors and when used with UTF-8 encoding and the spring filter system protects against xss attacks. 

==== How the index page works ====

When a user tries to access the term index page an associated term index function in the graffiti controller pulls the list of unique terms and generates a list. This list is then sorted using the Greek sorting system to account for special characters and greek. For each item in this list the associated data for each term is called and passed to the jsp. The data needed is generated by the [[https://github.com/sprenks18/CSCI335_AGP/blob/term_page/Graffiti/src/main/java/edu/wlu/graffiti/dao/IndexTermDao.java|Index Term DAO]] and the [[https://github.com/sprenks18/CSCI335_AGP/blob/term_page/Graffiti/src/main/java/edu/wlu/graffiti/data/rowmapper/IndexTermRowMapper.java|Index Term]] and [[https://github.com/sprenks18/CSCI335_AGP/blob/term_page/Graffiti/src/main/java/edu/wlu/graffiti/data/rowmapper/UniqueRowMapper.java|Unique Rowmappers]] using the Index Term bean. 

The term index list does not display terms that have been blacklisted by an admin and furthermore will eventually be sorted by data on the type of index when such data is added. This will require some sort of interaction with the epidocs. 

The data all comes from the graffiti_index table. This table is generated by the [[https://github.com/sprenks18/CSCI335_AGP/blob/term_page/Graffiti/src/main/java/edu/wlu/graffiti/data/setup/InsertIndexEntries.java|Insert Index Entries]] class which for development purposes be called by the term index page function in the graffiti controller. There is talk of implementing this as a button that an admin could click but we would advise caution because at the moment it erases all data in the table including whitelist preferences which might not be ideal.

==== Map Display in the Search Results ====

Prior to our work on this project, both the maps for Herculaneum and Pompeii would be displayed for all search results.  This included a search result which yielded no graffiti.  No the map display on the right side of the screen changes dynamically as the user filters their search.  If results from Herculaneum are included in the hits, then that map is displayed.  The same is true for Pompeii.  If the only results are from Smyrna, then no maps are displayed.  Currently, the maps are stationary and do not shift up and down depending on which are displayed.  This could be changed in the future according to the client's wishes.  This feature functions because in the graffiti controller we pass a boolean attribute for each mapped city to the webpage, which tells it whether or not that city should be displayed.  The page then saves that into a hidden html field, which is then used by filterSearch.js to produce the desired results.

==== Updates to the Header / Navigation Bar ====

Previously, the header bar would collapse after the shrinking window size had already forced the search bar onto its own line.  This was not aesthetically pleasing, and was a bug that needed to be addressed.  By using css's @media property, I was able emulate bootstrap's method for collapsing navigation bars.  This solution achieved the desired result of collapsing the bar before the search bar was forced onto a new line.  However, the formatting is not identical to that of bootstrap's.  This isn't a huge deal in an average use case, but if a user resizes the window while the hamburger menu (the opened version of the collapsed nav-bar) is open, they could potentially see it change style.  This is because Bootstrap's defaults kick in when the window reaches a certain minimum width.
==== Loading Data into the Database Through EpiDocs ====

Loading the data representing the Smyrna graffiti is as easy as clicking a button.  Simply open ReadFromEpidoc.java and run it as a java application.  In the terminal window, you will see output statements detailing the progress of the import.  If there were to be an issue, these outputs are a great resource for the user.  Under the hood, ReadFromEpidoc iterates through all of the files in the smyrna_epidocs directory and parses them.  As it parses it saves key information, such as the graffito's id or its findspot, and saves it in the database.  More specific information on parsing can be found here:  [[https://wlu.app.box.com/notes/191721659898 | EpiDoc Conventions]].  Once all of the new data has been loaded into the database, the user must then run AddInscriptionsToElasticSearch.java as a java application.  This will set up Elastic Search and enable the new graffiti to appear in search results.  With those simple steps, all the EpiDoc-ed graffiti should now be visible on the site.

==== Updages to the Admin Tools: Ignore List Function ====

The Ignore List Function (previously refered to as the "black list") has been fully implemented under the Admin Tools tab. In order to access this function, the user will need to first authenticate through the admin login page. The final use case is where the user is able to choose what items can be displayed in the index by simplying selecting items from the Ignore List page and perform corresponding actions. The page layouts shows three boxs (from left to right): items that should be displayed, items that are displayed but still require further review, and items that should be ignore and not displayed. User can move items between tables easily using the buttons implemented. There is also a search bar on top of each table that allow users to access items more easily.

In order to load up the funciton, simply run modifyIgnoreList.jsp on the server. In order to check the database, use Professor Sprenkle's instruction to access the database on the servo. The JSP sends the query into the database to retrieve the items and sort them in alphabetical order.