- +

First News App¶

A step-by-step guide to publishing a simple news application.

@@ -48,26 +50,23 @@

First News AppInvestigative Reporters and Editors (IRE) -and the National Institute for Computer-Assisted Reporting (NICAR) -by Ben Welsh. It debuted on February 27, 2014, at NICAR’s annual conference -in Baltimore. A revised version was presented at -the following year’s conference in Atlanta. It -is scheduled to be taught again at the upcoming Denver conference -on March 11 and 12, 2016.

-

What you will make¶

-

This tutorial will guide you through the process of publishing an interactive database and map -about the more than 60 people who died during the riots that swept Los Angeles -for five days in 1992. You will repurpose the data from a Los Angeles Times +

If you complete this lesson, you will publish an interactive database and map +about the dozens of people who died during the riots that swept Los Angeles +for five days in 1992. You will do this by repurposing the data from a Los Angeles Times application that accompanied a story released on the 20th anniversary of the riots.

-

A working example can be found at ireapps.github.io/first-news-app/build/index.html

+

A working example of what you’ll make can be found at ireapps.github.io/first-news-app/build/index.html

+
+
+

About the author¶

+

This guide was prepared for training sessions of Investigative Reporters and Editors (IRE) +and the National Institute for Computer-Assisted Reporting (NICAR) +by Ben Welsh. It debuted in February 2014 at NICAR’s conference +in Baltimore. A revised version was presented at +the 2015 conference in Atlanta and the 2016 conference in +Denver. It is scheduled to taught for the fourth time at the upcoming NICAR conference in Jacksonville.

Prelude: Prerequisites¶

@@ -76,30 +75,20 @@

Prelude: Prerequisites
  • A command-line interface to interact with your computer
  • A text editor to work with plain text files
    • -
  • Git version control software and an account at GitHub.com
  • Version 2.7 of the Python programming language
  • The pip package manager and virtualenv environment manager for Python
    • +
  • Git version control software and an account at GitHub.com
    • -
    -

    Note

    -

    Depending on your experience and operating system, you might already be ready -to go with everything above. If so, move on to the next chapter. If not, -don’t worry. And don’t give up! It will be a bit of a -slog but the instructions below will point you in the right direction.

    -
    +
    +

    Warning

    +

    Stop and make sure you have all these tools installed and working properly. Otherwise, you’re gonna have a bad time.

    +
    +
    +

    Command-line interface¶

    +

    Unless something is wrong with your computer, there should be a way to open a window that lets you type in commands. Different operating systems give this tool slightly different names, but they all have some form of it, and there are alternative programs you can install as well.

    +

    On Windows you can find the command-line interface by opening the “command prompt.” Here are instructions. On Apple computers, you open the “Terminal” application. Ubuntu Linux comes with a program of the same name.

    -

    Command-line interface¶

    -

    Unless something is wrong with your computer, there should be a way to open a window that lets you -type in commands. Different operating systems give this tool slightly different names, but they all have -some form of it, and there are alternative programs you can install as well.

    -

    On Windows you can find the command-line interface by opening the “command prompt.” Here are instructions for -Windows 8 -and earlier versions. On -Apple computers, you open the “Terminal” application. Ubuntu Linux -comes with a program of the same name.

    -
    -
    -

    Text editor¶

    +

    Text editor¶

    A program like Microsoft Word, which can do all sorts of text formatting like change the size and color of words, is not what you need. Do not try to use it below.

    You need a program that works with simple “plain text” files, @@ -109,51 +98,46 @@

    Text editorTextWrangler. In Ubuntu Linux you can stick with the pre-installed gedit text editor.

    -
    -

    Git and GitHub¶

    -

    Git is a version control program for saving the changes -you make to files over time. This is useful when you’re working on your own, -but quickly becomes essential with large software projects, especially if you work with other developers.

    -

    GitHub is a website that hosts git code repositories, both public and private. It comes -with many helpful tools for reviewing code and managing projects. It also has some -extra tricks that make it easy to publish web pages, which we will use later.

    -

    GitHub offers helpful guides for installing Git in -Windows, -Macs and -Linux. You can verify -it’s installed from your command line like so:

    -
    # You don't have to type the "$" It's just a generic symbol
