User Tools

Site Tools


using_phplugins

PHPlugins

Our goal for the Core Elements framework has been to create a common foundation for the reinvention and continual improvement of all TTG products — to maximize parity and template interchangeability between web engines, to provide new layout and design features for image galleries and web pages, to create photography assets accessible to both desktop and mobile devices and web-browsers, and to place power into the hands of designers to customize TTG image galleries and pages to whatever end.

Power to the Designer

It is this last point to which I now speak. The Core Elements framework contains many new features, but one of the most exciting is PHPlugins, a massive leap forward for extensibility and customization in TTG web engines.

PHPlugins enable designers to effect changes to their TTG website globally, locally or specific to a single page, and to maintain those changes from a single, persistent location. Using PHPlugins, user customizations may be applied to pages with precise control and in a dynamic, automated fashion.

The possibilities are limited only by your ingenuity — use PHPlugins to keep up with your constantly changing social networks; site-wide navigation menus may be managed and updated from a single source; custom header, menu and footer designs may be applied dynamically to all pages in your site, and widgets may be added to specific pages.

With Great Power Comes Great Responsibility

Be forewarned, however, that PHPlugins should be filed under Advanced Features. The feature is intended for use by web-designers, and assumes prerequisite knowledge of HTML and CSS, familiarity using an FTP client and text-editor to access and manipulate files on a web-server, and some small degree of comfort working with PHP script.

If the last paragraph makes you queasy feeling, then PHPlugins are not for you. There are limits to the amount of support I can provide on these features if you do not have the necessary background to make sense of them.

That said, this documentation should provide enough sample code that users should be able to make sense of things without too much trouble.

Acknowledgements

John Bishop, of John Bishop Images, has been instrumental in the creation, implementation and testing of PHPlugins in the Core Elements framework.

The hook architecture, designed by John, represents several months of conversation about his own needs and concerns as a TTG user, and my vision for the future of the TTG product line.

I am simply ecstatic with the way things have turned out. PHPlugins equate to infinite extensibility and endless possibility, and we have John to thank for that. Do thank him.

About PHP

Enabling PHPlugins in your TTG gallery will cause your gallery page(s) to be exported as a PHP document. This has several ramifications.

PHP files require being run from a PHP-enabled web-server. This means that your image gallery cannot be viewed using Lightroom’s Preview in Browser feature, and that your exported gallery cannot be viewed from your desktop. It must be online, hosted on a web-server running PHP version 5.2.6 or greater.

The Goods

PHPlugins operate in two parts, like plugging an appliance into an electrical outlet: the male plug goes into the female receptacle, and power is had.

The PHPlugins file are distributed with all CE3 web engines, though must be enabled within Lightroom before the necessary files will appear in published galleries. When enabled, the necessary files will be exported into a /phplugins/ folder within your gallery. The /phplugins/ folder contains three items:

index.html
path.php
phplugins.php

The phplugins.php file is the “plug” through which PHP Hooks are defined. The path.php file is a utility to help us setup PHPlugins in our galleries, its use detailed below. The index.html file is a simple redirect script; anyone attempting to access the /phplugins/ folder by URL will be redirected to the root of your domain.

Getting PHP Info

If you are uncertain of your PHP version or setup, you may get your PHP info by accessing the path.php file and calling the ?phpinfo function:

http://www.yourdomain.com/phplugins/path.php?phpinfo

Enabling PHPlugins

To utilize PHPlugins, we first must prepare our gallery with a receptacle. In the Site Info control pane of any CE3 plug-in, locate the PHPlugins control group and enable the “Enable PHPlugins” check-box.

Enabling PHPlugins causes your gallery or pages to be exported with the /phplugins-sample/ folder included. After export, manually rename this folder as /phplugins/.

The gallery or pages will be created as PHP files, and will connect with the local phplugins.php file, meaning the phplugins.php file contained within the /phplugins/ folder within the exported gallery.

Multiple galleries exported with PHPlugins enabled and the server path blank, as pictured above, will each utilize their own, separate PHPlugins file.

