Skip to content

Controller Marks

Jump to bottom Edit New page
Jeff Johns edited this page Apr 4, 2014 · 7 revisions
Controller Extends Path
Marks Plain_Controller /application/controllers/marks.php

This controller handles the login view as well as processing the login requests.

Methods

__construct - Public

Called automatically which in turn calls the parent constructor, it also does the following:

  • Redirects the user if NOT logged in
  • Loads the user marks model

add - Public

Used to handle all primary requests to add a new mark to the system and to the user. Mark URLs are unique in the system. If it already exists we don't add it again, will simply extract its mark_id and make the relationship to the user. If it does NOT exist, we add the mark and then make the relationship.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View Yes

Query Parameters

Variable Type Default Required Options Description
$url String N/A Yes N/A The URL to add.
$title String No Title No N/A The page title from the URL.

Example Request

URL: /mark/add
Query Parameters: url=http%3A%2F%2Fwww.amazon.com%2Fgp%2Fsearch%2Fref%3Dsr_il_ti_popular%3Frh%3Dn%253A5174%252Cp_n_date%253A20140204%26sort%3Dpopularity-rank%26ie%3DUTF8%26qid%3D1389147159%26lo%3Dpopular&title=Amazon.com%3A%2020140204%3A%20Music

All your query parameters should ALWAYS be urlencoded.

archive - Public

Used to archive an existing user mark.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View No

Example Request

URL: /marks/archive/{MARK_ID}

check - Public

Used to check if the url passed is already saved to the current user's account.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View No

Example Request

URL: /mark/check
Query Parameters: url=http%3A%2F%2Fwww.google.com

delete - Public

Used to remove an existing user mark. Users marks are never really deleted, they are set to active=0. You can run a cronjob if you wish to remove all user marks that are inactive. We do this so the user doesn't have to wait for the table to reindex during a simple request like this.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View No

Example Request

URL: /mark/delete/{MARK_ID}

edit - Public

Used to edit an existing user mark. This URL is NOT accessible from a web view. Only for XMLHttpRequest and API requests.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View No

Query Parameters

Variable Type Default Required Options Description
$label_id Integer N/A No N/A The label's id to associate this user mark to. If not sent or not numeric it will not be used in the update.
$notes String N/A No N/A The notes for this mark. Any #hashmarks will be used for tags. If not sent, it will not be used in the update.
$title String N/A No N/A If you want to customize the mark's title just for you, send this param. If you want to remove your custom title, send this param but empty.

Example Request

URL: /mark/edit/{MARK_ID}
Query Parameters: label_id=5&notes=Cool%20mark%20bro.%20%23awesome&title=My%20Title

All your query parameters should ALWAYS be urlencoded.

get - Public

Used as a router of sorts to figure if a get URL is valid. If the method is found, it executes, if not it sets an error. This method saves us from having to add a new route for each /get/{WHAT} request. Now if someone requests /get/labels the request is sent to marks.get and the labels portion is used to create the method to check for.

It becomes converted to getLabels. We then check for this method. If it exists we execute it and render the JSON. If not we set the 'Invalid Request' error.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View No

Child Methods

Method Visibility Request Path Description
getLabels Private /get/labels Sets all the system level labels and gets the total marks associated to each for the user.
getStats Private /get/stats Sets all the user stats for total mark for different timeframes. It returns an array of saved (all marks), archived and marks (active marks) for various time periods. It also returns the overall total of each.
getTags Private /get/tags Sets all the most popular and most recently used tags for the current user.

You can call the above child methods directly from the marks controller by simply calling self::getStats(). All other requests need to come from and XMLHttpRequest or API request.

index - Public

Returns all the marks for the period/options provided. All marks returned are sorted from newest to oldest and 30 at a time. To read more about the data returned please click here.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View Yes

Lookup Options

Option Request Path Description
all /marks A list of all the active marks.
archive /marks/archive A list of all the archived marks.
search /marks/search?q={QUERY}&archive={1|0} A list of marks matching the query string. The query will search mark title, url and your notes. If you pass the archive param and set to 1, it will search your archived marks instead of active marks.
today /marks/today A list of active marks created today.
yesterday /marks/yesterday A list of active marks created yesterday.
last-week /marks/last-week A list of active marks created over the last 7 days.
last-month /marks/last-month A list of active marks created over the last 30 days.
last-three-months /marks/last-three-months A list of active marks created over the last 90 days.
last-six-months /marks/last-six-months A list of active marks created over the last 180 days.
last-year /marks/last-year A list of active marks created over the last year.
ages-ago /marks/ages-ago A list of active marks created over longer than a year ago.
label /marks/label/{LABEL_SLUG|LABEL_ID} A list of active marks with the label specified.
tag /marks/tag/{TAG_SLUG|TAG_ID} A list of active marks with the tag specified.
custom_date /marks/YYYY-MM-DD/YYYY-MM-DD A list of active marks within the range of dates. Dates should can be full datetime or just a year.

If no marks are found for any of the above requests, the total will be returned as 0 and the errors key will be set. For all of these requests, if calling from the web view, we will also call the following:

  • getStats
  • getLabels
  • getTags

If a label or tag lookup we will also append the following data:

  • $active_label = array('label_id' => $label_id, 'label_name' => $name);
  • $active_tag = array('tag_id' => $tag_id, 'tag_name' => $name);

They will only be set for a label or tag lookup. All other lookups will not have this data as it does not apply.

Sorting Your Results

By default we sort all marks from newest to oldest. For active marks this used the created_on column for archived marks it uses the archived_on column. If you wish to switch this sorting option you can send the sort parameter with your request. It has two options:

  • newest
  • oldest

It default to newest.

/marks/archive?sort=oldest
/marks/archive?sort=newest
/marks/last-year?sort=oldest
/marks/last-year?sort=newest
/marks/search?q=google&sort=oldest
/marks/search?q=google&sort=newest

info - Public

Returns all the information for a specific mark.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View Yes

Example Request

URL: /mark/info/{MARK_ID}

random - Public

Returns 1 random mark and its information.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View No

Example Request

URL: /mark/random

restore - Public

Unarchives a specific mark.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View No

Example Request

URL: /mark/restore/{MARK_ID}

total - Public

Used as a router of sorts to figure if a get URL is valid. If the method is found, it executes, if not it sets an error. This method saves us from having to add a new route for each /total/{WHAT} request. Now if someone requests /total/marks the request is sent to marks.total and the marks portion is used to create the method to check for.

It becomes converted to totalMarks. We then check for this method. If it exists we execute it and render the JSON. If not we set the 'Invalid Request' error.

Request Types

Type Accessible
XMLHttpRequest Yes
API Yes
Web View No

Child Methods

Method Visibility Request Path Description
totalArchived Private /marks/total/archived Returns the total archived marks for the period of time set.
totalMarks Private /marks/total/marks Returns the total active marks for the period of time set.
totalSaved Private /marks/total/saved Returns the total marks (archived or not) for the period of time set.

You can call the above child methods directly from the marks controller by simply calling self::totalMarks(). All other requests need to come from and XMLHttpRequest or API request.

Setting Time Ranges (Internal Calls)

Simply call the private method from the child list above and pass a start and finish date.

Example
$total = self::getMarks('yesterday', 'today');

// Total will equal the total active marks from yesterday
// First param is $start, second is $finish
// Query is constructed like such created_on >= $start AND created_on is < $finish
// Only the YYYY-MM-DD portion is used
// In the example above it would look like: created_on >= '2014-02-03' AND created_on is < '2014-02-04'

Setting Time Ranges (Request Based)

Simply call /marks/total/{WHAT}/START/FINISH.

Example (same as above example)
URL: /marks/total/marks/yesterday/today
Add a custom footer
Add a custom sidebar
Clone this wiki locally