Lab3 - Second Version

Normal Deadline: Monday, 06 February 2017


PREPARE FOR A BIG INCREASE IN LEVEL OF DIFFICULTY

We were unable to do much in Lab2 last week as it was a public holiday so some parts of Lab2 is deferred to this Lab3... Hang on...

Basic technical requirements:

1. Laravel Setup @ DO Droplet

This short guide assumes that the pair/triple of you have cleared the important task in online Lab2, i.e. spinning a new Digital Ocean (DO) Droplet with LAMP (Linux/OS Apache/Web-server MySQL/Database PHP/Server-side-scripting) stack on Ubuntu 16.04 and understand how to upload your Lab1-2 work (your HTML/JS/CSS files) there so that your (currently static) web application can be publicly accessed by anyone who has Internet access and knows the IP address of your DO droplet.

We will now proceed to install the Laravel dependencies, spin up a new Laravel project, and get it working.

This section is actually optional if you+your team mate(s) have setup and use Laravel beforehand (and still remember the exact steps). But since almost all of you have never used Laravel before (except 2-3 out of 49 students; based on Lecture 01 quick survey and Lab1 observation), please read on.

Here are a few more detailed steps to install Laravel at fresh copy of DO droplet with LAMP stack on Ubuntu 16.04. If you use another web server with different setup (different OS or OS version/web server/database/server-side scripting language), this guide may be 'wrong' and you have to find the solution yourself... Unfortunately there is no faster way as there is not yet one-click app to auto-prepare a DO droplet with Laravel setup yet... Btw, in the event you get stuck, try Googling online for potential solutions before asking your Lab TA. Note that some of these steps may have changed (a bit?) by the time you read this document...:

  1. Install Laravel setup dependencies by running the following commands.
    Use sudo if you have permission issues (you should not encounter such thing if you are logged in as root).
    Replace [YOURPROJECTNAME] with your chosen project name.

    # you can read online documentation at https://getcomposer.org (Composer website)
    # to self-learn the details about installing Laravel and the required PHP libraries
    # that are needed by Laravel (version 5.3 or the newly released 5.4)
    # but not installed by default in DO droplet with LAMP stack on Ubuntu 16.04
    sudo apt-get install composer php-mbstring php-xml zip unzip php7.0-zip
    
    # change directory to /var/www/html/ and create a new Laravel project (will take time)
    cd /var/www/html/ && composer create-project laravel/laravel [YOURPROJECTNAME]
    
    # change a few directory permissions so that Laravel can write new files on them:
    chmod o+w /var/www/html/[YOURPROJECTNAME]/storage/framework/cache
    chmod o+w /var/www/html/[YOURPROJECTNAME]/storage/framework/sessions
    chmod o+w /var/www/html/[YOURPROJECTNAME]/storage/framework/views
    chmod o+w /var/www/html/[YOURPROJECTNAME]/storage/logs
    
  2. Configure Virtual Host
    Create a file called /etc/apache2/sites-available/[YOURPROJECTNAME].conf with the following content.

    <VirtualHost *:80>
      DocumentRoot <path_to_your_project_folder>/public
      Errorlog <path_to_your_project_folder>/storage/logs/error.log
      <Directory <path_to_your_project_folder>/public>
        Require all granted
      </Directory>
    </VirtualHost>
    
    We use this step so that the document root is no longer the default /var/www/html but path_to_your_project_folder/public (do not forget the /public subfolder so that we only expose the public folder of our project to the Internet but not anything else...)

  3. Test virtual host configuration using apache2ctl -t.
    Syntax OK means everything will be ok.
    Disable the default site with a2dissite 000-default.conf.
    Enable your new site with a2ensite [YOURPROJECTNAME].conf.
    Restart Apache with service apache2 reload.
    Access your new project by entering the IP address http://aaa.bbb.ccc.ddd of your server in the browser (assuming that you haven't do the domain name registration that we will do later in Lab6).
    A standard Laravel project page should appear. Check your error logs if there is any issue. Google around for debugging, discuss among the pair/triple of you, and only consult Lab TA as the last resort...
  4. Congratulations, you have set up Laravel successfully.

2. Retry Lecture 06 Example

Finally... a working dummy Laravel project. At this point, you may want to repeat the example from Lecture 06 - Front-End about Laravel basic Routing, Blade Template, Child Pages, and Custom Controller to strengthen your understanding of these concepts...

3. Migrate To Laravel

Now look back at your Lab2 work. If you have completed Lab2 successfully, you should have 'index.html', 'help.html', and at least 3 student-detail-page.html'.

Now let's migrate into Laravel format and appreciate that some steps that you have did in Lab1-2 are now much easier with this framework (after you understand how to use it).

First, make FOUR (4) Views in Blade format:

  1. ONE (1) template 'resources/views/template.blade.php'
    You are required to abstract out common features of the HTML files in your project into this base template.
  2. THREE (3) child pages: 'resources/views/index.blade.php', 'resources/views/help.blade.php', and 'resources/views/detail.blade.php'
    All these child pages should extend the template.

Then, make ONE (1) Controller: 'app/Http/Controller/StudentController.php' to control TWO (2) different routes: '/' and 'student/{id}' (for now).

Then, update 'routes/web.php' to contains at least these THREE (3) routes (with additional route 'help'):

<?php
Route::get('/', 'StudentController@index');
Route::get('student/{id}', 'StudentController@detail');
Route::get('help', function() { return view('help'); }); // direct controller

The StudentController must take in an {id} and for now, generate a dummy detail view with just one simple statement: "This page will show the details of student with this id.".
This {id} can be any integer from [1..N], not just for 3 out of N students as with Lab1-2.