To use PHPlugins globally to manage hooked-in content on a site-wide basis and from a single source – which is typically the intent – all galleries and pages on the site need connect to one central phplugins.php file. This requires a server path be entered into the field labeled “Server Path to PHPlugins without trailing slash”, pictured below.

To get the server path, upload published content containing a /phplugins/ folder to your web server, then ping the path.php file in your web-browser at that address. For example:

http://www.yourdomain.com/phplugins/path.php

The browser will return the full path to the /phplugins/ folder on your server. Copy and paste this path into Lightroom, as pictured below.

That’s all there is to enabling PHPlugins in your gallery. If you are otherwise finished designing your gallery, Export to a folder on your desktop and copy that folder to your web server using an FTP client.

A Real-world Scenario

So, let's say you're setting up a new site using TTG CE3 Pages and TTG CE3 Gallery, and you want to enable your site to use PHPlugins. How do you go about the enabling?

First step, setup TTG CE3 Pages to your liking. Enable PHPlugins simply be enabling the check-box, shown below, and you're ready to export and upload to your web server root via FTP.

Your Home page is now accessible at http://www.yourdomain.com and that puts your /phplugins/ folder at http://www.yourdomain.com/phplugins/.

In this scenario, we plan to use the PHPlugins assets associated with your installation of TTG CE3 Pages as our source for PHPlugins site-wide. Because the PHPlugins files are “local” to your TTG CE3 Pages installation, it is sufficient to publish your pages with the Enabled PHPlugins check-box ticked and the server path left blank, as above.

We now need to publish our image galleries, and for this example will be using TTG CE3 Gallery. The following steps should be taken for all add-on content, though, including TTG CE3 Auto Index, TTG CE3 Client Response Gallery, TTG CE3 Stage, etc. To use the PHPlugins assets now existing on your server, we need to tell our galleries and additional pages where to find them, and that requires a server path. So, let's get our server path!

In your web-browser, hit the path.php file at http://www.yourdomain.com/phplugins/path.php. This will return a server path to your /phplugins/ folder. Copy this path.

In TTG CE3 Gallery, enable PHPlugins and paste the path into the input as shown below.

Do this for every image gallery, auto index, or additional page being added to your site. These galleries and pages will now reference the PHPlugins installed with TTG CE3 Pages, allowing you to effect site-wide changes from a single file source.

The Hook Functions

With the gallery prepared as a receptacle, the phplugins.php file becomes the plug, a vehicle for the user’s customizations. And like most vehicles, it has several seats in which the user’s customizations may sit.

The phplugins.php file — hereafter referred to as the “hook file” — may contain any of several predefined functions. The functions dictate at which point in the webpage the user’s customizations will be inserted, and how those customizations should relate to any content already present at that position in the page.

The hook file is commented and contains some technical instruction and examples. The portion of the file which is user editable occurs between the commented lines // SET USER FUNCTIONS BELOW and // END USER FUNCTIONS. The file should not be modified outside of these markers.

Between these markers, the user functions should be defined. The basic format for a user function looks like this:

function __HOOK__( $style, $path ) {
echo '
	<!-- user content here -->
';
	return false;
}

A function following this format will be applied globally to all galleries or pages accessing the hook file at this location. Further into this documentation, we will cover how to modify this function for more specific application to select galleries or pages.

Let us break the function into its three components. The first defines the hook:

function __HOOK__( $style, $path ) {

In this line, __HOOK__ should be replaced with one of the defined user exits or “hooks”, explained below.

The second component is the user’s customization:

echo '
	<!-- user content here -->
';

Here, the user may author their own code, including any PHP logic and processing as well as output to be inserted into the targeted galleries or pages.

The final component is the return value:

	return false;
}

The return value is boolean, and must be either true or false. When true, the function will insert the user authored content and then continue with the content as written in the original page. This allows user content to be added to the page without overwriting existing code.

When false, the function will replace the existing code with the user authored content.

Not all hooks utilize the return value, however. Some hooks only allow content to be added, and do not replace any existing content. These hooks ignore the return value. See the hook descriptions below to identify which hooks honor or ignore the return value.

The following user exits or “hooks” may be used to replace __HOOK__ in the function above.

ttg_user_load

  • used internally by PHPlugins script; typically not for user modification
  • return value ignored
  • called immediately after this file returns
  • called before any output is produced
  • all header and response variables are accessible
  • cookie and session processing can be initialized
  • globals to be used by later hook calls can be defined

ttg_head_end

  • return value ignored
  • called just before ending head tag
  • encompasses nothing; use to insert content with the head, after all other TTG head content has processed

ttg_body_top

  • return value ignored
  • called first within the body element, before header
  • encompasses nothing; use to insert content at top of body

ttg_header_masthead

  • if return = false normal TTG masthead processing is skipped
  • called inside the header element
  • encompasses those elements comprising the masthead content

ttg_header_navigation

  • if return = false normal TTG site navigation is skipped
  • called inside the header element, inside the nav element
  • encompasses those elements comprising the main site navigation

ttg_canvas_top

  • return value ignored
  • called immediately after the header, before the block or grid content
  • encompasses nothing; use to insert content above page content

ttg_block_top

  • if return = false normal TTG block content processing is skipped
  • called immediately within the div #the-block .core, before the copy
  • encompasses the full content of the div #the-block .core, which is typically the “gallery description”

ttg_block_bottom

  • return value ignored
  • called just before closing the div #the-block .core, after the copy block
  • encompasses nothing; use to insert content following the gallery description, but within that same box

ttg_grid_top

  • if return = false normal TTG grid content processing is skipped
  • called immediately within the div #the-grid .core, before the image gallery
  • encompasses the full content of the div #the-grid .core, which is typically the “image gallery”

ttg_grid_bottom

  • return value ignored
  • called just before closing the div #the-grid .core, after the image gallery
  • encompasses nothing; use to insert content following the image gallery, but within that same box

ttg_canvas_bottom

  • return value ignored
  • called immediately after page content, before the footer
  • encompasses nothing; use to insert content beneath page content

ttg_socialnetwork

  • if return = false normal TTG social networking block process is skipped
  • called first within the #social-networking-block element
  • encompasses those elements comprising the social networking content
  • if return = false normal TTG footer process is skipped
  • called first within the footer element
  • encompasses those elements comprising the footer content

ttg_body_bottom

  • return value ignored
  • called last within the body element, after the footer and before the closing body tag
  • encompasses nothing; use to insert content at the bottom of the body

These hooks are available in all CE3 engines, with few exceptions. If there are exceptions, or if a CE3 engine includes additional hooks, these will be covered in specific plugin documentation.

And so, a complete function might be written in this way:

function ttg_header_navigation( $style, $path ) { 
echo '
	<div id="navigation" class="tab-content clearfix">
	<div class="mantle clearfix">
		<div class="core clearfix">

		<p class="p-nav menu">

		<a href="/index.php">Home</a>
		<a href="/galleries.php">Galleries</a>
		<a href="/blog/">Blog</a>
		<a href="/services.php">Services</a>
		<a href="/info.php">Info</a>
		<a href="/about.php">About</a>
		<a href="/contact.php">Contact</a>
		
		</p>

		</div>
	</div>
	</div> <!-- #navigation / single-level -->

';
return false;		// Replaces normal menu
} // END

This function invokes the ttg_header_navigation hook to replace the existing menu with a new menu using pseudo-absolute URLs, appropriate for a site-wide navigation menu.

Note the reference to ttg_header_navigation in the first line of the function, and that the return value is set to false, which causes the standard TTG menu to be replaced with the user authored menu contained within the function.

In this case, setting the return value to true would result in two menus displayed on the page: the user authored menu first, followed by the standard TTG menu pre-existing in the source code. Naturally, such a result would be undesirable, hence the return value of false being used.

Global Hook Functions

Functions written as in the example above will be applied globally, to all galleries and pages enabled to use PHPlugins and connecting to the phplugins.php file at this location.

Local Hook Functions

My use of the term “local” is admittedly loose. In this context, I use the term to describe functions which are applied only a specific type of gallery. For example, a function that would be applied to all pages created using the TTG CE3 Gallery web engine, but which would not be applied to other PHPlugins-enabled galleries connecting to this hook file.

