ddcornwall / nara-alaskana

National Archives Alaskana Explorer

nara-alaskana

National Archives Alaskana Explorer

This is an informal project to provide better access to digitized Alaskana materials within the National Archives Catalog at https://catalog.archives.gov/.

The project goals are:

1. Provide access to the most recently digitized Alaskana within the National Archives Catalog.
2. Provide a search limited to US National Archives "Alaska Digitization Project."
3. Provide browsing access to digitized materials in five "important" Alaska history topics

While others are very welcome to join the project, this is an off hours project for me (Daniel Cornwall) and has no current connection to any institution within Alaska. It is driven by my interests in Alaska history and application programming interfaces (APIs) coding.

nara-alaskana's Issues

Update About page

Update structure of About page to match style/structure of Home.

Remove unused USWDS assets

I'm confident that not all of these files will be used. Some in particular being SCSS files, unless you want to develop with Sass. There may be others, but it will need review once the project comes to a close.

Search input type should be "search" not text

Inconsistent thumbnail display

Depending on where NARA thumbnail assets are house, using the API's thumbnail["@url"] does not always result in the display of the thumbnail.

Thoughts on problem:

Process

1. "No thumbnail conditions"
2. Single thumbnail conditions
   2a. use thumbnail in thumbnail[@url]
   2b. use NARA workaround
3. Array thumbnail conditions
   3a. use thumbnail in thumbnail[@url]
   3b. use NARA workaround

See usnationalarchives/Catalog-API#9 for "workaround" thread.

Test solution against:

(Title: 1306-07 Barrow - 1940 Census)
https://catalog.archives.gov/api/v1/?naIds=52204721

Workaround thumbnail url (broken as of 3/13/2018)
https://catalog.archives.gov/catalogmedia/live/ent/seattle/rg-075/2655229/2655229-003-021-0001.jpg/opa-renditions/thumbnails/2655229-003-021-0001.jpg-thumb.jpg

API thumbnail url (works as of 3/13/2018)
https://catalog.archives.gov/OpaAPI/media/52204721/opa-renditions/thumbnails/2655229-003-021-0001.jpg-thumb.jpg

(Title: Chifornak)
https://catalog.archives.gov/api/v1/?naIds=72034258

Workaround thumbnail URL (working as of 3/13/2018)
https://catalog.archives.gov/catalogmedia/live/seattle/rg-075/1870939/JPGs/1870939-001-008-0001.jpg/opa-renditions/thumbnails/1870939-001-008-0001.jpg-thumb.jpg

API thumbnail url (broken as of 3/13/2018)
https://catalog.archives.gov/OpaAPI/media/72034258/opa-renditions/thumbnails/1870939-001-008-0001.jpg-thumb.jpg

Also need to research what (path? etc?) makes these two records different.

Some searches are much longer than others

The length of time to retrieve records is very inconsistent. It varies from almost instantaneous to over two minutes. One theory is the presence of ["@extractedtext"] in records. Searches whose results are mainly photographs are generally quick. Searches whose results are mainly PDFs generally have minute and a half plus retrieval times.

We have tried restricting fields retrieved to little effect.

Update Browse page

Update Browse page to reflect style/structure of Home.

Village Census Rolls needs description

Locate description of Village Census Rolls series and put into description.

Style search results

Make search results more aesthetic and easy to scan.

Provide non-GitHub users a way to report bugs

@digilou - Let's think about a way that non-GitHub users could file a bug report. I like our current solution of taking the user immediately to "new issue" but if one isn't a GitHub user, it asks them to create an account. Our eventual solution should still let GitHub people file a new issue, but provide the non-GitHub people a chance to chime in.

Update global nav

Make Home, Browse, and About primary nav. Move Github and Bug Reports to secondary (from footer).

Reorganize file structure

Move CSS and JS into their own respective folders. Keep USWDS assets in their own folder, as it's a 3rd-party "vendor". (although this is an opinionated choice)

No results paging for searches

When a user does a search, it is not currently possible to page past the first ten hits. Previous efforts to code this functionality resulted in two outcomes:

1. Search box stopped working and "akURL" was built from default elements.
2. Search box was operational, but button didn't do anything.

See previous versions of index.html for work on this issue.

Search and browse results should clear between result retrievals

Problem: When you do a browse search, then another, the description is replaced immediately, but the previous search results remain until the new search results are retrieved. Similar behavior in search results.

Ideally, previous results should clear when new search/browse is executed. While preserving the appending of new paging results from the same search.

Create service worker

Related to #39 to qualify this as a PWA.

Install a service worker for offline use, once the site has been visited once.

https://developers.google.com/web/ilt/pwa/introduction-to-service-worker

UI updates

Once a lot of your functionality is worked out, I'd love to update your UI design / CSS that would meld branding from NARA and Alaska with a 2018 style.

Could I be added as a collaborator (in settings) to your project? Or would you rather I fork your repo and push a branch?

