Skip to content

Latest commit

 

History

History
128 lines (119 loc) · 5.5 KB

DETAILS.md

File metadata and controls

128 lines (119 loc) · 5.5 KB

Madison Technical Document

The Code Explained

Here we will provide documentation as the code stands at the point of release. Right now, running code lives at www.KeepTheWebOPEN.com. Most of the files are commented internally, but this documentation will provide a broad overview of the application's functionality.

  • A structural dump of the database as it currently exists has been included in the root folder
    • The documents are broken up into sections of text content that define editable areas. The number of rows for each document's content is currently in the 100-600 range.
    • The documents also have note and note meta tables. Each note is either of type comment or suggestion. The notes for each document range from 0-600 rows. The note meta rows count the values of likes, dislikes, and flags for each note.

Index.php

This file simply includes inc/init.php which is the controller for the application.

Assets

This directory holds the project's css, js, and media files. These are specifically for organization and still need to be included in the code itself (ie. css and js files are not automatically included).

  • css
    • Currently there are slug-specific files that are only loaded on their respective pages to emphasize certain passages
  • i
    • holds all the application image files
  • js
    • markup-slider.js
      • Custom javascript included for the sopa-markup view
    • jquery.min.js
      • Minified jquery v. 1.6.4
    • edit_user.js
      • Custom javascript for the edit-user view
    • bill-reader.js
      • Contains front-end functionality for interactivity
        • get_section
          • Grab bill section from SESSION bill object
          • posts to jquery.php (action: get-section)
        • init_reader
          • Set up passage click listeners
          • loads notes (load_notes)
        • strip_html
          • Cleans string of known html
        • load_notes
          • Loads all notes for a selected passage
          • Posts to jquery.php (action: get-notes-by-part)
        • ldf_note
          • Like, dislike, or flag a suggestion or comment
          • Posts to jquery.php (action: add-ldf-note)
        • choose_note
          • Choose between commenting on a passage or suggesting an edit to a passage
        • add_note
          • Adds a note to a passage
          • Posts to jquery.php (action: add-note)
        • preview_suggestion
          • Add a note to a passage
          • Posts to jquery.php (action: preview-suggestion)
        • show_popup
          • Show link or share popup
          • posts to jquery.php (action: get-short-url)
  • pdfs
    • holds all the application PDFs

Docs

Documentation generated by PHPDoc. This documentation is very limited, as we did not follow the PHPDoc standards uniformly throughout the application. The current comments will need to be cleaned up and the PHPDoc standard should be followed moving forward.

Inc

This directory holds the application files themselves. Init.php is located in this directory, which is the controller for the application. This directory includes the following:

  • Facebook/
    • The facebook SDK
  • Livestream/ --should be removed--
    • Temporary directory serving a specialized streaming function.
  • Scripts/
    • populate_top.php
      • This contains the functionality for determining the 'best comments/suggestions'. It currently only pulls out the top 'notes' and puts them in a table by themselves. It should be run on a cron.
  • Views/
    • This folder holds the views for the application. Each file has its functionality prepended to the filename (ie. view-about.php is the about page view).
  • Helper PHP Classes
    • User.class.php
    • Postmark.class.php
    • Object.class.php
    • Db.class.php
    • Bill.class.php
  • Facebook.php
    • Config file for Facebook implementation to stream the Oversight Committee debate on the SOPA bill.
  • Jquery.php
    • This is the main ajax functionality for the application. The front-end ajax calls reference this file.
  • Email.php
    • The email template used when sending emails.
  • Cacert.pem
    • Bundle of CA Root Certificates extracted from Mozilla's root certificates. This file can be found at the following location in the mozilla source tree:
      • /mozilla/security/nss/lib/ckfw/builtins/certdata.txt
  • Functions.php
    • Contains helper functions used throughout the application:
      • archive_companies
        • input: (string) comma delimited list of company ids
        • output: archives companies in the database
      • approve_companies
        • input: (string) comma delimited list of company ids
        • output: approves companies in the database
      • get_bill_by_slug
        • input: (string) bill slug
        • output: (int) bill id
      • redirect
        • input: (string) url
        • output: redirects using php header location function and exits
      • email
        • input: (string) email, (string) subject, (optional)(string) message
        • output: sends email using the Postmark API (postmark.class.php)
      • get_url_contents
        • input: (string) url
        • output: curls the url and returns the contents
      • get_header
        • input: none
        • output: starts the html markup, the header markup, and the body markup up to div#content
      • get_vids() --should be removed--
        • input: none
        • output: html markup for homepage youtube videos
      • get_footer()
        • input: none
        • output: html markup for page footer
  • Config.php
    • Hold configuration settings and credentials for the application such as defined constants, api keys, db credentials, and table name definitions
  • Init.php
    • This is the controller for the application
    • Handles all GET requests
    • Handles all POST submissions
    • Instantiates initial classes
    • Handles email and Facebook logins
    • Determines the view
    • Displays the view