Controller Marks

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

Controller Marks

Methods

__construct - Public

add - Public

Request Types

Query Parameters

Example Request

archive - Public

Request Types

Example Request

check - Public

Request Types

Example Request

delete - Public

Request Types

Example Request

edit - Public

Request Types

Query Parameters

Example Request

get - Public

Request Types

Child Methods

index - Public

Request Types

Lookup Options

Sorting Your Results

info - Public

Request Types

Example Request

random - Public

Request Types

Example Request

restore - Public

Request Types

Example Request

total - Public

Request Types

Child Methods

Setting Time Ranges (Internal Calls)

Example

Setting Time Ranges (Request Based)

Example (same as above example)

Clone this wiki locally

`__construct` - Public

`add` - Public

`archive` - Public

`check` - Public

`delete` - Public

`edit` - Public

`get` - Public

`index` - Public

`info` - Public

`random` - Public

`restore` - Public

`total` - Public