Skip to content

Latest commit

 

History

History
587 lines (419 loc) · 21.3 KB

UserGuide.adoc

File metadata and controls

587 lines (419 loc) · 21.3 KB

LiBerry - User Guide

By: AY1920S1-CS2103T-F13-1 Since: Sep 2019 Licence: MIT

1. Introduction

LiBerry is a desktop app for librarians to quickly manage their community libraries! LiBerry is optimized for librarians who prefer to work with a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). You can type quickly and serve your long line of borrowers in a short amount of time.

LiBerry can manage all your books and borrowers efficiently and meticulously. You can easily add new books to your library records, register new borrowers, loan out books, track outstanding fines and more!

This user guide will introduce to you the different features of LiBerry and how to use them! Jump to Section 3, “Quick Start” to get started now! Enjoy!

2. Legend

💡
 Denotes useful tips.
Important
 Denotes important details to take note of.

3. Quick Start

Dive into LiBerry with our simple set-up guide for a quick tour of our user interface and features!

  1. Ensure you have Java 11 or above installed in your Computer.

  2. Download the latest LiBerry.jar here.

  3. Copy the file to the folder you want to use as the home folder for your LiBerry.

  4. Double-click the file to start the app. The GUI should appear in a few seconds.

    annotated ui
    Figure 1. Components of LiBerry’s User Interface (UI)

  5. The UI of LiBerry consists of 5 main components.

    1. The command box where you input commands to interact with the software.

    2. The command results display which provides feedback for your inputs.

    3. The displayed book list which displays all the books in LiBerry’s catalog and also search results.

    4. The borrower panel which displays information about a borrower and his/her borrowed books when LiBerry is in Serve mode.

    5. The mode indicator which indicates if LiBerry is in Normal mode or Serve mode.

  6. Type the command in the command box and press Enter to execute it.
    e.g. typing help and pressing Enter will open the help window.

  7. Here are some commands you can try out:

    1. Add a new book to LiBerry by using add t/Animal Farm a/George Orwell

    2. Register a new borrower to LiBerry by using register n/John Smith p/97875454 e/[email protected]

  8. Refer to Section 4, “Features” for details of each command.

4. Features

This section contains a detailed guide to every feature LiBerry supports, including how to use and the format of the commands to use the feature. The following table shows the format used to describe each command.

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in find t/TITLE, TITLE is a parameter which can be used as find t/Harry Potter.

  • Items in square brackets are optional. E.g. t/TITLE [g/GENRE] can be used as t/Harry Potter g/fiction or as t/Harry Potter.

  • Curly brackets indicate that at least 1 of the optional parameters have to be given, e.g. { [t/TITLE] [a/AUTHOR] } can be used as t/Harry Potter

  • Items with …​​ after them can be used multiple times including zero times, e.g. [g/GENRE]…​ can be used as   (i.e. 0 times), g/fiction, g/fiction g/adventure etc.

  • Parameters can be in any order e.g. if the command specifies t/TITLE a/AUTHOR, a/AUTHOR t/TITLE is also acceptable.

4.1. Using Normal Mode

Normal Mode is for librarians to manage the books in the library. Commands in normal mode are not specific to any borrowers. Normal Mode also provides some utility commands to help the librarian use LiBerry. However, it is important to note that commands specific to Serve Mode cannot be used while in Normal Mode.

4.1.1. Viewing help : help

Opens up a help window, which shows a summary of the list possible commands that you can execute.

HelpWindow
Figure 2. Screenshot of Help Window

The figure above shows a screenshot of the help window. The left side of the window shows the command while the right side of the window gives a description of the command and a usage example.

Format: help

4.1.2. Locating books by title: find

Shows all relevant books found.

Format: find [NUMBER] { [t/TITLE] [a/AUTHOR] [g/GENRE]…​ [sn/BOOK_SN] [-overdue] [-loaned] [-available] }
Format: find [NUMBER] { [t/TITLE] [a/AUTHOR] [g/GENRE]…​ [sn/BOOK_SN] [-overdue] [-loaned] [-available] [-rated] [-popular] [-new] } - Coming in v2.0

  • The search is case insensitive. e.g harry will match Harry

  • When searching by book titles and authors, partial words will also be matched e.g. Har will match Harry, J will match J K Rowling and Jin Yong

  • Books matching at least one keyword will be returned (i.e. OR search). e.g. harry will return both Harry Potter and Harry Botter

  • [NUMBER] will limit the search to NUMBER books

  • [t/TITLE] will be used to search through book titles

  • [a/AUTHOR] will be used to search through or filter by authors

  • [g/GENRE] will be used to search through or filter by genre

  • [sn/BOOK_SN] will be used to search through book serial numbers

  • Only 1 of the following 3 flags can be used

    • [-overdue] will only show overdue books

    • [-loaned] will only show loaned books

    • [-available] will only show available books

  • Adding one of the following will sort the books such that:

    • [-rated] will list the top 10 highly rated books - Coming in v2.0

    • [-popular] will list the top 10 most borrowed books - Coming in v2.0

    • [-new] will list the 10 newest books - Coming in v2.0

