General Intro

Manifold is a tool not directed towards developers or hobbyists, but actual owners of things. It is a platform that owners of IoT things can use to manage their stuff, from phones and smart watches to knives and blenders. Manifold interfaces with the pico engine (you will see later on how it actually does this) and essentially just displays and interacts with the picos on that engine in a way that makes sense in the context of the Internet of Things. For example, owners shouldn't need to know anything about channels, or eci's, or even what a ruleset is. From their point of view, they have a physical thing and want to manage it via Manifold and see that digital representation actually behave the way it should. i.e. a blender should be able to blend things, turn off remotely if it has the capability to do so, and even interact with other things in the kitchen if needed. As another example, you can imagine that I want my air conditioning to turn on as soon as my car is close enough to my house in the summer. An owner would set up that interaction using Manifold, but the technical process of how everything actually works is abstracted away.

Web Programming

If you are familiar with how web programming works, skip to the next section.

In web programming, there is a front end and a back end. As a user, you experience this all the time when you use a browser. Everything you physically see and interact with in a browser when you visit a website is the front end. It is the look and feel of a website. When you type some url into your browser, it retrieves a bunch of html, css, and javascript files that are shown as the user interface (UI). But all that display is useless without any information to actually fill the website. That is where the backend comes in. A web app requests information from a server to actually supply the data to the user. When the user wants to perform an action, like adding a cool new thing to your Amazon shopping cart, the front end will communicate with the server (the back end) to actually get that done. 

If your understanding of web programming is pretty shaky, we recommend you read more about it. There are many good introductions on web programming, like this one. Just google more info on how Web Programming works in general.

Manifold is a front end single page application (SPA). The pico engine is the backend, supplying information about the IoT things an owner cares about.

Chrome DevTools

We use many different packages in Manifold, which will be explained in the sections below. There are also many different developer tools that have chrome extensions to debug easier. Here are the different extensions we recommend installing to make your life easier:

1. React Developer Tools (This allows you to not inspect the page as html, but as the react components that the page was rendered from)
2. Redux DevTools (This allows you to view the redux store and see the actions dispatched as they happen, as well as seeing how it affects the store from running the reducers)
3. Clear Session (This is useful for quick logout, but was more helpful when we were debugging the login process itself. Now it is more optional)

One important note: Redux DevTools requires a code modification in order to allow the browser to freely view the redux store. The code is located in index.js:

const store = createStore(
  reducers,
  window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__(),//this line enables Redux DevTools
  applyMiddleware(promise, sagaMiddleware)
)

CoreUI

To jumpstart our project and avoid having to write everything from scratch, we found a boilerplate project that came with the general look and feel we want for Manifold (minus the functionality of course). CoreUI is a free template for a general use, admin style web app. It comes written using many different options of JavaScript framework libraries, such as React.js, Angular 2+, Vue.js, and Angular. We decided to use React.js to take advantage of React Fiber (React v. 16.0.0), which has high speed and performance. There is no other real reason for why the other options would not have worked, (except Angular 1, which is deprecated). Here is the github repository for CoreUI: https://github.com/coreui/coreui-free-bootstrap-admin-template.

Create React App

One extremely important thing to realize is that CoreUI used another repository called Create React App, which is a boilerplate for React apps developed by Facebook. The README.md file is largely made up of the Create React App README.md. Create React App provides many different functionalities, including the Jest component tester and babel by default. Even though we cloned the repository some time ago, the README.md contains information on how to update our existing project to current versions of Create React App, which essentially updates all of our dependency tools without us having to do so.

React and Redux

For reference, here is the React website: https://reactjs.org/, and the Redux website: https://redux.js.org/.

React

React.js is a javascript framework that Manifold uses to structure the entire application. It was designed and is still maintained by Facebook. This page is not an in-depth description of React or how to actually program using it, but a useful resource is provided for Pico Labs employees at Udemy, which is an online resource that hosts courses for all sorts of subjects. Contact others in Pico Labs for access to Udemy courses.

Redux

When programming a large application like Manifold in React, it can quickly become a complex project with all sorts of bits of information to keep track of. For example, let's say an owner has three dozen things, anything from their car to their basement sink, that they are using Manifold to manage. Each of those things has all sorts of information that Manifold may need to keep track of and share throughout the entire application. As a result, it needs somewhere to keep track of global information. That is where Redux comes in. Redux defines a way to store and modify global information for the application.

Redux is not inherently built into React. In fact, it was created separately and can even be used with other javascript frameworks. It is not called a framework, but rather called a store (because just like a grocery or clothing store, it houses all the different information you would want for your app).

What is a JavaScript Framework?

This wikipedia article is helpful to understand what a framework is. To sum it up, a framework is essentially a library of code that you include in your project. It differs from a normal library, however, because it isn't just a useful tool that your code will call functions on. Rather, it defines the entire structure of how you are going to build your application in the first place. If you are building an app using React.js, you have to think like a React programmer, not a normal javascript developer who is just calling some functions. The same goes for the other popular frameworks out there.

Redux Middleware

Redux middleware is a useful way to add more complex functionality to Redux, and is a more advanced subject. Before reading this section, make sure you understand how redux works. They are especially useful for async actions where we need information from the pico engine. They intercept Redux actions before they hit the reducers, perform some processing, and then finally give the result back to the reducer.

redux-saga

redux-saga is a more complex system to explain, and is out of scope of this page. The simple version is that it allows for complex async actions to happen when we make HTTP calls. In Manifold, we use redux-saga for an exponential backoff implementation that would not be feasible with redux-promise.

redux-promise

redux-promise is a very simple middleware that can handle most simple async actions. It intercepts actions going through the redux store if that action returns an object with the key "payload" whose value is a promise. All redux-promise does is force the promise to resolve before going to the reducer.

Webpack

Webpack is first and foremost a module bundler. What is a module bundler? Essentially, a module bundler tries loading your project from its root file, like index.js. From there, it branches out and looks at all the files that are imported in that file. An import is where a file declares that it needs code from another file. Here's an example:

import React from 'react';

The above code declares a new local variable (local to the current file) called React, which is the result of an export default statement found in the 'react' file. You will learn about this in the Udemy course. Webpack looks at those imports and branches into that file to look at that file's dependencies. As it traverses this big tree of dependencies, it compares that file with configuration settings to know how to parse/compile/bundle the file. You will not need to do anything with webpack besides knowing generally how it works. Browsers don't understand most of the code and project structure that happens in projects. Generally, browsers only understand pure javascript, so module bundlers take a project and build it into a single bundle file with browser friendly javascript.

Webpack also provides some other features that are really useful, like hot reloading. Whenever we make a change to a file and save it in our text editor, webpack will notice the change and update the browser with your new change without you ever having to refresh the webpage.

Here's a good article on bundling: https://www.sitepoint.com/javascript-modules-bundling-transpiling/