13DTP

From fridges to toilets, from watches to phones, from TVs to security cameras - almost everything these days has a web browser - so if you want to make a truly cross-platform application then a web-app is the ideal way to go.

So, this year you will be making a complex database-backed web-app / website using Python, SQL and HTML5.  You'll learn how to make complex SQL queries to an SQLite database from a Python app running the Flask web framework - and how to then present that information to the user in a professional way using HTML, CSS and potentially some Javascript.

Achievement Standards

The 4 main standards for the Year 12 Software Engineering and Computer Science course are:

Internal

6 credits - Programming - AS91906

4 credits - Database - AS91902

4 credits - Media (Web) - AS91903

----

14 credits - pass  (͡ ° ͜ʖ ͡ °)  


External

3 credits - Computer Science CAT External - AS91908 - very important for nerd street cred, and also for subject endorsement (those are basically the same thing)


NOTE: If you are taking Game Design or Product Design then some of the above standards may cross over, so it is up to you to make sure your teachers know about this - you can not sit the same standard in two subjects and get credits for each one - so alternative standards need to be arranged.  We can only do that for you if we know about it - so make sure you discuss this with your teachers at the start of the course.

Taking Notes

DON'T waste time taking notes in a doc - use paper and a pen.  You'll remember more.  This is doubly important for things like ER diagram design.  Don't waste time trying to make a pretty graphical version on the computer - draw boxes and lines and get it done - its easier, faster and much more 'editable'.

You will be told this over and over - and there is sound scientific basis for it.

https://commons.lib.jmu.edu/cgi/viewcontent.cgi?article=1056&context=lexia

https://www.scientificamerican.com/article/a-learning-secret-don-t-take-notes-with-a-laptop/

SETTING UP and getting going

Planning Your Project

"Your plan should be a document you could give to another developer, and have enough detail that they could hand you back the finished product" 

A plan gives you direction and help ensure you know what you're doing in your project.  In the real world it mirrors a kind of specification document, signed off between you and a customer to ensure everyone is on the same page - which means there should be no arguments when it comes to getting paid when it's done - which is somewhat important.  

It needs to be complete by the end of the first term so that you're ready to start the project at the beginning of term 2.

Your plan should be a document you could give to another developer, and have enough detail that they could hand you back the finished product.  In practice it will also form part of the evidence you need for the standards - so check those as well to make sure you're ticking boxes... ticking boxes is very importa... darn, I can't say that with a straight face.  But you do (probably) want to achieve the three standards tied to this project.

Your plan should cover most or all and maybe more than the following:

* a Flask route, eg:  @app.route('/pizza/<int:id>')

** a function signature is just the first line of a function, eg:  def pizza(id):

Note: the route and the function name do not need to match, but they probably should where they can.


Getting Started:

The simplest way to get started is to imagine yourself as a visitor to your finished site.  What would you expect to see?  What pages would you want?  What information would you want to find?  Start mind-mapping this information on paper.  Note: a sheet of paper and a pencil is far easier than trying to write this into a doc - just scribble notes, draw lines between connected bits of information and start to form the basis of your database design by working out what information you need to store.  Then when you're done simply scan or photograph these notes and put them in your planning doc.

The pages you think you'll need on the site will also help you consider the queries you will need from your database as well.  For example, a Pizza site would likely have a page listing all the pizzas - and this might need the names of the pizzas, and pictures.  It will also need the id's of the pizzas in order to link to a page that shows details of a specific pizza - SELECT id, name, photo FROM Pizza; is the likely query for this page.

At this point, you should jot down the route and function signature for this page - most likely something like @app.route('/all_pizzas') and def all_pizzas(): respectively.

This should then lead you to thinking about how that 'All Pizzas' page might look.  Will it be a simple drop-down list, or a fancy grid of names and photos, with each photo and name linked through to a 'Pizza Details' page (make a note to design that page next).  The link will need to include the id, so you might look something like this: 

<a href="/pizza/{{ pizza[0] }}> <!-- link to pizza details page -->

  <img src="/static/images/pizzas/{{ pizza[2] }}" />

  <br />

  {{ pizza[1] }}

</a> 

This assumes the details are in a list called pizza, with pizza[0] containing the id, pizza[1] the name of the pizza and pizza[2] the photo link - You should also be laying out the design and make notes about possible colours and fonts and any special functionality the page should include.  

At this point you've also had to consider file management for the images - so make notes about that as well - will all images just go in /static/images or will it need to be more complex?

NOTE: The plan doesn't need to include code, but sometimes it's helpful to write code ideas or actual test snippets and then put them in the plan so you can refer to them later on.