Add US Web Design Standards assets

Replace Bootstrap with the USWDS assets.

Change event listener to onchange

Just an idea once our search form and data response has been refined, chance the form event listener from submit to onchange for more dynamic (immediate) search results as they pop up. Not sure how the communication with the API will handle it, but it's an idea.

Minify CSS and JS

A small improvement for performance.

Use localStorage, Cache API, or IndexedDB

Not a requirement as a PWA, but a nice-to-have. There is potential here to store some of the data accessed from NARA on the user's browser.

Something I'll need to think through a little more, but wanted to add as I'm learning this stuff.

Create icon

Related to #39

Design an icon to brand this app and be used in the manifest file, as well as a favicon. Several sizes need to be created.

Update Home links

Use https://https://ddcornwall.github.io/nara-alaskana/

Create Bios page

As mentioned in #4:
"... remove 'this is a personal project of Daniel Cornwall ...' from the bottom of pages. Let's also get rid of my transplanted navbar on the other pages. What do you think of creating a team page with short bios of us both? I don't want to take credit for your improved layout."

• Create new page to hold short biographies of Daniel and Amy
• Update global navigation and footer navigation to accommodate for new collaboration

Write unit tests

Even a small scale app should have tests written for it. In this case, TDD (test-driven dev) would work, unless you want to go BDD (behavior-driven dev). Jest is a popular library to use right now. If you don't want to go with all-the-things Facebook, Mocha is another option.

One perk of tests, it helps you think about what the user is trying to accomplish or expect, and helps keep your functions smaller.

Refactor AJAX with Fetch API

It sounds like ES6 promises open a whole new door for API calls. It may even offer better performance and security. I'd like to give it a shot later on in the project, once all the functionality has been worked out.

Thumbnails display issues

The following records show broken thumbnails:

Record: 5
Title: June 22, 1939 Loose Dogs
Parent Series: Circulars Relating to Reindeer Herding in Alaska
Year Records Start: 1933
Year Records End: 1943
There are 5 digital objects associated with this record.

View full record in NARA Catalog - https://catalog.archives.gov/id/46750793
Record Cataloged: 2017-01-31T10:48:31
NaID = 46750793

---

Record: 7
Title: Circ. to Owners - 6/26/37 Re: Killing Dogs on Ranges
Parent Series: Circulars Relating to Reindeer Herding in Alaska
Year Records Start: 1933
Year Records End: 1943
There are 6 digital objects associated with this record.

View full record in NARA Catalog - https://catalog.archives.gov/id/46750773
Record Cataloged: 2017-01-31T10:48:31
NaID = 46750773

Create manifest file

To nudge this along toward making this a PWA (progressive web app), add a manifest file with meta about the site.

https://developers.google.com/web/fundamentals/web-app-manifest/

Create form to receive comments and problems

Related to #35

Non-Github users need a way to provide feedback and report bugs. Additionally, it would be helpful to receive comments from users.

Create a separate page with a form that routes to Daniel's email.

Search: Search terms should be listed out

Currently, a user's keywords disappear and no hint of a user's search appear before results are offered.

Ideally, when a user enters keywords and presses the search button, the following should appear on a new line.

"Retrieving digital Alaskana related to [keywords]. Please be patient."

Search is broken

Getting bad request messages in console when doing searches. From regular user point of view search just hangs. Need to review API for changes.

Make zero results screen more graceful

Currently when one gets zero results, this happens:

On page:

0 results are available.

Record: undefined

In console:

Uncaught TypeError: Cannot read property 'fileUnit' of undefined

Ideally "zero results" should display more meaningful text to the user and not cause a JavaScript error.

Refactor browse and display code based on learnings in Practical JavaScript

Things to consider implementing in refactor:

• Create handlers to handle button actions
• Change for loops to forEach when appropriate
• Create a view object for display
• See if LoadData is REALLY needed

Next 10 records bug doesn't disappear until a browse search is selected

In browse.html, linked to browse.js, the intended functionality of the "next 10 records" button is:

1. Initially hidden
2. Displays and is clickable if more than ten results are returned
3. Grays out when a user reaches the end of results

2 and 3 work as expected, but the button displays initially and only disappears after a browse search is selected. It then reappears and acts as intended.

This is another issue that will not be worked on prior to the resolution of the thumbnail issue.

Implement PrintCreator function

In a future release, we want to display the creating agency of a record. The first effort to code this failed for reasons explained in the comment line.

 //The line below fails when there is more than one creating organization. Would need to be able to test for a deal with an array before displaying.
  //$("#recent").append("</br> Creating Organization: " + response.opaResponse.results.result[i].description.fileUnit.parentSeries.creatingOrganizationArray.creatingOrganization.creator.termName);

I won't work on this enhancement until our thumbnail issue is solved.

txt results in new items break browse

Items with a text format make the display break. See "Title: EPA GoGreen! Newsletters for 2011" which gives "Cannot read property '@path' of undefined" error in console.