Repository files navigation

This repository is an educational resource for Angular v1 experts that are looking to learn React/Redux. A contrived sample application for managing basic patient information is provided using both technologies' best practices (look undersamples/ to see both versions). This application (demonstrated below) will be referred to below as we explore the key philosophical differences between Angular v1 and React/Redux so that you can get coding!

Once the technologies for a project are chosen, the next step is to figure out how to scaffold and build the application using production-ready practices. Angular v1 applications are typically wired together using a mixture ofNPM andBower (dependency management) andGrunt orGulp (build tooling). In the React/Redux world, NPM andWebpack are the way to go (this repo uses and recommends thereact-redux-starter-kit which incorporates these technologies).

Scaffolding a project in React/Redux isn't very different from what is typically done in Angular v1 (with some exceptions to theJohn Papa styleguide). Here's thetree output of both samples in this repository:

                 Angular v1                                           React/Redux                ------------                                         -------------├── app.module.js                                      ├── common├── common                                             │   ├── CustomValidators.js│   ├── ssn.filter.js                                  │   ├── Formatters.js│   └── tel.filter.js                                  │   ├── FormsyDatePicker.js├── patient                                            │   ├── FormsyInput.js│   ├── demographics                                   │   └── FormsyMaskedInput.js│   │   ├── basic                                      ├── containers│   │   │   ├── basic.info.controller.js               │   └── AppContainer.js│   │   │   ├── basic.info.directive.js                ├── index.html│   │   │   ├── basic.info.view.html                   ├── layouts│   │   │   └── basic.module.js                        │   └── CoreLayout│   │   ├── contact                                    │       ├── CoreLayout.js│   │   │   ├── contact.info.controller.js             │       ├── CoreLayout.scss│   │   │   ├── contact.info.directive.js              │       └── index.js│   │   │   ├── contact.info.view.html                 ├── main.js│   │   │   └── contact.module.js                      ├── routes│   │   ├── demographics.controller.js                 │   ├── index.js│   │   ├── demographics.directive.js                  │   └── Patient│   │   ├── demographics.module.js                     │       ├── Demographics│   │   └── demographics.view.html                     │       │   ├── Basic│   ├── patient.controller.js                          │       │   │   └── BasicComponent.js│   ├── patient.html                                   │       │   ├── Contact│   ├── patient.module.js                              │       │   │   └── ContactComponent.js│   └── patient.service.js                             │       │   │└── index.html                                         │       │   ├── PatientDemographicsComponent.js                                                       │       │   └── PatientDemographicsContainer.js                                                       │       ├── index.js                                                       │       └── PatientModule.js                                                       ├── store                                                       │   ├── createStore.js                                                       │   ├── location.js                                                       │   └── reducers.js                                                       └── styles                                                           ├── _base.scss                                                           └── core.scss

Notice how everything isorganized in modules as opposed to a flat directory approach. This is a best practice that helps one organize a complex user interface while still sharing generic pieces.

