Color

This project is online at color.lukas-stratmann.com. Alternatively, you can run the debug version on your local machine as described in Installation for Development and Testing or host the project yourself as described in the section Deployment.

Project Structure

Important folders and files (with relevance to this project) are written in bold letters.

• app: Symfony folder
  • config: Symfony configuration files
    • parameters.yml: Database and mailing configuration. Important for running the experiment. (Excluded from git.)
    • security.yml: Site access to specified user groups can be configured here. Would have to be edited to re-enable the experiment.
  • Resources:
    • views: Site contents stored in Twig HTML templates
    • students.txt: For the experiment: List of university email addresses of all students attending the lecture. (Excluded from git.)
• bin: Symfony folder
• src: Symfony folder containing the relevant PHP code.
  • AppBundle/Controller/MainController.php: Site routing definition
• tests: Symfony folder
• var: Symfony folder
• vendor: PHP dependencies installed with Composer (excluded from git)
• web: The only folder visible to the public. Your domain should point here!
  • node_modules: Local dependencies installed with npm (see Step-by-Step Guide below). (Excluded from git)
  • resources:
    • css:
      • *.less: Edit these files to change the look of the site.
      • *.css: Generated from the *.less files using Less CSS.
    • img: Images go here
    • js: Javascript code!
      • build/color.compiled.min.js: Only self-made Javascript file needed for running the site.
    • shaders: GLSL shaders for the visualizations
  • package.json: Configuration file for Node.js and npm
  • other files in this directory: Either generated by Symfony or favicon-related
• build-js.sh: Run this to re-build web/resources/js/build/*.

Installation for Development and Testing

Step-by-Step Guide: Running on a Local Machine

1. Copy or git clone the project to a directory of your choice and cd to that directory.
2. Make sure PHP is installed. (Tested with PHP 7.0. On Debian-based systems, run sudo apt install php7.0 to install.)
3. Install the XML extension for PHP (e.g. sudo apt install php7.0-xml)
4. Install dependencies for the Symfony framework via php composer.phar install. If you are deploying a published version, use the following command instead: ./symfony_deploy.sh. You may need to replace the call to php with php[x]-cli, where [x] is the PHP version number. You will be prompted to enter the database host. If you are installing on a local machine, the default 127.0.0.1 is fine. The same goes for the other settings, which can still be changed later by editing the file app/config/parameters.yml. Providing the database settings is necessary if you plan to run the experiment again (disabled by default).
5. For the Javascript and other dependencies we need the Node Package Manager (npm): sudo apt install npm.
6. Run ./install_production_dependencies_only.sh. If you also want to build the sources, run install_dev_dependencies.sh instead and refer to the section List of Dependencies below for installing all modules that are assumed to be installed globally.
7. Now you can execute ./run_local_php_server.sh and visit the given address (typically http://localhost:8000) in your browser.

List of Dependencies

This project uses bower for managing client-side dependencies, which are listed in bower.json. After cloning this project's repository, simply run bower install. For development dependencies, the project makes use of the Node.js Package Manager. After cloning, run npm install for both development tools and client-side tools which are required by some of the former. To install only the latter, run npm install --production.

Development dependencies (mostly run automatically in WebStorm's File Watchers):

• babel for compiling ECMAScript 6 into ES5 compliant Javascript. Apparently, even modern browsers don't support ES6 modules yet.
• lessc for compiling Less CSS into regular CSS. This needs to be installed globally via sudo npm install -g less.
• browserify for a "require" that works in the browser. Otherwise, individual .js files would quickly become bloated. This needs to be installed globally via sudo npm install -g browserify.
• babelify: A combination of babel and browserify.
• browserify-shader plugin for browserify for including external shader text files in javascript.
• uglify-js for minifying Javascript. This needs to be installed globally via sudo npm install -g uglify-js.

Deployment

1. Follow the Step-by-Step Guide above up to step 6. If your hosting provider does not allow you to install software like npm and if npm is not already provided, you can first execute the steps on a local machine and then upload the project to the server (the folder web/node_modules in particular, in case the rest of the project is already uploaded).
2. If you make changes to the PHP code or any of the Twig templates in app/Resources, remember to empty Symfony's cache via php bin/console cache:clear -e prod. (php may need to be replaced with php[x]-cli, where [x] is the PHP version number.)
3. Do not have your domain point at the root project folder! Only the web directory is supposed to be public.

PHP

Dependencies for PHP development are installed to ./vendor via php composer.phar install. The file composer.lock specifies the exact versions of the original installation.

To run a debug server, execute php bin/console server:run.

This project uses Symfony and, for templating, Symfony's Twig. knpuniversity's video tutorials are highly recommended!

Symfony

Useful resources:

• Registration form: http://symfony.com/doc/current/doctrine/registration_form.html
• Login form:
  • http://symfony.com/doc/current/security/form_login_setup.html
  • http://symfony.com/doc/current/cookbook/security/form_login_setup.html
• Load users from DB: http://symfony.com/doc/current/security/entity_provider.html
• Access control, ROLEs: http://symfony.com/doc/current/security.html

Experiment

Enable / Disable

TODO!

Registration

RegistrationController.php will check for the file app/Resources/students.txt. If it exists, it acts as a whitelist. If it doesn't exist, everyone may register.