-# geeks use to show they're working on the command line.
-$ git --version
+
    +
    +

    Python¶

    +

    Python is a computer programming language, like many others you may have heard of like Ruby or PHP or Java. It is free and open source. To continue to with this class, you will need to have version 2.7 installed.

    +

    If you are using Mac OSX, Python version 2.7 is probably already installed and you can test to see what version, if any, is already available by typing the following into your terminal.

    +
    $ python -V
    -

    Once that’s done, you should create an account at GitHub, if you don’t already have one. -It shouldn’t cost you anything. The free plan -is all that’s required to complete this lesson.

    +
    +

    Note

    +

    You’ll note that the example above begins with a “$”. You do not need to type this. It is only a generic symbol +commonly used by geeks to indicate a piece of code should be run from the command line. On Windows, this prompt could even look quite different, likely starting with a phrase like C:\.

    -
    -

    Python¶

    -

    If you are using Mac OSX or a common flavor of Linux, Python is probably already installed and you can -test to see what version, if any, is there waiting for you by typing the following into your terminal.

    +

    You should see something like this after you hit enter:

    $ python -V
+Python 2.7.12
    -

    If you don’t have Python installed (a more likely fate for Windows users) try downloading and installing it from here. In Windows, it’s also crucial to make sure that the -Python program is available on your system’s PATH so it can be called from anywhere on the command line. This screencast can guide -you through that process.

    -

    Python 2.7 is preferred but you can probably find a -way to make most of this tutorial work with other versions if you futz a little.

    +

    If you get an error instead, Mac users should install Python by following these instructions offered by The Hitchhikers Guide to Python.

    +

    If your version is 2.7.11 or 2.7.13 or some other slight variation from what’s above, that’s okay. If it’s Python 3, that’s another issue and you should try to install Python 2.7 instead. If you continue with Python 3, this class may largely work, but you could encounter some small problems you’ll need to sort out on your own.

    +

    Just like Apple users, Windows people should open their command prompt and investigate whether Python is already installed.

    +
    python -V
+
    +
    +

    You should see something like this after you hit enter:

    +
    python -V
+Python 2.7.12
+
    +
    +

    If not Windows users can find a similar installation guide here which will have you try downloading and installing Python from here. After that’s done, ensure Python is installed by reopening the command prompt and running the command above again.

    -

    pip and virtualenv¶

    +

    pip and virtualenv¶

    The pip package manager makes it easy to install open-source libraries that expand what you’re able to do with Python. Later, we will use it to install everything needed to create a working web application.

    If you don’t have it already, you can get pip by following -these instructions. In Windows, it’s necessary to make sure that the -Python Scripts directory is available on your system’s PATH so it can be called from anywhere on the command line. This screencast can help.

    -

    Verify pip is installed with the following.

    +these instructions.s

    +

    Verify pip is installed with the following command:

    $ pip -V
    @@ -165,17 +149,39 @@

    pip and virtualenv
    $ virtualenv --version

    -

    If you don’t have it, install it with pip.

    -
    $ pip install virtualenv
-# If you're on a Mac or Linux and get an error saying you lack the right permissions, try it again as a superuser.
+
    If you don’t have virtualenv, install it with pip.
    
+
    # On Windows:
+$ pip install virtualenv
+# On a Mac or Linux you will need to install it as a superuser with the sudo command.
+# When you are prompted for a password, use the same one that logs you into your computer
 $ sudo pip install virtualenv
 
    
 
    
-
    If that doesn’t work, try following this advice.
    
+
    If that doesn’t work, try following this advice.
    
+
    