Now that the file structure (hopefully) makes sense, one can go back a directory and run the build tool (you won't find major differences between gulp/grunt and webpack). In our case, it'sgrunt serve andnpm start for Angular v1 and React/Redux samples, respectively.

The heart of Angular v1 is with directives. These discrete interfaces take in 1 and 2-way data parameters and inject services that really power up your view. Fortunately, directives are not that different from Redux-aware React components. Moreover, the stuff inside of React components can be easily translated from Angular v1 concepts (this repo won't go into those details, as they are easily "Googleable"... for instance Google"React equivalent for ng-repeat" to see for yourself).

In Angular v1, directives are typically introduced in views that are controlled by route-level controllers. In React/Redux, components are introduced in the same way, however, a container must be placed in the middle so that the component (also known as asmart component, in this case) can get application-wide state. The container will also bring in functions from upper level services that child components will use. These topics (application-wide state and upper level services) will be explained later in the guide.

As mentioned before, Redux has to bind its store to child React components in a container. In our application, theroutes/Patient/Demographics/PatientDemographicsContainer.js puts references to the Redux state like so (code simplified for sake of demonstration):

constmapStateToProps=(state)=>({patientInContext:state.patient.patientInContext,basic:state.patient[state.patient.patientInContext].basiccontacts:state.patient[state.patient.patientInContext].contact})

One other important thing that is done in this container is the binding of Redux-aware service functions (formally known as "action creators") like so:

constmapDispatchToProps={  setPatientInContext,  updatePatientData,  updateContactData,  deleteContact,  startAddingNewContact}

With these two mappings out of the way, child components can access the state and functions from above. Here are some highlighted examples of this inroutes/Patient/Demographics/Basic/BasicComponent.js:

Displaying data from the store in a table:

<tr><td><strong>SSN:</strong>{socialSecurityFormat(this.props.info.ssn)}</td><td><strong>Martial Status:</strong>{this.props.info.martialStatus}</td></tr>

Form edit reference to the SSN input (uses local component state instead of Redux store state - note thatFormsy is a popular form validation library):

<td><FormsyMaskedInputmask={[/\d/,/\d/,/\d/,'-',/\d/,/\d/,'-',/\d/,/\d/,/\d/,/\d/]}value={this.state.ssn}onChange={this.handleInputChange}validations={{isLength:9}}sanitizationFunction={this.sanitizeToJustNumbers}validationErrors={{isDefaultRequiredValue:'Valid SSN is required',isLength:'Valid SSN is required'}}name='ssn'label='SSN'required/></td>

Save function for the form that takes the local component state of the form and sends it to the Redux store for updating. Note thatupdatePatientData is passed from the parent container:

handleSubmit(formValues){// Convert dob back to date stringformValues.dob=formValues.dob.format('YYYY-MM-DD')this.props.updatePatientData(formValues)this.setState({showForm:false})}

At this point, you may be thinking"wait, why are you copying the data from Redux into the local state/form rather than using it directly? Isn't the point of Redux to encapsulateall application state?". Good question. As with most things in software engineering, it is always best to be able to break the rules when it's justified. Should state such as{ showForm: true/false } (determines whether to render the form or not) and{ cachedForm: this.props.info } (holds a cache of the form state if the user hits cancel) be put into the Redux store or just be local to the component? It depends. In our case, this state doesn't need to be application wide so Redux is only storing things that are domain-centric rather than domain-centric and UI-centric. These things will often come down to requirements and what the opinions are of your resident seasoned Redux enthusiast(s).

In Angular v1, application-wide state is put into services so that directive controllers can CRUD it. In React/Redux, all application-wide state is put into the store, an object tree. As shown in the above section, components access the store via containers and parent components passing it to them. Components can alter said state by invoking module functions (formally known as "action creators") that containers and parent components pass down.

One key difference between Angular v1 application-wide state in services and Redux store is that state mutation is not allowed. While this sounds weird and scary at first, youcan change this state but it must be done in a very specific way. The easiest way to think about this is whenever you update the store, you simply clone the object, mutate the clone to your heart's content, and send that to the store.

Think back to your Angular v1 directives that display information from a service that holds the state. When that service state changes, the directive will change the view to reflect said change. Similarly, Redux-aware React components will change when the store changes.

A key difference between the updating of the state in an Angular v1 service and in the Redux store is that you don't "talk" to the store directly. In order to get the store to respond to data changes, you must issue an action. Actions simply send data from your application to your store and then your app "reacts" (pardon the pun).

Recall that theroutes/Patient/Demographics/Basic/BasicComponent.js callsthis.props.updatePatientData(formValues) when it wishes to update basic patient information in the store. TheupdatePatientData function is defined in the moduleroutes/Patient/PatientModule.js (modules will be covered in the next section) that looks like this:

exportconstupdatePatientData=(data)=>{return(dispatch,getState)=>{returnnewPromise((resolve,reject)=>{console.debug(`updating basic patient data for${getState().patient.patientInContext}`)dispatch({type    :'UPDATE_PATIENT_DATA',payload :data})resolve()})}}

The important piece to focus on for now is thedispatch function. This function takes in something called an action. In our case, our action is of typeUPDATE_PATIENT_DATA and the payload is the new basic data.

When the action has been dispatched, something needs to handle it so that the store is updated. This is the job of the reducer. Reducers look at an inbound action and figure out how to update the store with the new information. For exampleroutes/Patient/PatientModule.js exposes the following reducer:

constinitialState=testDataexportdefaultfunctionpatientReducer(state=initialState,action){letresultletcopyswitch(action.type){case'UPDATE_PATIENT_IN_CONTEXT':copy=clone(state)copy.patientInContext=action.payloadresult=copybreakcase'UPDATE_PATIENT_DATA':copy=clone(state)copy[copy.patientInContext].basic=action.payloadresult=copybreakcase'UPDATE_CONTACT_DATA':copy=clone(state)constcontactIndexForUpdation=_.findIndex(copy[copy.patientInContext].contacts,(c)=>{if(c&&c.hasOwnProperty('id')){returnc.id===action.payload.id}})copy[copy.patientInContext].contacts[contactIndexForUpdation]=action.payloadresult=copybreakcase'INSERT_CONTACT':copy=clone(state)constlastContact=_.last(copy[copy.patientInContext].contacts)letnewContactId=0if(lastContact!=null&&lastContact.hasOwnProperty('id')){newContactId=lastContact.id+1}copy[copy.patientInContext].contacts.push({isNewContact:true,id:newContactId})result=copybreakcase'DELETE_CONTACT':copy=clone(state)constcontactIndexForDeletion=_.findIndex(copy[copy.patientInContext].contacts,(c)=>{if(c&&c.hasOwnProperty('id')){returnc.id===action.payload}})deletecopy[copy.patientInContext].contacts[contactIndexForDeletion]result=copybreakdefault:result=state}returnresult}

There is a good amount going on here, but the most important thing to focus on is thatstate variable. This is the application store. Because we areswitching on action types, the reducer will know to run the code in theUPDATE_PATIENT_DATA section. This code is simply making a copy of the store and editing it with the new basic information. At the end of the functionreturn result is called and the Redux store is updated.

What's interesting is that the reducer ispure in that no mutations were made to the original store becauseclone (a nice NPM module) copied the store to a new object.

In the last section, we learned thatroutes/Patient/Demographics/Basic/BasicComponent.js callsthis.props.updatePatientData(formValues) which dispatches an action to the reducer so that the store can be updated. You may be thinking"the module is just a place where actions are created and reducers run based on those actions". This is correct, but there is an additional piece worth pointing out. Modules can serve as a centralized place for logic to run before the store updates.

routes/Patient/Demographics/Contact/ContactComponent.js allows users to add a new contact. This data payload will eventually make it up to the module and the module may wish to perform an HTTPPOST to a server (note that our sample application doesn't do this) before saving the new contact information to the store. This logic is totally appropriate for the module function and would look something like this:

exportconststartAddingNewContact=(data)=>{return(dispatch,getState)=>{returnHttpPost(endpoint,data).then((response)=>{data.id=response.data.iddispatch({type    :'INSERT_CONTACT',payload :data})})})}}

You may be thinking"I see there's a mutation here (function is not pure)...data is getting anid added on, is that allowable?". The answer is "yes". Module functions can be asynchronous and have side effects. The important thing is that the reducer that will receive the action will be pure and synchronous.

Unit testing is not too much different than the approaches found in Angular v1.Karma,Mocha,Chai, andSinon are used as the test runner, framework, assertion library, and mocks/spies tools respectively.

The only philosophical difference that is notable is that tests assert items on the component view in React/Redux. This is typically not done in Angular v1 unit tests.

NOTE:v1.0.0 Didn't include unit tests for the Redux/React sample application (embarrasing, right?). The Angular v1 sample tests are in place, but we plan on doing the Redux/React tests inv1.0.1.

• React Component Lifecycle
• The Difference Between Virtual DOM and DOM
• 1-way vs 2-way Databinding
• Presentational and Container Components
• React Global Error Handling
• Redux Logger
• Redux Ducks File Structure
• React Logger
• ES6 Highlights
• React/Redux Router Tutorial
• Redux Middleware
• Redux Wes Box Redux Tutorials
• Master Redux Resources List

• MIT
• Victor Choueiri, who reviewed the code
• Manuel Bieh, who reviewed the code
• Google font used for header