Tuesday October 18, 2016

Photos Flickr Reference Manual

Photos Flickr

PRETTY FUNCTIONS

photos_photo_index()
photos_photo_pageindex()
photos_photoset_index()

GENERAL FUNCTIONS

photos_init()
photos_photo_index_href()
photos_photoset_index_href()
photos_is_photo()
photos_is_index()
photos_is_photoset()
photos_is_tag()

GENERAL FUNCTIONS: photos_photo_

photos_photo_description()
photos_photo_href()
photos_photo_title()
photos_photo_url()
photos_photo_photosets()
photos_photo_tags()
photos_photo_photoset_list()
photos_photo_tag_list()
photos_photo_page_url()
photos_photo_date_taken()
photos_photo_next_img()
photos_photo_prev_img()
photos_photo_next_href()
photos_photo_prev_href()
photos_photo_next_title()
photos_photo_prev_title()

GENERAL FUNCTIONS: photos_photosets_

photos_photoset_list()
photos_photoset_description()
photos_photoset_href()
photos_photoset_title()
photos_photoset_img()
photos_photoset_next_img()
photos_photoset_prev_img()
photos_photoset_next_href()
photos_photoset_prev_href()
photos_photoset_next_title()
photos_photoset_prev_title()

PRIVATE FUNCTIONS

PRIVATE: photos_init_phpFlickr()
PRIVATE: photos_config_page()
PRIVATE: get_flickr_user()
PRIVATE: photos_flickr_config_page()
PRIVATE: photos_private_img()
PRIVATE: photos_private_getContext()
PRIVATE: whine()

OBSOLETED FUNCTIONS

OBSOLETED: photos_index()
OBSOLETED: photos_pageindex()
OBSOLETED: photos_index_href()
OBSOLETED: photos_photo_next_img()
OBSOLETED: photos_photo_prev_img()
OBSOLETED: photos_photoset_url()

Photos Flickr

    Plugin Name:    Photos Flickr
    Plugin URI:     //dannyman.toldme.com/photos-flickr/

    Author:         Danny Howard
    Author URI:     //dannyman.toldme.com/

    Description:    Photos Flickr is a development version of a plugin
    that I am writing for WordPress blog software to display a user's
    Flickr photos within their blog.

    Version:        0.7.1

So . . . what have we here?

Pretty functions are probably the most interesting -- they do the heavy lifting of printing, say, an index page ...

General functions are the ``worker ants'' which you may call directly, or are in turn used by the pretty functions to get things done. They come in two flavors of name: photos_photo_ and photos_photoset_ depending on whether they are meant to service photo pages or photoset pages.

Private functions are documented for completeness, and for my own sanity. These may be changed at any time. You are welcome to use these, but be warned that you are voiding the warranty, and might get spanked by a future version.

Don't use private functions unless you really know what you are doing.

Obsoleted functions are functions that are no longer supported. A good many are just old names for functions that have been renamed. These are sparingly documented for completeness, and to reassure you that you're not as insane as your friends claim.

Don't use obsoleted functions unless you really really know what you are doing!

PRETTY FUNCTIONS

Top-level functions that implement serious magic and generate copious HTML.

`photos_photo_index()`

Print a reasonable photo index.

Consults the context in which the page was called, and will print only photos from a photoset or tag, if appropriate. Otherwise, you get the whole photostream.

The semantics of this function changed substantially in 0.8!

 Arguments:
    $num_per_page       = number of photos to print per page
    $num_per_row        = number of photos to print between $row_sep
    $page               = what page number we are printing
    
    $img_size           = what size image to print
    $img_before         = what to print before IMG
    $img_after          = what to print after IMG

    $row_sep            = what to print between rows
    
    $photo_before       = what to print before each photo
    $photo_after        = what to print after each photo
    
    $print_title        = print title?
    $title_before       = what to print before title
    $title_after        = what to print after title
    
    $print_description  = print description?
    $description_before = what to print before description
    $description_after  = what to print after description

You'll end up with a page of photos, and each photo looks something like:

 $photo_before
  $title_before         PHOTO TITLE         $title_after
  $img_before           PHOTO IMG TAG       $img_after
  $description_before   PHOTO DESCRIPTION   $description_after
 $photo_after

For $print_description, if you pass an integer, the description will truncated after $print_description characters.

`photos_photo_pageindex()`

Prints a ``pagination'' doohickey.

 Arguments:
    $context            = number of adjoining pages to print links to
    $item_sep           = what to put between page links
    $dotdotdot          = what to put between page link sets
    $page               = what page are we on, anyway?

A call like this:

 <?php photos_photo_pageindex(1, ', ', ' . . . ', 5); ?>

Might produce something like this:

1, 2 . . . 4, 5, 6 . . . 68, 69

`photos_photoset_index()`

Print a reasonable photoset index.

 Arguments:
    $num_per_row        = number of sets to print between $row_sep
    $row_sep            = what to print between rows
    
    $print_thumb        = print thumbnail?  Unless NULL, what kind?
    $print_title        = print title?
    $print_count        = print count?
    
    $photoset_before    = what to print before photoset
    $photoset_after     = what to print after photoset
    
    $thumb_before       = what to print before thumbnail
    $thumb_after        = what to print after thumbnail
    
    $title_before       = what to print before title
    $title_after        = what to print after title
    
    $count_before       = what to print before count
    $count_after        = what to print after count

You'll end up with a page of photosets, and each photoset looks something like:

 $photoset_before
  $thumb_before PHOTOSET IMG THUMBNAIL  $thumb_after
  $title_before PHOTOSET TITLE          $title_after
  $count_before PHOTOSET COUNT          $count_after
 $photoset_after

GENERAL FUNCTIONS

`photos_init()`

 MANDATORY call once before you call other stuff:
 * Connects to Flickr, setting up phpFlickr handle ($f)
 * Connects to cache database
 * Sets up $person and $nsid for our convenience
 * Sets up $photos_base_url appropriately

TODO: If we are hooking in to WordPress' init() then this should check to see if we're actually doing any photos before it goes pinging Flickr and setting up a database connection, huh?

`photos_photo_index_href()`

Print a link to a photo index page.

`photos_photoset_index_href()`

Print a link to a photoset index page.

`photos_is_photo()`

Are we a page for one photo, or some nav index?

Returns Flickr photo ID of current photo.

Returns false if there is no photo.

`photos_is_index()`

Are we an index page? If so, what flavor?

Unless we are an photos_is_photo() will return ``index'' or ``photoset''

Returns false if we are not an index.

If we are not a photo or an index, we might be a photoset page, or a tag page ...

`photos_is_photoset()`

Returns ID of current photoset, else false.

`photos_is_tag()`

Returns value of current tag, else false.

GENERAL FUNCTIONS: photos_photo_

 TODO: photos_photo_list();
 photos_photo_description();
 photos_photo_href();
 photos_photo_title();
 photos_photo_img();
  
 photos_photo_photoset_list();
 photos_photo_tag_list();

You can pass a photo ID to any of these functions. Otherwise, they'll default to the current photo.

`photos_photo_description()`

Print photo description.

`photos_photo_href()`

Print Photos Flickr URL of photo page for $photo_id.

`photos_photo_title()`

Print photo description.

`photos_photo_url()`

Print a Flickr IMG link to photo.

`photos_photo_photosets()`

Print linked photosets for a photo.

`photos_photo_tags()`

Print a linked list of tags for a photo.

`photos_photo_photoset_list()`

Returns a PHP list of photosets associated with photo.

Returns False if no photosets. (So you could use it as a boolean check.)

`photos_photo_tag_list()`

Returns a PHP list of tags associated with photo.

Returns False if no tags. (So you could use it as a boolean check.)

`photos_photo_page_url()`

Print a link to Flickr photo page

`photos_photo_date_taken()`

Print the date photo was taken.

Accepts $date_format as second argument -- a format string for PHP's date() function. If this is not supplied, the WordPress date_format option will be checked.

See: http://www.php.net/date

Example:

 photos_photo_date_taken(NULL, 'Y-m-d, H\hi');

(The first argument is the photo ID. NULL means to default to current photo.)

Would print something like:

2007-06-25, 15h58

`photos_photo_next_img()`

Print IMG link for next photo in stream.

Accepts Flickr image size type as first argument: defaults to ``square''

`photos_photo_prev_img()`

Print IMG link for previous photo in stream.

Accepts Flickr image size type as first argument: defaults to ``square''

`photos_photo_next_href()`

Print link to Photos Flickr page for next photo in stream.

`photos_photo_prev_href()`

Print link to Photos Flickr page for previous photo in stream.

`photos_photo_next_title()`

Print title of next photo in stream.

`photos_photo_prev_title()`

Print title of previous photo in stream.

GENERAL FUNCTIONS: photos_photosets_

 photos_photoset_list();
 photos_photoset_description();
 photos_photoset_href();
 photos_photoset_title();
 photos_photoset_img();

These functions generally accept at least one argument: $photoset_id, which is the ID of a Flickr photoset.

`photos_photoset_list()`

Return a list of photosets associated with $photo_id.

Defaults to returning a list of all sets for user.

Returns False if no photosets.

 Arguments:
    $photoset_id    = Flickr ID of photoset
    $thumb_type     = Flickr image size for "thumbnail"
    $photo_id       = Flickr ID of photo