The Website
Table of contents
About ManoaBookSwap
Overview
The problem: Textbooks are expensive and used textbooks at a reasonable price are hard to find. While your friends may be a good source of used books to buy from, there are around 20,000 other students who could provide some deals.
The solution: Manoa Book Swap is a meteor application that provides a means for UH Manoa students to communicate their textbooks needs, whether they are selling or buying.
Users create profiles which show their major and courses taken. These profiles will allow users to have listings of books they are willing to sell as well as listings they may be interested in. When two users have met each others requirements, the buyer can accept the listing and the user holding the listing can schedule a meet up time and location for the transaction.
Credits
This idea was generated by Russell Omo and Raven Robles in ICS 314 Spring 2017
User Guide
When you come to the site, you will be first greeted with our landing page:
In order to utilize this service you must have a UH account. Upon clicking the login button, the UH CAS authentication screen appears and requests your UH account and password:
After being authenticated, you are greeted with your hompage, where you can find links to everything on this site:
In order to sell one of your textbooks you simply proceed to the sell page:
To find a book you look no further than our filter page:
Click on the title of a book to be directed to a full description page, including the seller’s contact information:
Installation
First, install Meteor.
Second, download a copy of ManoaBookSwap, or clone it using git.
Third, cd into the app/ directory and install libraries with:
$ meteor npm install
Fourth, run the system with:
$ meteor npm run start
If all goes well, the application will appear at http://localhost:3000. If you have an account on the UH test CAS server, you can login.
Application Design
Directory structure
The top-level directory structure contains:
app/ # holds the Meteor application sources
config/ # holds configuration files, such as settings.development.json
.gitignore # don't commit IntelliJ project files, node_modules, and settings.production.json
This structure separates configuration files (such as the settings files) in the config/ directory from the actual Meteor application in the app/ directory.
The app/ directory has this top-level structure:
client/
lib/ # holds Semantic UI files.
head.html # the <head>
main.js # import all the client-side html and js files.
imports/
api/ # Define collection processing code (client + server side)
base/
interest/
profile/
startup/ # Define code to run when system starts up (client-only, server-only)
client/
server/
ui/
components/ # templates that appear inside a page template.
layouts/ # Layouts contain common elements to all pages (i.e. menubar and footer)
pages/ # Pages are navigated to by FlowRouter routes.
stylesheets/ # CSS customizations, if any.
node_modules/ # managed by Meteor
private/
database/ # holds the JSON file used to initialize the database on startup.
public/
images/ # holds static images for landing page and predefined sample users.
server/
main.js # import all the server-side js files.
Import conventions
This system adheres to the Meteor 1.4 guideline of putting all application code in the imports/ directory, and using client/main.js and server/main.js to import the code appropriate for the client and server in an appropriate order.
This system accomplishes client and server-side importing in a different manner than most Meteor sample applications. In this system, every imports/ subdirectory containing any Javascript or HTML files has a top-level index.js file that is responsible for importing all files in its associated directory.
Then, client/main.js and server/main.js are responsible for importing all the directories containing code they need. For example, here is the contents of client/main.js:
import '/imports/startup/client';
import '/imports/ui/components/form-controls';
import '/imports/ui/components/directory';
import '/imports/ui/components/user';
import '/imports/ui/components/landing';
import '/imports/ui/layouts/directory';
import '/imports/ui/layouts/landing';
import '/imports/ui/layouts/shared';
import '/imports/ui/layouts/user';
import '/imports/ui/pages/directory';
import '/imports/ui/pages/filter';
import '/imports/ui/pages/landing';
import '/imports/ui/pages/user';
import '/imports/api/base';
import '/imports/api/profile';
import '/imports/api/interest';
import '/imports/ui/stylesheets/style.css';
Apart from the last line that imports style.css directly, the other lines all invoke the index.js file in the specified directory.
We use this approach to make it more simple to understand what code is loaded and in what order, and to simplify debugging when some code or templates do not appear to be loaded. In our approach, there are only two places to look for top-level imports: the main.js files in client/ and server/, and the index.js files in import subdirectories.
Note that this two-level import structure ensures that all code and templates are loaded, but does not ensure that the symbols needed in a given file are accessible. So, for example, a symbol bound to a collection still needs to be imported into any file that references it.
Naming conventions
This system adopts the following naming conventions:
- Files and directories are named in all lowercase, with words separated by hyphens. Example: accounts-config.js
- “Global” Javascript variables (such as collections) are capitalized. Example: Profiles.
- Other Javascript variables are camel-case. Example: collectionList.
- Templates representing pages are capitalized, with words separated by underscores. Example: Directory_Page. The files for this template are lower case, with hyphens rather than underscore. Example: directory-page.html, directory-page.js.
- Routes to pages are named the same as their corresponding page. Example: Directory_Page.
Data model
The Manoa Book Swap data model is implemented using Javascript classes.
CSS
The application uses the Semantic UI CSS framework. To learn more about the Semantic UI theme integration with Meteor, see Semantic-UI-Meteor.
The Semantic UI theme files are located in app/client/lib/semantic-ui directory. Because they are located in the client/ directory and not the imports/ directory, they do not need to be explicitly imported to be loaded. (Meteor automatically loads all files into the client that are located in the client/ directory).
Routing
For display and navigation among its four pages, the application uses Flow Router.
Routing is defined in imports/startup/client/router.js.
Authentication
For authentication, the application uses the University of Hawaii CAS test server, and follows the approach shown in meteor-example-uh-cas.
When the application is run, the CAS configuration information must be present in a configuration file such as config/settings.development.json.
Anyone with a UH account can login.
Authorization
The landing page is public; anyone can access this page.
All other pages require authorization. You must be authenticated via the UH test CAS server. Pages are accessed using the authenticated username which is then specified within the URL.
To prevent people from accessing pages they are not authorized to visit, template-based authorization is used following the recommendations in Implementing Auth Logic and Permissions.
Configuration
The config directory is intended to hold settings files. The repository contains one file: config/settings.development.json.
The .gitignore file prevents a file named settings.production.json from being committed to the repository. So, if you are deploying the application, you can put settings in a file named settings.production.json and it will not be committed.
ManoaBookSwap checks on startup to see if it has an empty database in initialize-database.js, and if so, loads the file specified in the configuration file, such as settings.development.json. For development purposes, a sample initialization for this database is in initial-collection-data.json.
Quality Assurance
ESLint
BowFolios includes a .eslintrc file to define the coding style adhered to in this application. You can invoke ESLint from the command line as follows:
meteor npm run lint
ESLint should run without generating any errors.
Development History
Milestone 1 - Mockup Development
(April 4, 2017 - April 13, 2017)
The goal of this milestone was to create a mockup of the entire project. We would be using Meteor as a means of creating this.
Milestone 1 was implemented as ManoaBookSwap GitHub Milestone M1:
Milestone 1 consisted of 8 issues, and progress was managed via the ManoaBookSwap Github Project 1:
Landing Page
Home Page
Profile Page
Filter Page
Sell Page
FAQ Page
Contact Us Page
Each issue was implemented in its own branch, then merged to master when completed:
Milestone 2 - Data Model Development
(April 13, 2017 - April 27, 2017)
The goal of Milestone 2 was to implement the data models for the profile and books collection, along with the addition of class listings, a general UI overhaul, and overall functionality. The data model will be implemented as a set of Javascript classes. Form submission along with database interaction were be given to our pages. Overall, our application now has some functionality to its pages that the user can interact with.
Milestone 2 was implemented as ManoaBookSwap Github Milestone M2:
Milestone 2 consisted of 7 issues, and progress was managed via the ManoaBookSwap Github Project 2:
Each issue was implemented in its own branch, then merged to master when completed:
Milestone 3 - Testing and Feedback
(April 27, 2017 - May 9, 2017)
The goal of Milestone 3 is to implement the rest of the functionality that we were unable to implement in Milestone 2. We also will be beginning our testing and receiving feedback from users.
Milestone 3 is implemented as ManoaBookSwap Github Milestone M3:
Milestone 3 consists of 10 issues, and progress is managed via the ManoaBookSwap Github Project 3:
Each issue was implemented in its own branch, then merged to master when completed:
Milestone 4 - Post
(May 9, 2017 - Onwards)
The goal of Milestone 4 is to finish all remaining issues and offer a fully functional site. We hope to be able to implement all of the feedback that we recieved from the last milestone.
Milestone 4 is implemented as ManoaBookSwap Github Milestone M4:
Milestone 4 consists of 4 issues, and progress is managed via the ManoaBookSwap Github Project 4:
