/core/notes.php

<?php


?>

Render Buffer
===============================

-Instead of dumping raw HTML to the PHP output buffer, we render our template code to a separate render buffer. This
allows objects further down the pipeline to abort the rendering process if they hit an error.

For example:

1) a page module initiates the rendering process
2) ...and calls an album module
3) ...which calls a media module

There are several possible outcomes:

a) The item doesn't exist - so we would want to throw a 404 (if the user-agent is a bot) or redirect (if the user-agent is a browser)
b) The item exists, but the user-agent is a bot and the server is overloaded - so we want to throw a 429
c) The item existed but was deleted - so we want to throw a 410
d) The item exists and we want to show it - so we want to render the media item

In cases a) through c) we'd want to abort the render process, zero the render buffer, re-load it with the correct HTML, and
then send it to the user-agent. This is not possible to do using conventional WordPress templates.


Headers
===============================

-We probably also need to bypass the WordPress header generation process, because WP appears to automatically send these




###################################################################################################


URL's -vs- AJAX -vs- GET
========================

-The purpose of URL's and encoding things as fake directories in the URL is to give search engines a hierarchical tree of
data to crawl. Fetching content this way carries a big penalty because WP/BP/BPM has to disassemble the URL, figure out
what page/plugin/module/action/etc should be given control, render an entire web page, and then send it to the user.

-That's why most social networking sites use very limited URL schemes. Google+ is 4 levels deep, then uses AJAX. Facebook
is 2 levels deep, then uses GET variables to encode data + AJAX to fetch content.

-For any crawlable pages, we should encode the variables in directories. For all other actions, we should use AJAX, because
it provides the best user experience.



FEATURED MEDIA
=======================

/featured_media/	- First page of results
/featured_media/p/X   - Page X of results

Links jump to:

/group_album/group_id/a/album_id/m/media_id/
/user_album/user_id/a/album_id/m/media_id/

- Its impossible to include more control in the URL because the next logical step is "filtering" (show only videos, show only images),
and the next step after that is "ordering" (most popular, most views), and the next step after that is multi-dimensional sort / filter / search
(show only "videos" of "skydiving" ranked by "most views"). This is what YouTube does, with about 25 drop-down boxes, using AJAX.

-So in *this case* just jump directly to the AJAX for this functionality because the URL encoding would be practically impossible.



FRIENDS MEDIA
=======================

/friends_media/user_id/ - First page of results for user_id
/friends_media/user_id/p/X - Page X of results for user_id

Links jump to:

/user_album/user_id/a/album_id/m/media_id/

-Media items are always nested inside an album in the URL. This gives us the album_id and media_id simultaneously, so we can run two DB calls in parallel
(via AJAX or node.js) to build the page instead of first fetching the media_id info, then using the album_id stored in the record to fetch the album_id info. This is probably
why Google+ and Facebook encode both ID's in the URL.



GROUP ALBUMS
=======================

URL'S

/group_albums/group_id/ - First page of albums
/group_albums/group_id/p/X/ - Page X of albums


...links jump to: /group_albums/group_id/a/album_id/

/group_albums/group_id/a/album_id/ - First page of media items inside album "album_id"
/group_albums/group_id/a/album_id/p/X - Page X of media items inside album "album_id"

...links jump to: /group_albums/group_id/a/album_id/m/media_id/

/group_albums/group_id/a/album_id/m/media_id/ - Media item "media_id" inside album "album_id"

ACTIONS

All actions are done using GET variables.



MEDIA OF USER
=======================

URL'S

/media_of_user/user_id/ - First page of media items
/media_of_user/user_id/p/X/ - Page X of media items

...links jump to: /user_album/user_id/a/album_id/m/media_id/

/user_album/user_id/a/album_id/m/media_id/ - Media item "media_id" inside album "album_id"




USER ALBUM
=======================

URL'S

/user_album/user_id/ - First page of albums
/user_album/user_id/p/X/ - Page X of albums

