Differences

This shows you the differences between two versions of the page.

Link to this comparison view

using_phplugins [2011/11/10 21:04]
matthew [ttg_body_bottom]
using_phplugins [2011/11/10 21:53] (current)
matthew
Line 261: Line 261:
 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. 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:
 +
 +<code>
 +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
 +</code>
 +
 +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.
 +
 +<code>
 +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
 +</code>
 +
 +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:
 +
 +<code>
 +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;
 +}
 +</code>
 +
 +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’:
 +
 +<code>
 + 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;
 + }
 +</code>
 +
 +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’:
 +
 +<code>
 +
 + 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;
 + }
 +</code>
 +
 +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//:
 +
 +<code>
 +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>
 + ';
 + }
 +</code>
 +
 +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