Avi Das

Home for my code, thoughts and else.

What Makes a Great Programming Tutorial?

The Internet started as a publishing medium. It excels at enabling people to share their unique gifts. An amazing amount of content gets put out on the web everyday, far beyond someone can read in a lifetime. Massive amount of information also means information overload.

In software, it is common to use web tutorials to supplement someone’s learning of a particular material. Following guidelines of someone who has already done it can really fast track development. Tutorials appear in various forms in the web. Some of the common formats are long form blogposts, videos and series of email newsletters. Some enjoy the personal touch that videos can offer; others enjoy being able to quickly skim a blogpost.

When you want to put your hard earned knowledge and valuable time into writing a tutorial, there are questions worth thinking about. Does the tutorial cater to its intended audience and will it reach them? Can someone quickly skim the content and still get value? Is there a way to measure the effectiveness of online tutorials?

To look for answers, I asked a carefully selected group of 150 people about their preference of tutorials. The focus was on software engineers/designers/entrepreneurs due to my familiarity and experience with the field. What emerged from their responses gives a blueprint for creating great online resources.

  1. Real time feedback: If exercises or examples accompany a tutorial, multiple survey responders emphasized the need to check the user’s responses and provide interactive feedback to the user to guide them to the solution. Good examples are checkpoint multiple choice questions during Coursera/Udacity courses that you must complete to move forward with the course.

  2. Follow up: Several responders emphasized the need to provide contact information or other means to reach out to the author once they went through a tutorial. Providing a comments section or your email/twitter handle are great mediums for a reader to follow up.

  3. Address a concrete problem: Staying focused of a specific problem gives a tutorial depth. A differentiator can be to classify for the user whether the focus is academic and structured vs. a blogpost focused on solving a particular problem right now.

  4. Working examples: Interactive, working examples close to the content that builds on top of each other makes following along simpler. Michael Hartl’s Ruby on Rails tutorials came up as an example of detailed, comprehensive tutorials.

  5. Advanced user tutorials: Several user’s pointed out the need for tutorials that addresses advanced content. Making expectations clear about experience levels of intended audiences can be a huge positive for tutorials. Ray Wenderlich’s iOS tutorials are good examples of the detail and level of research and understanding that can happen before putting out content on the web.

  6. Copyright: Sometimes an afterthought, it may be worth pointing out what license the content is released under. This can give the reader’s clarity on how to attribute the source when they use that content in production. Github makes this really easy with license options provided during repository creation.

  7. Offer tangible short-term benefits: While this certainly applies more to blogposts rather than courses, focusing on offering user’s value short, medium and long term can improve the message of a tutorial. Moreover, an user may be more inclined to follow through the entire content of a tutorial if they are get that value at different stages of the tutorial.

  8. Timeliness: This could be hard to measure, but popularity of tutorials can be attributed to how current and relevant they are. As of the time of writing this blogpost, April 2016, there are lot of people looking to get into VR/AR, chatbots, AI and so on. Accounting for recency can certainly increase the reader counts of your posts.

  9. Continuity: It became clear through the responses that while people looked for tutorials to solve a particular problem, they return because they are looking for a subject matter expert. Producing a series of tutorials taking on different aspects of a topic can help with retention.

  10. Discoverability: This can go in the realms of SEO, but lot of responders responded to their favorite source of online tutorials with well-known sources. Coursera/Udemy/Khan Academy/YouTube and Google were all common ways people went around in finding online tutorials. If you do not want to solve distribution for the content you create, writing for more known blogs/sites can be a way to reach larger audiences.

  11. Formatting: A big part of the user experience, proofreading cannot be left for the last. In the tech space, prominent writers such as Paul Graham always attribute at the end of the blogpost all those who have helped proofread the content. Just passing it around to a few people before publication and basic spell checking/grammar checking can improve the user experience for tutorials.

There are definitely caveats to this survey. As the person compiling this survey, it is at least slightly influenced by my biases. My target group is highly technically literate, so there is a bias towards modern tools. Perhaps it is worth taking into account the intent of writing tutorials, be it teaching, lead generation or growing a business.