💡
 Inputs for g/GENRE is automatically capitalized.
💡
 t/TITLE and a/AUTHOR are matched by partial spellings. Search t/phil if you forgot how to spell 'Philosopher'!

Examples:

  • find t/Animal Farm a/George Orwell
    Searches for the book titled “Animal Farm” by the author “George Orwell”.

  • find 3 g/mystery g/children -available
    Searches for children mystery books that are not on loan and show the first 3 entries.

4.1.3. Viewing a book’s information: info

Views more information about a book in the displayed list.
The information displayed includes:

  • Title of book

  • Genres of book, if any

  • Serial number of book

  • Author of book

  • Loan status of book

  • Loan history of book
     

Format: info INDEX

The figure below shows how an info window might look like.

infowindow
Figure 3. Info window of a selected book

In the window above, we can see that information related to the book 'Man’s Search for Munning' is displayed in a viewable window.

4.1.4. Clearing all entries : clear

Clears the most recent search from the displayed book list and displays all books.

Format: clear

4.1.5. Adding a book: add

Adds a new book to library records.

Format: add t/TITLE a/AUTHOR [sn/BOOK_SN] [g/GENRE]…​

  • Adds a book with the title TITLE, written by AUTHOR, classified by the genres GENRE and tagged with the serial number BOOK_SN.

  • TITLE should be at most 50 characters long.

  • AUTHOR should be at most 50 characters long.

  • GENRE, if provided, should be at most 20 characters long.

  • BOOK_SN, if provided, must be a valid serial number that starts with the prefix 'B' followed by 5 digits. They should be unique.

💡
 A book can have up to 5 genres (but can have no genres as well).
💡
 You do not need to specify the serial number if you wish so.
LiBerry will then auto-generate a valid serial number for the new book.

Examples:

  • add t/Harry Botter a/Raylei Jolking sn/B02010 g/children
    Adds a children book titled "Harry Botter" by "Raylei Jolking", with the serial number "B02010", to LiBerry.

  • add t/Inferno a/Tande g/classic g/epic Adds a book titled "Inferno" by "Tande", with the genres "classic" and "epic" to LiBerry. The serial number for this book will be automatically generated.

4.1.6. Deleting a book : delete

Deletes a book from the library records. Used when book is lost or trashed.

Format: delete INDEX or delete sn/BOOK_SN

  • Deletes the book at the specified INDEX.

  • INDEX refers to the index number shown in the displayed book list.

  • INDEX must be a positive integer 1, 2, 3, …​

  • delete INDEX will delete the book with the book at INDEX position in the results list.

  • delete sn/BOOK_SN will delete the book with this serial number.

Examples:

  • find t/harry
    delete 1
    Deletes the 1st book in the results of the find command.

  • delete sn/B00422
    Deletes the book with serial number sn/B00422.

4.1.7. Registering a new borrower: register

Registers a new borrower to the library records. A unique ID associated with the borrower will automatically be generated and displayed. Borrowers are expected to know his ID in order for loans to be processed.

Format: register n/NAME p/PHONE_NUMBER e/EMAIL

Example:

4.1.8. Unregistering a borrower: unregister

Unregisters and removes a borrower with the given borrower ID from the library records.

Format: unregister id/BORROWER_ID

Example:

  • unregister id/K0001
    Deletes the borrower with the borrower ID id/K0001

4.1.9. Undoing mistakes: undo

Undoes the previous command/action. This command only works for commands that modifies the catalog, loan records, borrower records or user settings.

Undoable Commands:

  • add, delete, edit, loan, register, renew, return, set, toggleui and unregister.

Important
 After every serve, done or pay command, all previous state would be cleared. This means that you would not be able to undo to the state before the serve, done or pay command.
💡
 Check the commands you made and ensure that they are correct before entering a serve, done or pay command.

Format: undo

4.1.10. Redoing undone commands : redo

Redoes the most recent command that was undone. This command only works if there are undone commands.

Important
 Once a new undoable command is entered, you may not redo previously undone commands.

Format: redo

4.1.11. Setting User Settings: set

Sets the user settings of the application.

