Tea Leaves with jQuery

concepts & coding practices

Last time I wrote Tea Leaves with Rails and basic front-end. In order to have content loaded more smoothly, I updated the old Tea Leaves app using jQuery and JSON API.

Key concepts: object relationships, nested forms, RESTful routes, Rails, JavaScript, jQuery, JSON API.

workflow

  1. Add two gems: ‘activemodelserializers’, ‘jquery-rails’ and require jquery3 in asset javascript application.js
  2. Write todos in NOTE.md
  3. Code to meet the requirements set in NOTE.md
  4. Review NOTE.md
  5. Refactor

tasks defined

  1. Display index of teas on categories show page, fetching the tea info via AJAX GET request, with backend rendering in JSON format, and then appending the tea info to the page.
  2. Allow a user to browser through categories by clicking “Next” and “Previous” buttons on the categories show page, with the next/previous category being fetched and rendered via jQuery and AJAX.
  3. JSON API has has-many relationships. For example, when I render the next category info via AJAX call, I also have the list of teas in that category rendered through the API.
  4. A user can add a review to a tea, and the review is serialized and submitted via an AJAX POST request, with the response creating a javascript object and then appended to the DOM using JavaScript.
  5. Write a method to show posted dates for reviews on its JavaScript prototype object and append to the DOM.

thoughts: working on existing projects

Adapting an existing project to another language framework proved to be more challenging than constructing something new from the ground up. I googled so much because my problems were so specific to the app setup. I couldn’t write my app in a simple way to avoid complications. For example, I had to research how to dynamically listen to a list of buttons, not just one; I had to be mindful of all the parameters and object relationships that were passed around in each js call; etc. However, it’s probably the more common way to code. This experience is very helpful to see what the workflows would be like.

To quickly understand the structure of an existing project is the key. For a project that was originally built by myself, it still took me quite some time to familiarize with the web app. I interacted with the app in the browser, and then I went back to the codes to see how the corresponding functions were written and what variables and parameters were involved. That covered 80% of the scenarios.

What about the other 20%? A trick I learned during this process of working on existing repo is to write concise comments along with writing functions. It may seem like extra work in the beginning, but these comments serve three purposes:

1) Push me to define the purposes of the functions before they’re written out.

2) Make it easier for other coders or in this case, myself, to understand what the following lines tried to accomplish.

3) And most importantly, it helps me to stay clear-minded and delegate extra tasks to other functions. We all know the feeling of watching a function growing to a twenty-line fat existence that tries to do a thousand things. Not good.

how to work with current view pages(formatted) and JSON data

This can be a challenge. The way I handled it is, first, to pay close attention to the parameters and object relationships; and second, to have the pages rendered through previously formatted html view files and incorporate them into new js templates.

Especially when I was dealing with nested forms, I had to observe carefully how the forms were originally generated without javascript. Because my app is built upon Ruby on Rails, there’s authentication “csrf-token” that need to be taken care of before the form can be safely and successfully submitted. And not to mention all the classes, names, ids. It’s the small things that matter.

Here is a workflow I developed in this project to adapt a non-js project to jQuery & AJAX with JSON API:

  1. Review current views and decide which elements I would like to load via AJAX call.
  2. Write a NOTE.md with a list of basic tasks to keep myself on track. Use pseudo codes or plain English to define what I try to accomplish. I recommend limit the list to 5 items for a starter.
  3. Hijack the buttons and use javascript alert function fillers to test if I am listening to the right buttons and if the listeners are triggered correctly. Use debugger if not. Move on if yes.
  4. Add serializers for JSON responses. Adapt controllers to have them render JSON formats when requested.
  5. Write out the get/post function and use debugger to look at the response I get back from the calls. Save the response for templating later.
  6. Delegate the data-loading part to another function. Don’t write everything inside the listener functions. It would make debugging difficult.
  7. Templating time. I use Javascript objects and Handlebars to handle this part. I use the json response I got earlier and write my js object constructors accordingly. Then inside the data-loading function, I add a new js object with the JSON response. Use debugger to test if I get the right object before I move on.
  8. If all is well, I write my Handlebars templates now. If I am not sure about something, I would go back to the original views for reference. I tried to maintain a consistency between the original views and the new ajax looks.
  9. Render that response! Move on to the next task in NOTE.md. Repeat 3–8 untill all requirements are met.