PHPlugins

My goal for the Core Elements framework is to create a common foundation for the reinvention and 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 both to 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 — gallery resources may be shared; 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.

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 file. 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 CE2 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 CE2 plug-in, locate the PHPlugins control group and enable the “Enable PHPlugins” check-box.

Enable PHPlugins

Enabling PHPlugins causes your gallery or pages to be exported with the /phplugins/ folder included. 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, 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.

PHPlugins Server Path

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 Pages CE and TTG Horizon CE, and you want to enable your site to use PHPlugins. How do you go about the enabling?

First step, setup TTG Pages CE 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.

Enable PHPlugins

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 Pages CE as our source for PHPlugins site-wide. Because the PHPlugins files are “local” to your TTG Pages CE 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 Horizon CE. The following steps should be taken for all add-on content, though, including TTG Highslide Gallery, TTG Auto Index, TTG 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, ping 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 Horizon CE, enable PHPlugins and paste the path into the input as shown below.

PHPlugins Server Path

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 Pages CE, 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_styles

  • if return = false normal TTG style processing is skipped
  • called just after meta tags and just before link elements
  • encompasses link elements calling favicon and stylesheets

ttg_head_scripts

  • if return = false normal TTG script processing is skipped
  • called just after link elements and just before script elements
  • encompasses script elements calling both external Javascript files and inline scripts

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 within the div#the-canvas element, after the header, before page 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-content, before the copy
  • encompasses the full content of div.the-block-content, which is typically the “gallery description”

ttg_block_bottom

  • return value ignored
  • called just before /div.the-block-content, after the gallery description
  • 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-content, before the image gallery
  • encompasses the full content of div.the-grid-content, which is typically the “image gallery”

ttg_grid_bottom

  • return value ignored
  • called just before /div.the-grid-content, 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 just before /div#the-canvas, after page content, before the footer
  • encompasses nothing; use to insert content beneath page content

ttg_footer

  • 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

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

function ttg_header_navigation( $style, $path ) { 
	echo '
		<div class="menu_container">
		<p class="menuitems">
		
		<a href="/">Home</a>
		<a href="/galleries.php">Gallery Index</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>
	';
	return false;		// Replaces normal menu
} // END

This function invoked the ttg_header_navigation function 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 cause there to be 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 PHP Hooks 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 Stage CE web engine, but which would not be applied to other hook-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. G_STYLE may accept only a single value. To apply a local hook function to multiple gallery types, duplicate functions should be written. A local hook function should be written in this way:

function ttg_header_navigation( $style, $path ) { 
	if (G_STYLE == 'STAGE-CE') {
		echo '
			<div class="menu_container">
			<p class="menuitems">
			
			<a href="/">Home</a>
			<a href="/galleries.php">Gallery Index</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>
		';
		return false;		// Replaces normal menu for STAGE-CE pages
	}
	return true;	// Pages not STAGE-CE use normal menu
} // END

This example uses the same menu replacement as in the previous global example, but has been modified such that it is only applied to pages created by the TTG Stage CE web engine.

Writing a local function assumes the prerequisite knowledge of a web engine’s G_STYLE identifier, which may be obtained from the web engine’s product documentation. In the case of this example, the identifier is STAGE-CE. Capitalization is important.

Also note the presence of two return values. The first, set false, instructs STAGE-CE identified pages to replace the standard TTG menu. The second, set true, instructs pages not identified as STAGE-CE to process normally.

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.

function ttg_header_navigation( $style, $path ) { 
	if (G_PATH == 'FOLDER-NAME') {
		echo '
			<div class="menu_container">
			<p class="menuitems">
			
			<a href="/">Home</a>
			<a href="/galleries.php">Gallery Index</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>
		';
		return false;		// Replaces normal menu for specified page(s)
	}
	return true;	// All pages not specified use the 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. 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') {				// invoked if folder name is 'gallery-1'
		echo '
			<div class="menu_container">
			<p class="menuitems">
			
			<!-- Menu for GALLERY-1 -->
			
			</p>
			</div>
		';
		return false;
	}
	elseif (G_PATH == 'GALLERY-2') {			// invoked if folder name is 'gallery-2'
		echo '
			<div class="menu_container">
			<p class="menuitems">
			
			<!-- Menu for GALLERY-2 -->
			
			</p>
			</div>
		';
		return false;
	}
	elseif (G_PATH == 'GALLERY-3') {			// invoked if folder name is 'gallery-3'
		echo '
			<div class="menu_container">
			<p class="menuitems">
			
			<!-- Menu for GALLERY-3 -->
			
			</p>
			</div>
		';
		return false;
	}
	else {					// invoked globally if G_PATH is not defined as above
		echo '
			<div class="menu_container">
			<p class="menuitems">
			
			<!-- Menu for all pages or galleries NOT GALLERY 1, 2 OR 3 -->
			
			</p>
			</div>
		';
	}
	return false;
}

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 page contained in the folder named ‘gallery-1’:

	if (G_PATH == 'GALLERY-1') {				// invoked if folder name is 'gallery-1'
		echo '
			<div class="menu_container">
			<p class="menuitems">
			
			<!-- Menu for GALLERY-1 -->
			
			</p>
			</div>
		';
		return false;
	}

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

	elseif (G_PATH == 'GALLERY-2') {			// invoked if folder name is 'gallery-2'
		echo '
			<div class="menu_container">
			<p class="menuitems">
			
			<!-- Menu for GALLERY-2 -->
			
			</p>
			</div>
		';
		return false;
	}
	elseif (G_PATH == 'GALLERY-3') {			// invoked if folder name is 'gallery-3'
		echo '
			<div class="menu_container">
			<p class="menuitems">
			
			<!-- Menu for GALLERY-3 -->
			
			</p>
			</div>
		';
		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
		echo '
            <div class="menu_container">
            <p class="menuitems">Not GALLERY-1,2 OR 3</p>
            </div>
		';
	}

This last statement will be applied to all hook-enabled pages which do not qualify according to the three 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.

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 2 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.

Print/export