+
    Git and GitHub¶
    
+
    Git is a version control program for saving the changes
+you make to files over time. This is useful when you’re working on your own,
+but quickly becomes essential with large software projects, especially if you work with other developers.
    
+
    GitHub is a website that hosts git code repositories, both public and private. It comes
+with many helpful tools for reviewing code and managing projects. It also has some
+extra tricks that make it easy to publish web pages, which we will use later.
    
+
    GitHub offers helpful guides for installing Git in
+Windows,
+Macs and
+Linux. You can verify
+it’s installed from your command line like so:
    
+
    $ git --version
+
    
+
    
+
    Once that’s done, you should create an account at GitHub, if you don’t already have one.
+It shouldn’t cost you anything. The free plan
+is all that’s required to complete this lesson.
    
+
    @@ -265,15 +271,15 @@

    Act 2: Hello Flaskapp.py with your text editor and import the Flask basics. This is the file that will serve as your application’s “backend,” routing data to the appropriate pages.

    from flask import Flask
-app = Flask(__name__)  # Note the double underscores on each side!
+app = Flask(__name__)  # Note the double underscores on each side!

    Next we will configure Flask to make a page at your site’s root URL.

    Configure Flask to boot up a test server when you run app.py.

    from flask import Flask
-app = Flask(__name__)
+app = Flask(__name__)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     # Fire up the Flask test server
     app.run(debug=True, use_reloader=True)
    @@ -294,9 +300,9 @@

    Act 2: Hello Flaskrender_template, a Flask function we can use to combine data with HTML to make a webpage.

    from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     # Fire up the Flask test server
     app.run(debug=True, use_reloader=True)
    @@ -304,13 +310,13 @@

    Act 2: Hello Flaskindex that returns our rendered index.html template.

    from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def index():
     template = 'index.html'
     return render_template(template)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     # Fire up the Flask test server
     app.run(debug=True, use_reloader=True)
    @@ -319,14 +325,14 @@

    Act 2: Hello Flask/.

    from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 @app.route("/")
 def index():
     template = 'index.html'
     return render_template(template)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     # Fire up the Flask test server
     app.run(debug=True, use_reloader=True)
    @@ -353,7 +359,7 @@

    Act 2: Hello Flask

    Note

    -

    To get the terminal back up, you will either need to quit out of app.py by hitting CTRL-C, or open a second terminal and do additional work there. If you elect to open a second terminal, which is recommended, make sure to check into the virtualenv by repeating the . bin/activate part of Act 1: Hello Git. If you choose to quit out of app.py, you will need to turn it back on later by calling python app.py where appropriate.

    +

    To get the terminal back up, you will either need to quit out of app.py by hitting CTRL-C, or open a second terminal and do additional work there. If you elect to open a second terminal, which is recommended, make sure to check into the virtualenv by repeating the . bin/activate part of Act 1: Hello Git. If you choose to quit out of app.py, you will need to turn it back on later by calling python app.py where appropriate.

    I bet you remember how from above. But here’s a reminder.

    $ git add .
@@ -399,7 +405,7 @@ 
    Act 3: Hello HTML
    import csv
 from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def get_csv():
     csv_path = './static/la-riots-deaths.csv'
@@ -409,7 +415,7 @@ 
    Act 3: Hello HTMLtemplate = 'index.html'
     return render_template(template)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     app.run(debug=True, use_reloader=True)
    @@ -417,7 +423,7 @@

    Act 3: Hello HTML
    import csv
 from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def get_csv():
     csv_path = './static/la-riots-deaths.csv'
@@ -428,7 +434,7 @@ 
    Act 3: Hello HTMLtemplate = 'index.html'
     return render_template(template)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     app.run(debug=True, use_reloader=True)

    @@ -436,7 +442,7 @@

    Act 3: Hello HTML
    import csv
 from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def get_csv():
     csv_path = './static/la-riots-deaths.csv'