Format: set [lp/LOAN_PERIOD] [rp/RENEW_PERIOD] [fi/FINE_INCREMENT] [mr/MAX_RENEWS]

  • Updates the user settings with the specified LOAN_PERIOD, RENEW_PERIOD, FINE_INCREMENT and MAX_RENEW.

  • All the fields that are specified must be a positive integer.

  • If none of the fields are specified, the current user settings would be displayed.

  • LOAN_PERIOD refers to the number of days that a book can be loaned out for.

  • RENEW_PERIOD refers to the number of days that the loan can be extended for.

  • FINE_INCREMENT refers to the amount of cents charged per day for each overdue book.

  • MAX_RENEWS refers to the maximum amount renewals that can be made per loaned out book.

Examples:

  • set
    Shows the current user settings.

The yellow box in the figure below is what you will see after entering the set command.

ViewSettingsCommand
Figure 4. User interface after set to used to view current user sittings

  • set lp/7 rp/7 fi/5 mr/2
    Sets the loan period to 7 days, renew period to 7 days, fine increment to 5 cents per day and maximum renews allowed to 2.

BeforeSetCommand
Figure 5. User interface before set command is executed.

The figure above shows the user interface before the set command is executed. The yellow box shows the set command that is being entered.

AfterSetCommand
Figure 6. User interface after set command is executed.

After entering the set command, the user settings would be updated. The updated user settings will then be displayed in the result display as shown in the yellow box in the figure above.

4.1.12. Toggling dark mode : toggleui

Toggles between light mode and dark mode for the UI.

Format: toggleui

4.1.13. Rating a book : rate - Coming in v2.0

Gives a book a numerical rating.

Format: rate INDEX r/RATING

4.1.14. Exiting the program : exit

Exits the program.

Format: exit

4.1.15. Entering Serve Mode: serve

Enters Serve Mode. All commands/actions will be done on this specific borrower. A list of the borrower’s currently loaned books and their serial numbers will be displayed.
Borrower ID is used as the borrower will produce their library card which contains their ID to the librarian to be served.

Format: serve id/BORROWER_ID

Example:

  • serve id/K0001
    Enters save mode to serve a borrower with the ID K0001

4.2. Using Serve Mode

The Serve Mode is for librarians to serve borrowers. All commands in Serve Mode are done on a specific borrower currently served by the librarian. All commands in Normal Mode, except for serve and exit, can be used in Serve Mode too. The command unregister cannot be used on the currently serving borrower.

4.2.1. Exiting Serve Mode: done

Exits Serve Mode.

Format: done

After loaning all books, upon the done command, a printable loan slip in pdf format will be generated. The loan slip will be opened in your computer’s pdf viewer and also saved in the loan_slips folder. The figure below shows an example of how a loan slip might look like.

LoanSlip
Figure 7. Printable loan slip generated.

In the figure above, we can see that the loan slip records all the books borrowed by 'Bill'.

4.2.2. Editing a borrower: edit

Edit borrower’s particulars.

Format: edit { [n/NAME] [p/PHONE_NUMBER] [e/email] }

  • Edits the currently serving borrower’s particulars.

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

Examples:

  • edit p/91234567 e/[email protected]
    Edits the phone number and borrower’s email address to be 91234567 and [email protected] respectively.

  • edit n/Betsy Crower
    Edits the name of the borrower to be Betsy Crower.

4.2.3. Loaning book(s): loan

Loan book(s) to the currently served borrower.
The serial number of the book is used as the borrower would bring the physical copy of the book they want to borrow to you. Thus, you do not have to search for the index of the book in the displayed book list.

Format: loan sn/BOOK_SN
Format: loan sn/BOOK_SN [sn/BOOK_SN]…​ - Coming in v2.0

Examples:

  • loan sn/B00006
    You loan out the book with serial number B00006 to the currently served borrower.

    ug loan pic
    Figure 8. The user interface after the book is loaned out.

    After this command is entered, the command results display will provide you with a summary of which book is loaned out and tho who it is loaned to. As seen from the screenshot, the book will also be added to the list of currently loaned out books in the borrower’s panel on the right. Inside the main list on the left, an on-loan box would also indicate this book as being loaned out.

  • loan sn/B00201 sn/B02929 sn/B00203 - Coming in v2.0
    You loan out the books with serial numbers B00201, B02929 and B00203 to the currently served borrower.

4.2.4. Returning book(s): return

Return book(s) that were loaned by the borrower.
Fine incurred for late returns will automatically be calculated and added to the borrower’s total outstanding fines.

Format: return INDEX or return -all

  • Returns the book at the specified INDEX in the borrower panel or -all of the currently served borrower’s loaned out books.

  • INDEX indicates the book at this index number shown in the borrower’s book list on the right side of the UI. The index must be a positive integer such as 1, 2 or 3, and must appear in the borrower panel.

  • -all indicates all the books currently loaned out by the borrower.
     