Like most studies, this too should be taken with a grain of salt and in no way is sure way to produce great tutorials. Someone’s genuine passion, interest and the willingness to learn and teach find their ways to shine through content. However, just as the Joel Test for Software Development companies is often a good checklist for expected standards of software companies, being aware of the reader’s needs and voice can lead to sharper, more helpful tutorials.

10 Things I Learnt Going From 10k to a Marathon in 2015

If I were to think about running a 26.2 mile race at the start of 2015, the overwhelming feeling would be one of fear. I have only ever ran a 10k before and just signed up for the Austin 2015 half Marathon, my first ever half. The prospect of running twice the distance still seemed far away though. Flash forward to October 18th 2015, I finished my first Marathon with a 3:49:00 time. As I look back on this year, I wanted to put together some of my realizations during the whole process. 

  1. Running is a privilege: Living somewhere where I can run safely, have trails to run on, be in good health to run are all privileges to be thankful for. Growing up in the developing world meant that it was hard pressed to find opportunities to be involved in outdoor activites. Having the time and space to exercise is a luxury that needed to be earned. I never ran in high school, and by the time I graduated college I could not run longer than 5k. Having the time to run, being in US where running is very much part of the culture has been a huge contributor to my running progress.

  2. Joining a running group is one of the best decisions you can make as a beginning runner: Training with people better than you to improve is not unique to running. Start of 2015, I had no plans of running a marathon. In April, I joined the Austin Runners Meetup (ARM). In training long runs with ARM, I was able to build up the endurance for longer runs which made the progression to a Marathon much easier mentally. Training with other runners can definitely help you maintain the habit of running as well as improve your form and performance. Moreover, I found a new community of great people which has been very rewarding.

  3. Tying running with other activities you enjoy can make running much more consistent: In Charles Duhigg’s Power of Habit, he talks about the cue-action-reward pattern that most habits follow. Being aware of that pattern can help in building running as a habit. When run’s are followed by a delicious breakfast, you have something to look forward to. Trance music and podcasts help me maintain the flow during running. Travel is one of my favorite things and going to a new city for a race is something I eagerly look forward to.

  4. Running is a blissful release from life’s distractions:

    “All I do is keep on running in my own cozy, homemade void, my own nostalgic silence. And this is a pretty wonderful thing.”  ― Haruki Murakami, What I Talk About When I Talk About Running“`

    Distractions are part and parcel of our lives as more form factors emerge competing for our limited attention span. Often, this results in us not being aware of the passage of time. Running has been a great antidote to that problem for me. When running is effortful, you have to concentrate on the activity at hand and your entire focus is on the present moment. Long runs offer the prospect of seeing places and neighborhoods that you would not frequent otherwise. A slight breeze on a scorching summer’s day has never been more enjoyable.

  5. Once running is a habit, a chore becomes a craving: When you start out running, it can be something you dread on your calendar. There is really no way to get past this without sustained practice, lowering the cognitive load with group associations and reward mechanisms. If you continue though, you realize at one point that you start craving the runs. Don’t get me wrong, it still requires a lot of mental effort to get up at 5:30am for that 20 mile run you need to do for Marathon training. But something about the combination of endorphins, habits built during running and seeing your friends out there on the trail can change running into something that you look forward to.

  6. You only compete against your past self: This can vary a lot based on personality, but being slower than a lot of other runners has never really bothered me that much. As long as I beat my previous PR by two seconds, I would be happy. Running as an activity has been such a positive change for my life that the gratification from being faster than others has not been necessary at all. Lot of people starting out running also worry about their pace. However, beginner runners should actually run slower than the pace they think they can run at to avoid injury and build up distance and time.

  7. Respect your body’s adjustment mechanisms: One of my foremost running philosophies is to avoid injury. Running is a full body exercise. Your heart, muscles, ligaments and joints all need adjust to the increased level of physical activity. In the beginning, you run out of breath since your heart is simply not used to pumping out the necessary amount of oxygen to the muscles. However, it can adjust remarkably fast, and you may be tempted to run faster than you should. Getting past muscle cramps is often the next step. Your joints likely will be the last to adjust though, and care should be taken to not run too fast too soon to avoid injury.

  8. Hard things are often the most rewarding: If a Marathon was easy, the feeling of achievement would be less profound. You will be in pain after finishing a Marathon. However, if there is any time when pain feels besides the point, this is it. Finishing a Marathon feels good in a way that is hard to find a parallel in our day to day life. Rather you feel as accomplished as a battle commander from the middle ages after winning a long and arduous war.

  9. It will affect you positively in ways you may not expect: When I talk to people about running, I consistently discover new and positive impacts running has had on their lives. For some people if is therapeutic and a great way to cope against troubles in life. It stands out as one of the activities that can have an 80/20 impact on your life, since the improvement in concentration and physical ability that you gain from running regularly can help in most other areas of life.

  10. It gives you the satisfaction of reaching your goals and finishing: There are lot of things in life that can drag on, get pushed on and not have a clear resolution. Life is rarely black or white. Running is often a refreshing break from all that. Once you finish a race, it is done and over with, offering the joy of finishing something. Moreover, looking forward and planning for the race can become an exciting activity, as you look to vindicate your hard hours of training.

Running is ultimately a very solitary activity. It does not matter if you train with a group, you are going to be on your own for long periods of time. This makes everyone’s running journey very personaI. If you are starting out running in 2016 or have certain training goals, I wish you all the best. If you have already been running races, I hope there was still something useful in this post for you. Either way, feel free to reach out or leave a note. I would love to hear from you.

Coffeehouse Coworkers

I had a problem.

It is fun to start side projects, but not always the easiest to stay committed and finish. Coffee has powered more projects than one can count. What also helps to stay focused and motivated is the company of like-minded individuals. Coffee and friends results in more and better products.

What can one do to reach more of those people?

Coworking spaces are hot in this economy. WeWork have recently stepped into the $10 billion club. In Austin, Capital Factory, Chicon collective, General Assembly and Link are just some of the spaces ranging from Accelerator/Incubator to just rentable office spaces. However, they are much more fitted for startups working out of a coworking space. Moreover, one spot can get boring pretty quickly.

What if you are a remote worker or work on side projects and wish there was a community you could cowork/share with?

In Austin, there are a few options for that as well. There is a great group called Cafe Bedouins who meet Tuesdays at 7pm in Houndstooth cafe to work on projects. I had a great time there, but thought why would this need to happen only on a particular weekday on a particular time? Weekends are often the times when side projects gets the attention anyway. By a stroke of luck, I ran into Adam Coulon at Cafe Bedouins, who is also really enthusiastic about coworking, and shared the same problem.

We considered platforms where people could spontaneously decide to meet and cowork on projects. Slack was the clear winner. It is really easy to set up, and it has spread like wildfire so people tend to be familiar with the product. Without futher ado we present Coffeehouse Coworkers, made with rauchg’s excellent slackin pluigin. It’s a slack channel for people to find others and decide on places to cowork!

At the highest level, we love products and want their to be more finished products out there. It could be a blogpost, design concept, open source software or your consulting business. We think that better products happen in collaboration with like minded people. This may not be everyone’s cup of tea (or coffee rather), but our hope is to enable some people to optimize their workflow in a low commitment way.

If any of this interests you, join us at Coffeehouse Coworkers. Right now, the members are mostly Austin based and in tech since that is our current demographic, but it does not really have to be limited to that. Austin is a great place to start since it has a lot of independent workers and great coffeeshops.

Happy coworking!

Pycon Canada 2015 II: Python for Reliably Delivering Cross Platform Products

This is the second part of the two series blog post about my talk at PyCon Canada. Here is the first part.

Proposal:

Are you part of a team responsible for delivering cross platform products? End to end automated testing and communicating effectively are important when your project depends on multiple teams spread across functional domains. At Braintree/PayPal, we worked on a framework to reliably ship developer facing products. We will go over using BDD with Behave to describe test scenarios that speaks to both product and engineering, using Appium for mobile automation, and ElasicSearch and Kibana for storage and visualization of test results. You will see how the breadth of packages available on PyPI, the flexibility and ease of Python helped a team of developers whose core competencies were not in Python to collaborate on a common ground.

Slides:

Video:

Youtube link

Github Repo

Reliability Demo

Speaking at PyCon Canada 2015: I

High Level Takeaways

  • If you are giving a talk, too much content on slides means the audience is reading the slides instead of listening to you.
  • Design your talk expecting failure, and assume things like wifi will not work. An analogy would be the non functional escalator still being a staircase.
  • Show your talk to as many people as time allows. Every time I showed my talk to someone, I would find a new way to make the talk better.
  • It was amazing to hear from a 10 year old about his experience in coding. The barrier to entry to tech will keep falling in a noticeable way.
  • Teaching remains the best way to learn alongside with building things.
  • Coding for expectability is often as important as any considerations in a software project.
  • Science, data, web, systems and infrastructure were dominant themes at PyCon.

Getting to Toronto

  • It was really exciting to have my talk accepted at PyCon, since it was my first time speaking at a conference.
  • Getting through customs went as painless as they could have.
  • Toronto was colder than Austin, big surprise! Reminded me of times back in East Coast.
  • T-mobile data roaming was a breeze to set up, and worked mostly well across different providers.
  • Toronto had different modes of public transportation getting from downtown to airport: buses, streetcars, subway. Makes a city more interesting, although makes day to day travelling more complicated. Although, it does not take a whole lot to put public transportation in Austin to shame.
  • Asked a lady on the Subway for directions. It soon turned into a great conversation with her and her husband about life in Toronto and their experiences in US. For a big city, Toronto scores major points for having friendly people. Canadians have a reputation of being polite and helpful, and I would come to recognize it throughout my trip there.
  • My AirBnB was in Kensington Market, close to UoT where PyCon was taking place. It was a vibrant neighborhood, bars, restaurants, transportation nearby. My room was no hotel room, but a bed was all I needed.

Saturday

  • Morning started with me feeling the stress of not having all my slides and examples ready. I wanted to take some time to reflect on the great feedback I got from my team, but there was little time left.
  • Adding to my anxiety was the wifi connection not working. Thankfully, some organizers helped me out. Once the certificate issues resolved, it worked well for remainder of the conference.
  • Continental breakfast consisted of an assortment of cottage cheese, granola/yogurt, muffins, bread and coffee. No complaints.
  • Talked to Dusty, a Facebook engineer working on the Facebook infrastructure in Portland. Having lived in Canada, he had a lot to share about his experience there.
  • Morning keynote explored the history of Python interpreters and went into benchmarks. Benchmark related conversations can get subjective, but the speaker did a good job avoiding that.
  • Talks on application security, Emmy nominated CGI(!) and Docker deployment followed. The CGI talk was offered a very different viewpoint in software problems. Being highly computation intensive and long life cycles means the tradeoffs are very different from the usual SASS app/consumer product.

Building Realtime Apps With React, Socket.io and Node.js

Update: Udemy has generously granted a free coupon for the readers of this blog for their React JS and Flux course. Use the code avidasreactjs and the first 50 readers will get free access to the course!

The importance of delivering realtime feedback to users is more than ever. Gone are the days when chats or games were the only applications of realtime software. Starting from finance, advertising or education, having a realtime component to your web application will elevate the user experience.

Socket.io

From socket.io’s homepage, it is a library that enables real-time bidirectional event-based communication. It has two parts, a client side library that runs in the browser and a server side library for node.js. In recent times, this has become the de facto way of doing realtime web applications in the node.js world. Key reasons behind this has been the way it abstracts away the overhead of maintaining multiple protocols, while carrying on similar primitives from Node streams and eventEmitter. Some of its other powerful features include being able to stream Binary data, broadcast to multiple sockets and being able to manage connected client data from the server.

Architecture

The WebSocket protocol is a W3C standard that enables interactive communication between browser and server. It functions as an Upgrade request over HTTP 1.1. However, since all legacy browsers and devices do not have support for WebSockets, it’s cross-platform abilities get limited.

Socket.io itself is a library to build realtime applications. It will try to upgrade to and use the Websocket protocol if available. Socket.io depends on another libray called Engine.io which exposes a Websocket like API but provides fallbacks to other transport mechanisms such as XHR and JSONP polling. This enables application developers to write realtime codebases that are browser, device and transport implementation independent.

Getting started with Socket.io

This tutorial assumes that you have Node.js, npm and Express on your system.

In a directory create two files called index.html and app.js. In your app.js file, add the following

1
2
3
4
5
6
7
8
9
10
11
12
13
14
var app = require('express')();
var server = require('http').Server(app);
var swig = require('swig');
var path = require('path');

// view engine setup
app.engine('html', swig.renderFile);
app.set('view engine', 'html');

// server and routing
server.listen(8080);
app.get('/', function (req, res) {
  res.render('index');
});

We set up the view engine and serve up a basic index page. If this part looks unfamiliar, please check out Express docs. Now add the following in app.js.

1
2
3
4
5
6
7
8
var io = require('socket.io')(server);
// socket.io demo
io.on('connection', function (socket) {
  socket.emit('server event', { foo: 'bar' });
  socket.on('client event', function (data) {
    console.log(data);
  });
});

We create a new instance of socket.io and pass in the created express server as a parameter. As the server listens, whenever a new client starts a connection, we emit an event called server event and send the payload { foo : ‘bar’ }. It also listens for ‘client event’ and logs the payload once it gets the event.

In your index.html file add the following

1
2
3
4
5
6
7
8
<script src="/socket.io/socket.io.js"></script>
<script>
  var socket = io();
  socket.on('server event', function (data) {
    console.log(data);
    socket.emit('client event', { socket: 'io' });
  });
</script>

It includes the client side socket io library. After instantiating a new connection, it listens for the ‘server event’ and when that event happens it logs the data and emits ‘client event’ and sends the payload { socket: ‘io’}.

Run node app.js and fire up localhost:8080 in your browser. On the terminal you should see { socket: ‘io’ } and on the console you should see { foo : ‘bar’ } printed out. Congrats, you just did your first Socket.io app!

Useful Socket.io Concepts

Message sending/receiving

Socket.IO allows you to emit and receive custom events. Besides connect, message and disconnect, you can emit custom events and send with associated payload. Emit and Broadcast are ways to send events and on is the event listener.

Server vs Client API

There are some common functions between server and client side, but it is worth looking into the docs and understanding what is possible on the server vs client. Generally, the server side has much more features and capabilites and is capable of creating rooms and namespaces but both sides and send and respond to events.

Rooms and Namespaces

Socket.io provides built in abstractions to demultiplex the connected clients. Namespaces, identified by a path, can be connected via the following

1
2
var socket = io(); //connects to default namespace "/"
var admin = io("/admin"); //connects to the namespace specified by the path "/path"

After a client connects with var socket = io('/admin') , we can send message only to the admin namespace.

1
admin.emit("admin alert", "website traffic is up!"); //the event will only be sent to the clients who connected to the admin namespace

This enables more role or other criteria based distribution of socket.io events/messages within your application.

Rooms provide a way to further divide up clients within individual namespaces. Clients within a namespace can join and leave a room. By default, a client always is connected to a room idenfied by the sockets id. Hence it is possible to send targeted messages to a connected client via socket.broadcast.to(<SOCKET.ID>).emit('test', 'message'). Rooms could make more sense for particular themes whereas namespaces seem to fit well for user type/responsibilities.

React and Socket.io

Now for the exciting part, integrating React.js and Socket.io into an application. React.js is Javascript UI framework from facebook. You can follow some of the initial docs to get started with React. This tutorial will not go into great detail into the terminologies of React.js but refer to the official documentation if any of the React syntax looks confusing.

The basic idea of the app is to have an html input and a label. When someone types in something into the input box, it will update the label for anyone else who have an window open except for the person typing.

Client side code

Let’s start by changing your index.html to the following

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/react/0.13.2/react.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/react/0.13.2/JSXTransformer.js"></script>
    <script src="/socket.io/socket.io.js"></script>
  </head>
  <body>
    <div id="mount-point"></div>
    <div id="label-mount-point"></div>
    <script type="text/jsx">
     /** @jsx React.DOM */
    var socket = io();

    var Input = React.createClass({
      _notifyServer: function(event){
        socket.emit('client event', { value: event.target.value });
      },
      render: function(){
        return (
          <div className="update-label">
            <input type="text" placeholder="Enter text" onChange={this._notifyServer}/>
          </div>
        );
      }
    });
    var Label = React.createClass({
      _onUpdateLabel: function(data) {
        this.setState(serverValue: data.value);
      },
      getInitialState: function(){
        return { serverValue: '' };
      },
      render: function(){
        return (
          <div class="my-label">
            <h2>{this.state.serverValue}</h2>
          </div>
        )
      }
    });
    var input = React.render(<Input/>, document.getElementById('mount-point'));
    var label = React.render(<Label/>, document.getElementById('label-mount-point'));
    socket.on('update label', function (data) {
      label._onUpdateLabel(data);
    });
    </script>
  </body>
</html>
Server side

The server side of the codebase can mostly stay the same, except we broadcast ‘update label’ when ‘client event’ is received.

1
2
3
4
5
6
io.on('connection', function (socket) {
  socket.emit('server event', { foo: 'bar' });
  socket.on('client event', function (data) {
    socket.broadcast.emit('update label', data);
  });
});
Explanation

On the client side, two React components called Input and Label are created and mounted by calling React.render. Input renders an html input box which calls the notifyServer method whenever the someone types into the input field. The notifyServer method then emits socket.io event called ‘client event’ with the value of the input box.

On the server side, when ‘client event’ is received with the data, the server calls socket.broadcast.emit and passes the data payload along. This means that all the connected clients except for the socket that generated ‘client event’ will receive the ‘update label’ event and the payload. This sends the message to everyone except for the person typing.

Back to the client side, the Label component consists on a div with a h2 element with is set to the serverValue state of the component. getInitialState sets the initial value to be ” so initially the Label is empty. When ‘update label’ is received, we call the _onUpdateLabel on label, which is an instance of Label. It sets the serverValue state of the Label component to data.value. This invokes the render method of the label component, and it generates a h2 header with the updated value of the serverValue.

Guide to Finding a Technical Cofounder

This has been happening at various meetups/hackathons/startup events sufficiently enough to warrant a blogpost. The situation is generally a variant of this, someone has an idea they are really convinced is the next big thing, the only thing stopping that from happening is making an app/website which requires a technical cofounder. The person with the idea is not at a position to afford the costs of hiring a full time/part time developer, so an equity sharing situation makes sense. Hackathons and tech meetups are where developers hang out, so approaching them there seem to be a good idea to find that cofounder.

There are a few problems to approaches like this. Software people who go to events like this gets pitched a fair amount, sometimes repeatedly on the same ideas. Also, we can be a rather cynical bunch, often as result of the kind of work that we do. This can result you not finding that engineer/hacker to build your app during a hackathon. Or they might do so during the hackathon, but simply drop off after.

It can get discouraging, specially if you are convinced about the idea and new to such events. Personally, I like idea people, specially because they bring in ideas from domains and problem spaces I would have no exposure to otherwise. Moreover, I also believe that cross-pollination of people from different groups is healthy and more products coming into the world is a good thing. Therefore, I would rather like to jot down some helpful tips which can maximize your chances of finding a technical cofounder next time you are looking for one.

  1. Understand what motivates engineers: It’s important to understand what motivates engineers beyond just financial opportunity. If such an opportunity exists, you may be in pretty decent shape already and should really drill down on your exact plans on how the app would make money in the future. If you are less sure, there are still options. Can you prove that the app would have a broad user base? A great way to do this would be to prove that you have tried unscalable ways doing this already, be it door-to-door, personal know how, competitors etc. Most ideas can be validated using non-technical approaches. Knowing your problem space well will not only help you to build a business but also lend credibility when you are looking for a cofounder. Another thing that attracts is interesting technical problems or cutting-edge tech, so if your app involves either, it would be a positive. Good technical co founders can be extremely self-motivated once they realize that they have a problem is really worth spending time on.

  2. Manage expectations: It is best to present the idea and the opportunity and not expect immediate commitment. Generally people are busy, but if you have done your homework and can present the problem well, there is always a good chance. Not all engineers want the same thing, and lot are perfectly happy working where they are. If you do not have a proven user base or revenue plan yet, it does involve a certain risk-taking to get on that journey. As someone who wants to be a founder, you should seek technical co-founders with the same risk appetite as you.

Evaluating React.js and Flask

Update: Udemy has generously granted a free coupon for the readers of this blog for their React JS and Flux course. Use the code avidasreactjs and the first 50 readers will get free access to the course!

As a connoisseur of the web, front-end frameworks have been been a fertile area of late. React.js from Facebook has taken much fanfare, and this post evaluates key ideas on react, and digs into why you could be interested in React. Staying true to single responsibility principle, React is a highly useful tool if you are doing web programming.

In this post, we will dive into building a Frontend using React.js and Backend built using the Python framework Flask. Flask is a minimalistic framework, and excellent when your backend becomes more and more of an API. Moreover, this facilitates the microservices architecture, where the decoupling of your your app into small unit of services can make it more maintainable and scalable.

We will cover some of the key ideas of React and Flask here, but it would be worth referring to the official documentation for React and Flask for getting started and understanding the philosophies of each framework.

Key Ideas of React

The core idea of React is the developers are better of leaving manipulating the DOM to battle tested framework code. Since the DOM has a tree structure, finding elements and manipulating them would need many traversals of a potentially very large tree. Instead, what you modify is a virtual DOM, and React runs its intelligent diffing algorithm to directly update the DOM.

React

React itself is the UI library that will manage all the DOM updates as data changes. It’s takes the V of MVC frameworks, hence it can be used with other MVC frameworks such as Angular, Backbone or Meteor. It is quite easy to use React to manage specific areas of your application’s UI, rather than the entire app.

Virtual Dom

The virtual Dom is an abstraction layer between nodes in the real DOM and the view of the code you are modifying. When React selectively renders subtrees of the nodes in DOM based upon state changes, it achieves the following

 1. Ensures that your DOM is always up to date with current state
 2. Reduces the need to re-render the DOM every time there is change in state
 3. Updating only the individual components on state change ensures high performance
JSX

JSX is a JavaScript syntax extension and it brings in a HTML/XML like familiar syntax for defining a tree structure with attributes. This is the syntax you can use to declare the changes in layout code and React will update the UI. It’s a bold approach, since developers are conditioned to keep layout code separate from Javascript. We will explain more React terminology later as we dive into some code.

Key Ideas of Flask

Flask is a microframework, which means that it trades a short learning curve for fewer out of the box functionalities, compared to heavier frameworks such as Django or Rails. It gives developers more freedom to use their preferable tools and libraries. However, it does have a list of officially supported extensions which when plugged in provide a wide breath of functionalities for a standard web app. Extensions behave as if they are native flask code.

We strongly recommend that you set up a virtualenv for this project, and you may also want to check out virtualenvwrapper for convenience. This is to provide your app with a sandboxed environment.

Getting up and running with Flask

Lets first install Flask

1
2
3
4
pip install Flask

# For viewing and reusing app dependencies
pip freeze > requirements.txt

Set up the following directory structure in your app.

1
2
3
4
5
├── README.md
├── app.py
├── requirements.txt
└── templates
    └── index.html

Modify your app.py code to include the following

1
2
3
4
5
6
7
8
9
10
11
from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")

def index():
    return render_template('index.html')

if __name__ == "__main__":
    app.run()

We start by importing Flask and creating a new instance of a flask application. In flask, app.route is used to describe the behavior when users hit particular endpoints in the application. Here when user hits the index route, we render a template called hello world. By default Flask uses the Jinja2 templating language, but you can use any other templating language. In fact, we will not be covering Jinja2 in this blog post. Finally we tell python to call the run method of the app when invoked as a main function.

Let’s populate index.html with the following basic HTML boilerplate

1
2
3
4
5
6
7
8
9
10
11
12
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Flask React Tutorial</title>
</head>
<body>
     <div id="mount-point">
         <p1>Hello world.</p1>
     </div>
</body>
</html>

Now run the app with

1
2
3
python app.py
// * Running on http://127.0.0.0:5000/
// * Restarting with reloader

By default it runs on port 5000. Navigate to the endpoint and you should see the html page you just created. You are now up and running with Flask!

Integrate React

Easiest way to include React would be to just include them from a cdn. Let’s update the index.html to include React and and port our existing html to React. index.html will now look like

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Flask React Tutorial</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/react/0.13.2/react.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/react/0.13.2/JSXTransformer.js">
</head>
<body>
     <div id="mount-point"></div>
</body>

  <script type="text/jsx">
     /*** @jsx React.DOM */
    var FirstComponent = React.createClass({
        render: function() {
            return (<p1>Hello world.</p1>);
        }
    });
    React.render(<FirstComponent />, document.getElementById('mount-point') );
     </script>

</html>