@@ -448,7 +454,7 @@ 
    Act 3: Hello HTMLtemplate = 'index.html'
     return render_template(template)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     app.run(debug=True, use_reloader=True)

    @@ -460,7 +466,7 @@

    Act 3: Hello HTML
    import csv
 from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def get_csv():
     csv_path = './static/la-riots-deaths.csv'
@@ -473,7 +479,7 @@ 
    Act 3: Hello HTMLtemplate = 'index.html'
     return render_template(template)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     app.run(debug=True, use_reloader=True)

    @@ -481,7 +487,7 @@

    Act 3: Hello HTML
    import csv
 from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def get_csv():
     csv_path = './static/la-riots-deaths.csv'
@@ -495,7 +501,7 @@ 
    Act 3: Hello HTMLtemplate = 'index.html'
     return render_template(template)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     app.run(debug=True, use_reloader=True)

    @@ -503,7 +509,7 @@

    Act 3: Hello HTML
    import csv
 from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def get_csv():
     csv_path = './static/la-riots-deaths.csv'
@@ -518,7 +524,7 @@ 
    Act 3: Hello HTML    object_list = get_csv()
     return render_template(template, object_list=object_list)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     app.run(debug=True, use_reloader=True)

    @@ -604,7 +610,7 @@

    Act 3: Hello HTML
    import csv
 from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def get_csv():
     csv_path = './static/la-riots-deaths.csv'
@@ -624,7 +630,7 @@ 
    Act 3: Hello HTML    template = 'detail.html'
     return render_template(template)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     app.run(debug=True, use_reloader=True)

    @@ -653,7 +659,7 @@

    Act 3: Hello HTML
    import csv
 from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def get_csv():
     csv_path = './static/la-riots-deaths.csv'
@@ -674,7 +680,7 @@ 
    Act 3: Hello HTML    object_list = get_csv()
     return render_template(template)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     app.run(debug=True, use_reloader=True)

    @@ -682,7 +688,7 @@

    Act 3: Hello HTML
    import csv
 from flask import Flask
 from flask import render_template
-app = Flask(__name__)
+app = Flask(__name__)
 
 def get_csv():
     csv_path = './static/la-riots-deaths.csv'
@@ -705,7 +711,7 @@ 
    Act 3: Hello HTML        if row['id'] == row_id:
             return render_template(template, object=row)
 
-if __name__ == '__main__':
+if __name__ == '__main__':
     app.run(debug=True, use_reloader=True)

    @@ -790,7 +796,7 @@

    Act 3: Hello HTMLfrom flask import Flask from flask import abort from flask import render_template -app = Flask(__name__) +app = Flask(__name__) def get_csv(): csv_path = './static/la-riots-deaths.csv' @@ -814,7 +820,7 @@

    Act 3: Hello HTMLreturn render_template(template, object=row) abort(404) -if __name__ == '__main__': +if __name__ == '__main__': app.run(debug=True, use_reloader=True)

    @@ -893,15 +899,14 @@

    Act 4: Hello JavaScript</table> <script type="text/javascript"> var map = L.map('map').setView([34.055, -118.35], 9); - var mapquestLayer = new L.TileLayer('http://{s}.mqcdn.com/tiles/1.0.0/map/{z}/{x}/{y}.png', { + var osmLayer = new L.TileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { maxZoom: 18, - attribution: 'Data, imagery and map information provided by <a href="http://open.mapquest.co.uk" target="_blank">MapQuest</a>,<a href="http://www.openstreetmap.org/" target="_blank">OpenStreetMap</a> and contributors.', - subdomains: ['otile1','otile2','otile3','otile4'] + attribution: 'Data, imagery and map information provided by <a href="http://www.openstreetmap.org/" target="_blank">OpenStreetMap</a>.' }); - map.addLayer(mapquestLayer); + map.addLayer(osmLayer); </script> - </body> -</html> + </body> +</html>