...links jump to: /user_album/user_id/a/album_id/

/user_album/user_id/a/album_id/ - First page of media items inside album "album_id"
/user_album/user_id/a/album_id/p/X - Page X of media items inside album "album_id"

...links jump to: /user_album/user_id/a/album_id/m/media_id/

/user_album/user_id/a/album_id/m/media_id/ - Media item "media_id" inside album "album_id"

ACTIONS

All actions are done using GET variables.



ALBUM MODULE AJAX SCHEME
=========================

-If a user is inside a page module which:

    a) Renders only album modules
    b) Should logically give users the ability to create new albums
    c) The user has permission to create new albums

-Then, the page module should:

    a) Display a link or button offering to create a new album
    b) Attach JS code to the page to open the create new album dialog
    c) Attach CSS styles to the page describing how to style the create album dialog

-When a user clicks on the "create new album" link or button:

    a) The JS code should post a request to the server containing
	1) The method, function, etc, variables to tell the server which AJAX handler to run
	2) The page_module id (used to tell the difference between creating User Albums and Group Albums)
	3) The user_id (used to check authorization)

    b) The server should check authorization, and kill the process if the user is not authorized to continue

    c) The server should respond with the rendered HTML to load into the dialog box, containing:
	1) A list of the album types a user can create, with the number used and the number remaining (this avoids having to load the entire album module stack on every page view)
	2) A button to create an instance of each album type (disabled if the user has hit their quota for that album type)
	3) Encoded height and width parameters for the next dialog box for each album module (required by jQuery)

-When the user clicks on a "create album instance" button:

    a) The JS code should post a request to the server containing
	1) The method, function, etc, variables to tell the server which AJAX handler to run
	2) The page_module id (used to tell the difference between creating User Albums and Group Albums)
	3) The album_module id (used to determine which module's form to load)
	4) The user_id (used to set album owner if its a user album)

    b) The current dialog box should close with a fade-out effect (decreases perceived server lag due to page "doing something" while load is in progress)
    c) A new dialog box should open with a fade-in effect, sized to height and width set by the album module
    d) The dialog box should display an animated "loading" GIF until the server has filled the request

    e) The server should check authorization, and kill the process if the user is not authorized to continue

    f) The server should respond with the rendered HTML to load into the dialog box, containing:
	1) All data fields required to create the album type
	2) A "Cancel" button, which closes the dialog
	3) An "OK" button, which submits the create album request


-When the user clicks on the "OK" button:

    a) The JS code should post a request to the server containing
	1) The method, function, etc, variables to tell the server which AJAX handler to run
	2) The page_module id (used to tell the difference between creating User Albums and Group Albums)
	3) The album_module id (module's handler to use)
	4) The user_id (used to set album owner if its a user album)
	5) All data fields used to create the album instance

    b) The current dialog box should dim and display an animated "working" icon

    c) The server should check authorization, and kill the process if the user is not authorized to continue

    d) The AJAX handler should pass the data to the correct album module's "create" function
    e) The create function should run all data through the DB sanitizers and note any failed fields

-If there are failed fields:

    a) The create function should abort the create process and pass a BPM error object back to the AJAX handler

    b) The AJAX handler should parse the error object into
	1) The failed field names
	2) The reason each field failed

    c) The AJAX handler should JSON encode the data and send it back as a response to the JS code in the browser

    d) When the JS code receives the fail response, it should:
	1) Un-dim the dialog box and remove the "working" icon
	2) Reset all fields in the form to default status (handles case where the user has submitted the form, had failed fields, then corrected one or more failed fields)
	3) Fade the background color of each failed field to yellow
	4) Insert a tool-tip bubble above each failed field explaining why the field failed

-If there are no failed fields:

    a) The create function should create an album instance and pass a success status and album_id back to the AJAX handler
    b) The AJAX handler should JSON encode the response and send it back to the JS code in the browser

    c) When the JS code receives the success response, it should:
	1) Close the dialog box
	2) Redirect the browser to the new album's landing page