Notice that your project starts growing bigger.
Please use GitHub (or other relevant software) for version control and for collaboration with your team mate.

4. Responsive Design Requirement

The ranklist app in Lab2 does not look as good as the version on the computer if loaded on small screen. The text and pictures are too small and the user has to zoom in and out, scroll left/right/up/down to see the entirety of the ranklist/detail page. Please make the application works well on mobile devices too. Prevent side scrolling and ensure that users on mobile devices just need to scroll vertically. You are allowed to collapse/hide some details on smaller screen.

As an example, see the behavior of the live version and try to mimic (or even improve) on it.

Use Bootstrap to make the appearance of your ranklist app as good as possible on various screen resolutions as taught in Front-End (Bootstrap) lecture.


The Extra Challenges for Lab3:

  1. INCLUDE NAVBAR AND FOOTER (EASY):
    You have actually been shown on how to include footer in the class. Now please include common footer AND common Bootstrap Navbar in your project. Notice that the live version already have them.

  2. PREPARATION FOR DATABASE ACCESS (MEDIUM):
    For Lab3 basic requirement, we only expect simple dummy page with parameterized content, the {id}, i.e. "This page will show the details of student with this id." when route student/{id} is accessed. You have learned JavaScript array by now and will learn similar PHP array soon. Why don't you store the (currently random/dummy) scores of ALL N students in your StudentController (yes, bad practice for now; we will use Model/Laravel Eloquent database soon) so that the ranklist is generated from this array data and whenever the details of a student with a certain {id} is requested, we can generate the customized view from this array data too. We will test this by asking you to populate N = 50 (not just N = 7) random students data, and your ranklist (the sums, etc) and detail page of every student must be consistent with the one displayed in the ranklist. During checking, we will ask you to change one random number of random student on the spot, and only by changing that one number, the ranklist and the detail page are also updated accordingly (including all the highlight for gold/silver/bronze/pink that you have done in Lab2, etc). PS: You will not want to enter 50 random data manually, so we recommend you to self-learn this.

  3. HTML5 CANVAS DRAWING CHALLENGE (MAY NOT BE THAT CHALLENGING*):
    Show a Radar Chart view of the (fictional) scores of your N students. Upon clicking the detailed view of a certain student {id} (route /student/id), there should be 6 variables in the chart: MC, TC, HW, Bs, KS, and Ac that describes {id}'s scores on those components against the possible maximum scores (or against the current leader's score). This visualization can give viewer the rough information on what component this student is strong/weak at... in a glance... As we have not learn how to access Database, just make up the numbers randomly for now. What is tested is the drawing part. But if you are claiming for the previous "PREPARATION FOR DATABASE ACCESS" above, your (random) numbers must be consistent!...

    *if you know something

FAQ

  1. Q: Help, me and my team mate(s) are still unable to setup a working DO droplet mentioned in Lab2 that is required to complete this Lab3...
    A: You need to contact your Lab TA for help by now...

Additional Server Setup

We concentrate on Laravel in Lab3-6.
However, if you are interested to build Single Page Application (SPA) especially using Node.js, here is additional self challenge for you/your group (optional):

  1. NodeJS and tools
    If you want to develop those cool, interactive, flashy web apps, you will end up doing a lot of Javascript work.
    NodeJS has a LOT of modules out there that can make whatever you want to do much easier.
    So we'll install NodeJS and NPM (NodeJS' package manager) using apt-get install nodejs npm.

    In most Linux distributions, NodeJS command is node but in Ubuntu it is nodejs.
    This is a problem if you try to run gulp later.
    Let's make a symbolic link to fix that ln -s $(which nodejs) /usr/bin/node then run node -v to test that it works.

    We move on to essential tools for Javascript code: Gulp and Webpack.
    Laravel has kindly configured Gulp and Webpack for us so all we need is to install them.
    Install Gulp with npm install -g gulp.
    Install all other NodeJS dependencies (listed in *package.json*) with npm install.
    Running gulp should generate files in public/css and public/js folders.

    Note: As a common practice, do all Javascript development in resources/assets/js and all SASS/CSS stuff in resources/assets/sass.
    Gulp/Elixir will compile/transpile and bundle them up for you.

  2. Swap Files
    Refer to this section only if npm install is giving you a whole bunch of errors, like getting killed.
    This is very likely if you have less than 1 or 2 GB worth of memory.
    NodeJS stuff tend to consume a lot of memory, so chances are you ran into out-of-memory errors.

    If it is your own machine, why didn't you create a 4GB swap partition when you installed Linux?
    If you are running a 512MB memory Digital Ocean droplet (the cheapest one, which we assume you do), it doesn't come with a swap partition.
    Might be because it is not possible to set it up in virtual machine?
    Anyway, check out [Adding Swap Space] (https://www.digitalocean.com/community/tutorials/how-to-add-swap-on-ubuntu-14-04) for how to do it.

Lab TA Checklist

  1. Showcase the selected best Lab1+2 work so far.
  2. Try our best to help group who still have issue(s) with setting up Laravel in their own DO droplet.
  3. Review the concept of Laravel Blade Templates, the Model-View-Controller (MVC) idea advocated by Laravel framework, mention for now that php file is an html file that may have some 'server-side executable' scripts inside it.
  4. Check how each project group manage the work, i.e. are they using version control software like GitHub?
  5. Test the responsive design of each group (should be relatively easy with help of Bootstrap framework).
  6. Grade groups who have completed Lab3 basic requirements and nominate the best two lab works in your lab group so far to be showcased, especially those who have interesting nice features that differentiate them with the other groups (the navbar, Laravel Faker, Radar Chart, or others...).