ug return
Figure 9. Screenshot to illustrate the return commands that can be entered.

  • Referring to the above screenshot as an example, entering return 1 would successfully return the book "Stefe Jobz". However, entering return 3 would be invalid as there’s no book at index 3 in the borrower panel. Entering return -all would return all of Bobby’s loaned out books, which are "Stefe Jobz" and "Behaves".

4.2.5. Renewing book(s): renew

Renew book(s) that are still loaned by the borrower, i.e., extend their due dates.

Format: renew INDEX or renew -all

  • Renews the book at the specified INDEX in the borrower panel or all of the currently served borrower’s loaned out books that can still be renewed.

  • INDEX indicates the book at this index number shown in the borrower’s book list on the right side of the UI. The index must be a positive integer such as 1, 2 or 3, and must appear in the borrower panel.

  • -all indicates all the books currently loaned out by the borrower that still can be renewed.

  • You cannot renew overdue books or books that have reached the maximum renew count.

  • If you just loaned out or renewed a book, you cannot renew that same book in the same Serve mode session.

4.2.6. Paying fines: pay

Receive AMOUNT (in dollars and up to 2 decimal places) from the currently served borrower to pay off his/her outstanding fines.

Format: pay $AMOUNT

Examples:

  • pay $12.80
    You receive $12.80 from the borrower to pay off his/her fine.

    ug pay
    Figure 10. The command results display after paying fines.

    As seen from the screenshot above, after a fine amount is paid, a summary can be seen. You will see any outstanding fine the borrower still has. If the borrower pays an amount greater than his/her total outstanding fine, you can refer to the change given line to see how much change you should return to the borrower.

  • pay $5
    You receive $5 from the borrower to pay off his/her fine.

4.2.7. Reserving a book: reserve - Coming in v2.0

Reserve a particular book for the borrower.

Format: reserve INDEX or reserve sn/BOOK_SN

  • Reserves the book at the specified INDEX or the book with the specified serial number BOOK_SN for the currently served borrower.

  • INDEX indicates the book at this index number shown in the displayed book list. The index must be a positive integer such as 1, 2 or 3, and must appear in the displayed book list.

  • sn/BOOK_SN indicates the particular book with this serial number.

Examples:

  • reserve 2
    Reserves the 2nd book shown in the displayed book list for the currently served borrower.

  • reserve sn/B02422
    Reserves the book with serial number sn/B02422 for the currently served borrower.

4.3. Saving the Data

LiBerry data are saved in the hard disk automatically after any command that changes the data. There is no need to save manually.
Data saved should not be manually edited to prevent files from being corrupted.

5. FAQ

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous LiBerry folder.

6. Command Summary

This section contains the summary of LiBerry’s commands.
Commands applicable to both Normal and Serve mode:

  • Help : help

  • Find a book : find [NUMBER] { [t/TITLE] [a/AUTHOR] [g/GENRE]…​ [sn/BOOK_SN]] [-overdue] [-loaned] [-available] }
    e.g. find t/Animal Farm a/George Orwell, find 3 g/mystery g/children -available
    [-rated] [-popular] [-new] - Coming in v2.0

  • View book info : info INDEX

  • Clear results : clear

  • Add a book : add t/TITLE a/AUTHOR sn/BOOK_SN [g/GENRE]…​ `
    e.g. `add t/Harry Botter and the Baby’s Potty a/Reali Jolking sn/B02010 g/children

  • Delete a book : delete INDEX or delete sn/BOOK_SN

  • Register a borrower : register n/NAME p/PHONE_NUMBER e/EMAIL
    e.g. register n/matt p/83938249 e/[email protected]

  • Unregister a borrower : unregister id/BORROWER_ID

  • Undo : undo

  • Redo : redo

  • Set user settings: set [lp/LOAN_PERIOD] [rp/RENEW_PERIOD] [fi/FINE_INCREMENT] [mr/MAX_RENEWS]

  • Toggle UI theme: toggleui

  • Rate a book : rate INDEX r/RATING - Coming in v2.0

  • Exit : exit

  • Enter Serve mode : serve id/BORROWER_ID
    e.g. serve id/K0001

Commands applicable to Serve mode only:

  • Exit serve mode : done

  • Edit a borrower’s particulars : edit { [n/NAME] [p/PHONE_NUMBER] [e/email] }
    e.g. edit p/91234567 e/[email protected]

  • Loan book : loan sn/BOOK_SN
    e.g. loan sn/B00201

  • Return book(s) : return INDEX or return -all

  • Renew book(s) : renew INDEX or renew -all

  • Pay fines : pay $AMOUNT

  • Reserve book : reserve INDEX or reserve sn/BOOK_SN - Coming in v2.0