Warning: The following examples assume the ttg_user_load() function contained in the supplied ttg_user_load.php file is not modified. All these examples rely on correct values being set in the defined globals G_STYLE and G_PATH.

For this, we would invoke the G_STYLE variable to specify the gallery type to which the function should be applied. A local hook function should be written in this way:

function ttg_header_navigation( $style, $path ) {
	if (G_STYLE == 'CE3-GALLERY') {
		echo '
	
		<!-- navigation HTML here -->
	
		';
		return false; // Replaces normal menu for CE3-GALLERY pages
	}
	return true; // Pages not CE3-GALLERY use normal menu
} // END

This basic function would only be applied to galleries created by TTG CE3 Gallery, possessing the CE3-GALLERY identifier, and would replace the default navigation menu.

Writing a local function assumes the prerequisite knowledge of a web engine’s G_STYLE identifier, which may be obtained from our list of G_STYLE identifers for CE3 engines. In this example, the identifier is CE3-GALLERY. Capitalization is important.

Also note the presence of two return values. The first, set false, instructs CE3-GALLERY identified pages to replace the standard navigation menu with the user defined menu within our function. The second, set true, instructs pages not identified as CE3-GALLERY to proceed normally, displaying the original menu from source.

Location Specific Hook Functions

Location specific hooks are applied only to a single gallery, existing in a specific folder on your web-server. The function is written identically to a local hook function, only replacing G_STYLE with G_PATH. For example, if I wanted to modify the function above so that it would only be applied to a gallery in a specific location, I could write it this way:

function ttg_header_navigation( $style, $path ) {
	if (G_PATH == 'FOLDER-NAME') {
		echo '
	
		<!-- navigation HTML here -->
	
		';
		return false; // Replaces normal menu for CE3-GALLERY pages
	}
	return true; // Pages not CE3-GALLERY use normal menu
} // END

In this example, we are specifying a value for G_PATH, which is the folder name in which our gallery is located. Folder names should be written in ALL CAPITAL LETTERS.

Stacking Hooks within a Function

An exit or “hook” may be defined only once in the phplugins.php file. This is because PHP requires that functions be unique; calling the same function more than once will crash your script and break your pages. To specify multiple hooks for various conditions, we must therefore stack hooks into a single function in this way:

function ttg_header_navigation( $style, $path ) {
	if (G_PATH == 'GALLERY-1' || G_PATH == 'GALLERY-2') {		// invoked if folder name is 'gallery-1' or 'gallery-2'
		echo '
	
		<!-- Menu for GALLERY-1 and GALLERY-2 -->
	
		';
		return false;
	}

	elseif (G_PATH == 'GALLERY-3') {		// invoked if folder name is 'gallery-3'
		echo '
	
		<!-- Menu for GALLERY-3 -->
	
		';
		return false;
	}

	else {		// invoked globally if G_PATH is not defined as above; used everywhere not meeting the above conditions
		echo '
	
		<!-- Menu for all pages or galleries NOT GALLERY 1, 2 OR 3 -->
	
		';
		return false;
	}

	return false;
} // END

In this example, we make use of the commands if, elseif and else to set rules for a number of conditional checks, and finally to establish a global function if all checks fail.

The first statement in our function utilizes the if command, and defines output for the gallery pages contained in the folders named ‘gallery-1’ and '‘gallery-2'. Note the use of the PHP “or” operator, ||, to set dual conditions for using this menu.

