Dev userinterface guide - achakra/seck GitHub Wiki

The SECK user interface is a browser-based front-end for SECK’s search functionality. Using jQuery and AJAX to communicate with the REST API, this web interface will allow a user to submit a search query and view the list of matching documents. The interface design should strive to be simple and intuitive to use as well as display results in a clear and organized manner.

Deliverables

To accomplish the above within the scope of this quarter, the SECK user interface should provide at minimum the following:

  • Search page (homepage)
    • Input field for search criteria
      • Autocomplete will be provided for each word
        • Suggested words will be shown below the search box as the user types
    • Submit button to make the search request and display the results
      • To provide a better user experience, a user may hit “enter” or “return” to submit the request
  • Results page
    • The original search input
    • Total number of matched documents
    • A list of relevant search results ordered by page rank
      • Each result should include, at a minimum:
        • Page Title
        • Page URL
        • Result Statistics: Information regarding the search result (could also be gotten dynamically on need; see “getStats” below)
          • Relevancy score for the search criteria
    • Pagination, with a new page for each 20 results
      • Each page will display numbered links to other pages, with the current page styled differently to indicate it is the current page
    • A search form allowing users to submit new searches

Additional features that may be added, time permitting:

  • Page Preview
    • Display a google-style tooltip/popup showing a screenshot of the webpage when hovering over a result link
  • Sorting options
    • Display options to sort by other fields such as page rank, relevance, alphabetically by title, in either ascending or descending order
  • “I’m feelin’ lucky!”
    • It’s a mystery.

Method

The front-end will be built using HTML, CSS, and JavaScript, and will utilize jQuery to make AJAX calls to the REST API. Via asynchronous calls to the servlet, the UI will be able to display autocomplete suggestions as the user types, as well as display search results without the need for a page reload.

Mapped against our proposed features, the following is an initial API design currently pending the approval of the Servlet Team. The design is subject to change as our understanding of the application and its respective requirements grow.

Search: input search criteria, submit the search request, display the results

  • REST call: getResults
    • required parameters: String userInput
    • optional parameters:
      • String sortOrder: ‘asc’ or ‘desc’
        • Default: ‘desc’
      • String sortId: fieldname to sort by (pageRank, relevancy, alphabetically by title, etc)
        • Default: ‘pageRank’
      • Int limit: number of results to return
        • Default: 20
      • Int page: For paged results, what page to return (combined with the limit, the webservice team can calculate the result offset)
    • return: matching page objects as JSON arrays

Search autocomplete: show dropdown of suggested search inputs based on what the user is typing, ordered by popularity (how often the term is queried)

  • REST call: getKeywords
    • required parameters: String userInput
    • optional parameters:
      • Int limit: number of results to return
    • return: list of search strings as a JSON array

Result stats/analytics: show tooltip containing the page stats (relevancy, page rank, # visits, etc)

  • REST call: getStats
    • required parameters: int pageId or String pageUrl (depends on how the data is stored), String userInput (user’s original search term, so we can check the relevancy of this page for the specified search term)
      • return: array of statistics related to the page result
        ALTERNATIVELY, result stats can be returned as part of search result array

Page preview: the google-style preview where it shows the page when you over the result

  • REST call: getPage
  • required parameters: String pageUrl
  • return: array containing image of the page, text, whatever…
    • Not sure if we can grab a page preview directly from the result page using JavaScript or if we need to send a request to the server to have the servlet do it…

Plan

Plan assumes everything will progress smoothly. Schedule subject to change as things go wrong.

Week 7: Nov. 4 – Nov. 10

  • Create UI wireframes

Week 8: Nov. 11 – Nov. 17

  • Set content on page using jQuery (may be dummy content, depending on Servlet team’s progress), add placeholders for incomplete webservice calls

Week 9: Nov. 18 – Nov. 24

  • Fill in placeholders with working webservice calls, populate results with dynamic content, check for and fix bugs.

Week 10: Nov. 25 – Dec. 1

  • Fix bugs and resolve issues, if any. Otherwise, implement additional features as time-appropriate.

Finals Week: Dec. 2 – Dec. 8

  • Pretend it works. Hide unfixed bugs.

Responsibilities

Updated weekly based on progress made during the prior week.

Week 7: Nov. 4 – Nov. 10

  • Constance: Set up HTML5 Boilerplate and Bootstrap skeletons
  • Albert: Style wireframes
  • Raudel: Design logo/“branding”
⚠️ **GitHub.com Fallback** ⚠️