Jump to Content

Objective HTML

Photo Frame

Button API

The Photo Frame Button API is used to create your own buttons which can display their own UI and unique render effects. The effects created by buttons differ from the Effects API in that they are configurable and can have unique UI's, whereas the effects created by the Effects API are either on or off.

Overview

The Button API comes in two parts: PHP and JavaScript. Each has a class that is responsible for creating the effect. PHP is responsible for setting up file paths to the JS and CSS, and renders whatever effect you are building. The JavaScript class ensures the button appears in the toolbar with the control window. Everything is abtract and can be extended to do anything you need.

This documentation outlines the PHP class. To get more information on the JavaScript class, refer to the example and photo_frame.js for more information.

Properties

$name
The name of the button.
$description
The description of the button.
$path
The photo path.
$url
The photo url.
$jsDirectory
The name of the JavaScript directory in your add-on theme's directory. The default value is javascript.
$dirName
The name of the button directory within the JavaScript directory. The default value is buttons.
$image
The ImageEditor object. This object will be instantiated and assigned to each button.
$preview
Is this a preview of the photo, or is this saving/modifying the actual photo.

Extends

BaseClass

Methods

install()

The install() method is triggered when Photo Frame is installed. Each API has an install routine that may be used to perform custom logic.

Return

(void)

update($version)

The update() method is triggered when Photo Frame is updated. Each API has an update routine that may be used to perform custom logic.

$version
This string is the Photo Frame version
Return

(void)

uninstall()

The uninstall() method is triggered when Photo Frame is uninstalled. Each API has an uninstall routine that may be used to perform custom logic.

Return

(void)

modifyTables()

The modifyTables() method allows your buttons to modify the database schema for Photo Frame before it is installed. This is usefull to add new columns to the exp_photo_frame table, or alter the existing ones.

Return

(array)

render($manipulation = array())

The render() method is triggered when a manipulation has been created and is now attempted to be rendered.

$manipulation
This object is the manipulation data used to build complex effects
Return

(void)

postSave($savePhoto, $origPhoto = array())

The postSave() method is triggered each time the Photo Frame Fieldtype's postSave() method is triggered.

Return

(array)

prepSavedData($savedData)

The prepSavedData() allows your expansion pack to prep that data before it is saved in the DB. This is good for encoding arrays and objects into JSON before the photo is saved.

Return

(array)

startCrop()

The startCrop() method is triggered (with AJAX) each time a photo crop has started.

Return

(array)

css()

The css() method returns an array of CSS dependencies.

Return

(array)

javascript()

The javascript() method returns an array of Javascript dependencies.

Return

(array)

parseVars($row)

The parseVars() method returns an array of variables to be parsed by Photo Frame.

Return

(array)

settings($data)

The settings() method returns an array that will be passed to InterfaceBuilder that will build unique settings panels for your expansion pack.

Return

(array)


PHP Example

<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');

class RotateButton extends PhotoFrameButton {
	
	protected $name = 'Rotate';
	
	public function render($manipulation = array())
	{
		$this->image->rotate((float) $manipulation->data->degree);
	}
}

JavaScript Class

(function($) {
	
	PhotoFrame.Buttons.Rotate = PhotoFrame.Button.extend({
		
		/**
		 * An array of button objects
		 */
		
		buttons: [],
		
		/**
		 * The button description 
		 */
		
		description: false,
		
		/**
		 * Name of the button
		 */
		
		name: false,
		
		/**
		 * The JSON object used for Window settings 
		 */
		
		windowSettings: {
			title: false
		},
		
		constructor: function(buttonBar) {
			var t = this;
			
			this.name                 = PhotoFrame.Lang.rotate;
			this.description          = PhotoFrame.Lang.rotate_desc;	
			this.windowSettings.title = PhotoFrame.Lang.rotate;		
			this.buttons = [{
				text: PhotoFrame.Lang.rotate,
				css: 'photo-frame-tool-window-save',
				onclick: function(e, button) {
					t.apply();
				}
			}];

			this.base(buttonBar);
		},
		
		apply: function() {	
			var t = this;
						
			this.addManipulation(true, {
				degree: this.getDegree()
			});
			
			this.buttonBar.factory.trigger('rotate', this, this.getDegree());
			
			this.render(function() {	
				t.buttonBar.factory.trigger('rotateReInitCrop', t, t.getDegree());			
			});
		},
		
		startCrop: function() {
			var m = this.getManipulation();	
			
			if(m.data && m.data.degree) {
				this.window.ui.input.val(m.data.degree);
				this.base();
			}
		},
		
		getDegree: function() {
			return parseInt(this.window.ui.input.val() == '' ? 0 : this.window.ui.input.val());	
		},
		
		reset: function() {
			this.window.ui.input.val('');	
		},
		
		toggleLayer: function(visibility, render) {			
			this.base(visibility, render);
		},
		
		enable: function() {
			this.window.ui.input.attr('disabled', false);	
		},
		
		disable: function() {
			this.window.ui.input.attr('disabled', true);	
		},
		
		buildWindow: function() {	
			this.base({ buttons: this.buttons });
			
			this.window.ui.input = $('');
			
			var t = this, html = $([
				'<div class="photo-frame-inline">',
					'<label for="photo-frame-rotate photo-frame-margin-right">'+PhotoFrame.Lang.degrees+'</label>',
				'</div>'
			].join(''));
			
			html.append(this.window.ui.input);
			
			this.window.ui.content.html(html);			
			this.window.ui.content.find('input').keypress(function(e) {
				if(e.keyCode == 13) {
					t.apply();
					e.preventDefault();
				}
			});
			
			this.bind('stopRendering', function() {
				t.buttonBar.factory.trigger('rotateInitCrop', t, t.getDegree());				
			});
		}
	});

}(jQuery));