function ttg_header_navigation( $style, $path ) {
	if (G_PATH == 'GALLERY-1' || G_PATH == 'GALLERY-2') {		// invoked if folder name is 'gallery-1' or 'gallery-2'
		echo '
	
		<!-- Menu for GALLERY-1 and GALLERY-2 -->
	
		';
		return false;
	}

	...

Subsequent conditional statements within the same function utilize the command elseif, and check to see whether the gallery is located in the folder ‘gallery-3’:

	elseif (G_PATH == 'GALLERY-3') {		// invoked if folder name is 'gallery-3'
		echo '
	
		<!-- Menu for GALLERY-3 -->
	
		';
		return false;
	}

	...

You may use as many elseif statements as necessary to define additional conditions. Here I add another elseif check for 'gallery-4':

	elseif (G_PATH == 'GALLERY-3') {		// invoked if folder name is 'gallery-3'
		echo '
	
		<!-- Menu for GALLERY-3 -->
	
		';
		return false;
	}

	elseif (G_PATH == 'GALLERY-4') {		// invoked if folder name is 'gallery-4'
		echo '
	
		<!-- Menu for GALLERY-4 -->
	
		';
		return false;
	}

	...

And our final statement is our fallback in the event that all checks fail — i.e. our gallery or pages are not located in folders named gallery-1, gallery-2 or gallery-3. Because there is no specific condition, we use else:

	else {		// invoked globally if G_PATH is not defined as above; used everywhere not meeting the above conditions
		echo '
	
		<!-- Menu for all pages or galleries NOT GALLERY 1, 2 OR 3 -->
	
		';
		return false;
	}

	return false;
} // END

This last statement will be applied to all hook-enabled pages which do not qualify according to the previously defined conditions.

The else statement should always be the final statement in the function, and used to specify the least specific action. In our case, “least specific” is our global function. Following the terminal else statement, we end the function normally.

Accessing Constants

Several constants are predefined within CE3 pages and galleries and may be accessed from PHPlugins functions. Constants can be useful in a variety of ways when writing functions. These constants are:

PAGEIMAGE

Returns the image file name of the page image. The page image is defined during gallery setup by specifying an Image ID number in The Block settings, located in the Color Palette control pane. The page image is typically used to represent the page to social media, such as when the page is shared on Facebook or Twitter.

The PAGEIMAGE constant will return only the file name, not its location, i.e. image.jpg. You may manually call on image renditions such as thumbnails/image.jpg or photos/image.jpg when writing your function.

CURRENTPAGEURL

Returns the absolute URL for the current page, i.e. http://yourdomain.com/index.php.

CURRENTPAGELOCATION

Returns the absolute URL for the parent location/folder of the current page, i.e. http://yourdomain.com

CURRENTPAGENAME

Returns the name of the current page, i.e. index.php.

ALBUMTITLE

Returns the Album Title, as defined in the Color Palette control pane for each gallery.

Using Constants in a Function

This example function shows how to call constants within a function. You may copy-and-paste this function into your PHPlugins file and execute it to observe the returned values. The function will replace “the block” globally for all pages.

function ttg_block_top( $style, $path ) { 
	echo '

	<p><strong>PAGEIMAGE</strong>: ' . PAGEIMAGE . '</p>
	<p><img alt="The page image" class="float-left" src="thumbnails/' . PAGEIMAGE . '" /></p>
	<hr />
	
	<p><strong>CURRENTPAGEURL</strong>: ' . CURRENTPAGEURL . '</p>
	<hr />
	
	<p><strong>CURRENTPAGELOCATION</strong>: ' . CURRENTPAGELOCATION . '</p>
	<hr />
	
	<p><strong>CURRENTPAGENAME</strong>: ' . CURRENTPAGENAME . '</p>
	<hr />
	
	<p><strong>ALBUMTITLE</strong>: ' . ALBUMTITLE . '</p>
	<hr />
	
	';
} // END

Also note, this function omits the final return statement. When the return is undefined, the function's return value will default to false, and the function will replace any existing content in the hook location.

Coda

In this document, you have learned by example and explanation how to use the PHPlugins functions featured in The Turning Gate’s Core Elements 3 (CE3) series of web engines. This example barely scratches the surface of what is possible — PHP guru’s will be able to exploit the full range of functionality offered by the Apache/PHP/MySQL environment including managing HTTP headers, cookies and sessions. With PHP Hooks you can embed page segments from Google AdSense, Google Search, PayPal, blogs, social media, microformats, other network enabled resources and much much more.

We provide a number of example functions in the CE3 PHPlugins documentation, but those willing to experiment should be able to put PHPlugins to many more uses than our examples will show.

using_phplugins.txt · Last modified: 2013/06/25 06:16 by admin