masaq.com

maSAQ.com

Découvrez vos goûts


Synopsis
Strategy
      core strategy
      on using React
Installation
Development
Documentation
Maintainer

Synopsis

maSAQ.com is a prototype search interface to ease product discovery for all SAQ’s clients, using the Coveo REST API. This project originated from a technical challenge which was part of the front-end developer interview process at Coveo.

The challenge has been accepted, and there is only a french version for now.

Strategy

core strategy

Manage the whole application state based on the window.location.hash
(based on a recent book I read).

More precisely, as the user navigates into the website and trigger an event dictating the client to get new information from the Coveo rest API, the hash is updated consequently, which is then parsed to a JSON object meant to be sent as the body of a POST request made to the Coveo REST API, out of which a response is received by the client, and interpreted to update the UI with the new information received. Six main behaviors can cause the hash to update (there are others, but these are the most important):

User searches for a new product -> client updates hash -> client parses hash to JSON -> client sends POST request to Coveo API with hash-JSON as body (and extra, constant rest parameters also contained in the JSON body) -> information is received by the client, interpreted and passed to the main React component, which passes the proper information to its children to update the UI

User checks/unchecks a filter -> ...(same sequence)... ->

User resets filters -> ...(same sequence)... ->

User clicks on a new sort criteria -> ...(same sequence)... ->

User clicks on load more results button -> ...(same sequence)... ->

User goes back/advances in the browser history -> ...(same sequence)... ->

No local storage or other strategies are used to manage page refresh or second+ visits for now. When this occurs, the app is currently reloaded to its initial state.

on using React

The app is based on React mainly to build the UI components and to provide a rather simple way to manage the data flow (as explained in the core strategy). The component tree resembles the following:

MaSAQ
	Header
		HeaderTitle
		SearchBar
		SortSection
			SortCriteria<List>
	
	Aside
		ResetFiltersButton (currently not a component)
		FiltersForm
			FilterCategory<List>
				Checkbox<List>
	ProductsGrid
		NumberOfResultsFound (currently not a component)
		DidYouMeanMessage (currently not a component)
		ProductCard<List>
			Chip<List>
			MaterialButton (currently a component but not used as such in ProductCard)
			AccordsDialog
		ErrorCard
		MoreResultsButton (currently not a component)
		ToTopButton (currently not a component)
	Footer (currently not a component)

When indicated as currently not a component, this means you won’t find the actual component with that name in the project folder, but you will find it in its, unnamed, html format inside their parent component. The indication in the above schema means we believe this should be a component in itself, but is currently not.

Each component is named as presented in the schema in the project folder at _root_/src/components. Each component possesses its own stylesheet with the same name at _root_/src/styles, and its own test file with the same name at _root_/src/tests. It may however be possible that the styles of parent elements may be used in their children. If you do not find a rule you want to edit in the component’s style, you may want to climb up the component tree to find which component is containing the rule. As a rule of thumb, some utility rules (hide, show components) can be found at the root component MaSAQ.

Installation

Step 1: Prerequisites

First, make sure you have the following installed on your computer: Node.js, Npm, and Git.

Step 2: Clone the github repository

Move to an empty directory on your computer and clone the github repository with the following command:

git clone https://github.com/MichelML/masaq.com.git

After this command is executed, move to the local directory created with the following command:

cd masaq.com

Step 3: Install node dependencies

To install all the node modules dependencies for the project, run the following command on your computer:

npm install

This could take a few minutes or less, and you are now ready to contribute to the application.

Development

All source files are located at _root_/src, excepts for assets and the index.html file that are located at _root_/public. These files are the ones to be edited before building the production version of the app.

maSAQ.com started with create-react-app, helping you start the creation of applications with React, along with automated unit tests, with very minimal configuration.

Out of the box, create-react-app comes with great technologies and pre-built scripts helping you start being productive in no time (see create-react-app site or development section of the technology stack section). Here is an overview of each script and its function:

Disclaimer: following descriptions are greatly inspired by the create-react-app documentation.

Along with the React components, the application uses other modules provided in the _root_/utils folder to create a nice UI:

To get you started, you can view the issues currently remaining to be solved. You can also provide fixes for issues specified in the on using React section.

Documentation

more detailed documentation coming soon. Meanwhile, please see the strategy, and development section.

Technology stack

As of the last edit of this README, maSAQ.com is mostly supported by the following technologies:

Design

DOM manipulation and User interface

Development

Testing

DISCLAIMER: very minimal testing has been made so far. More unit tests (a lot more), remain to be added.

API

Utilities

Maintainer

Michel Moreau - michel.moreau.lapointe@gmail.com

This site is open source. Improve this page.