Moving Forward:

Remember that this is a living document, and it should be about a process, not the end product - so DON'T delete things and replace them - if you change something in your design, document the changes from your original and explain why you changed it - this shows your journey.  The finished project will show the destination.

 

Flask & PYTHON

Flask Hello World - Scroll down to the end

Flasking a little bit harder - multiple and dynamic routes

Flasking from a database - SQLite database connections

Templating with Jinja - How to lay out the HTML side of your project

Tech with Tim- Full Video series covering flask and sqlalchemy

Pretty Printed- Complete Flask-SQLAlchemy course for free

Flask Common Tasks- By SRCoder. Lots of real examples for most of what you need to do.

The BackPack Project- Video series from zero to Database driven Flask App


USEFUL PYTHON LIBRARIES / CHEAT-SHEETS

SQLite

SQL Basics

SQLite and SQLite Studio - the Pizza database

SQLite in Python

ER Diagrams

Flasking from a database - SQLite database connections

SQLAlchemy - Making SQL stupidly easy

https://www.gormanalysis.com/blog/intro-to-sqlalchemy/ - SQLAlchemy Intro (NOT Flask, but useful tips)


HTML & CSS

FLASK WTF - FORMS

Project Requirements

The project lasts for two terms - this means you have nearly 20 weeks to work on it, and the expectations are that it will look like 20 weeks worth of coding and learning with a commensurate level of complexity involved.  The kinds of things you are expected to have in the final project are:

Many-To-Many relationship(s)

at least one, implemented AND used in your site.

Online editing

You are expected to be able to edit at least one field in one table from the website - this could be from an online form used to add a new item to the database, or to update existing data.

Comments

Python, HTML, Jinja and CSS all have commenting facilities that should be used appropriately.  DON'T over-comment, Python is fairly well self-commenting due to the readability of the language itself.

✗ a=5  # create a variable called 'a' and set it to the integer value of 5

✓ user = User.query.filter_by(username=form.username.data).first()  # not first_or_404() - need to know if User is None

Remember that HTML comments are almost always visible to the end user (unless blocked by some Jinja logic) but Jinja comments are always removed when the template is rendered - if you don't want the comment to be visible to the end user (ie: because the comment could contain information that might help a hacker attack your site) then use Jinja comments in your templates, like this:{# comment #}.  HTML comments should at least be used to indicate the class / id of a closing div tag:

<div class="content_block">

 --- lots of HTML and stuff ---

</div>  <!-- content block -->

CSS comments should be used to show blocks of CSS, and to annotate any specific tricky piece of CSS you've used for something.

/** * NAV BAR **/

nav {

...etc

Data Integrity and Testing

Testing is the big one as far as documentation goes - you should have comprehensive testing tables, in sections indicating the page or item being tested.  The tests should explain what, how and why with expected results for a pass.  You should also have regular tests scheduled to ensure your recent changes have not broken anything. 

Data Integrity is about ensuring that the data you are storing, and the data you are displaying, is correct.  How are you testing that your site is not lying to your users? 

SQL Queries

Your plan for each data-based page on your web app should have its relevant SQL queries (not SQLAlchemy).  Your Python code will then contain the SQLAlchemy version of that (query or queries).

Your queries should just return the data you need (ie: if you just need the name of one item, don't get *, just get name.

✗ SELECT * FROM User WHERE id=1;

✓ SELECT name FROM User WHERE id=1;

Your queries need to be more complex than this as well - you are expected to have, and use, relationships in your models to retrieve 'JOIN'ed information from other tables.

Iterations

The Media and Database standards require you to have 'Iteratively Improved' each.  The wording is obscure, and the meaning unclear - but to cover this you should have broken the development into 'iterations' or stages of development - each being a self-contained chunk of improvement with a testable and working subset of the final outcome.

HCI

Your final product should provide a demostrably good user experience and the actual design should be in line with evidence-based research - most likely Nielsens Heuristics (www.nngroup.com).  You should have also tested your site on stakeholders (users who actually care about what you are doing) and have feedback on the interface which you have addressed (this will also fall into testing and perhaps an iteration of your development cycles as well).

Relevant Implications

 You need 2 for Database, and 2 for Media (web).  You need to explain how each is relevant to your project, and then how you mitigated any issues around them.

Language Conventions

In Python, PEP8 is the document that contains the conventions for the language - predominantly you should ensure you have used proper variable, function and class naming conventions, proper commenting, the correct number of blank lines between functions / classes / imports and the rest of the code, line length (where appropriate - do NOT treat line length as a commandment - overall readability and common sense take precedence here) etc.