Editing WordPress Templates Cookbook

== Overview ==

Documentation on how to set up various common features in WordPress.

== Inserting a custom content template in a page ==

* Within the top-level WordPress template (e.g. `page.php`)
<syntaxhighlight lang="php">
<?php get_template_part( 'modules-sidebar-donate-link' ); ?>
</syntaxhighlight>
* The string passed as the argument to `get_template_part()` corresponds to a WordPress template in the '''themes''' directory. So `'modules-sidebar-donate-link'` means there should be a template named `modules-sidebar-donate-link.php`.
* Template markup goes in the template file (`modules-sidebar-donate-link.php` in this case).
** Content can be retrieved within the template using `WP_Query()`.
<syntaxhighlight lang="php">
<?php $query = new WP_Query("post_parent=123&post_type='page'&orderby=order&order=ASC"); /* 123 = "landing page slideshow" page */ ?>
</syntaxhighlight>
** Then a loop would be created within the template:
<syntaxhighlight lang="php">
<?php if ($query->have_posts()) while($query->have_posts()): $query->the_post(); ?>
<div><!--// Content inserted here using markup and WP content retrieval methods. //--></div>
<?php endwhile; ?>
</syntaxhighlight>

== Sub-navigation within pages ==

When landing on a content section page, load a sub-navigation menu dynamically using pages that have that top-level content section page as their parent.

Example: http://rsrt.dbarchowsky.com/about-rsrt/

* Create the top-level page (as a WordPress "page", not a WP "post"). The page can have any sort of content.
* Create 2nd-level pages and assign the top-level page as their parent.
* Create a template for the sub-navigation menu, i.e. `page-navmenu.php`.
* Include the page navigation menu inside the loop. 
<syntaxhighlight lang="php">
get_template_part('page-navmenu');
</syntaxhighlight>
* Inside the sub-navigation menu template:
:* Get the id of the parent page: 
<syntaxhighlight lang="php" highlight="4,8">
$top_parent_id = 0;
if ($post->ancestors) {
    //  Grab the ID of top-level page from the tree
    $top_parent_id = end($post->ancestors);
}

//get the top menu parent ID. If this is a top menu page, the page will not have a parent
$parent_id = (($top_parent_id>0)?($top_parent_id):($post->ID));
</syntaxhighlight>
:* Fetch and loop through results
<syntaxhighlight lang="php">
<?php
$pagemenu = new WP_Query("post_parent={$parent_id}&post_type='page'&orderby=menu_order&order=ASC&showposts=20");
if ($pagemenu->have_posts()) while($pagemenu->have_posts()): $pagemenu->the_post(); ?>
	<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
<?php endwhile; ?>
</syntaxhighlight>
:* To test for the item representing the page that's currently loaded in the browser to treat its link differently:
<syntaxhighlight lang="php">
/* outside the loop get the current page id */
$currentPageID= ($post->post_parent==$top_parent_id)?($post->ID):($post->post_parent);

/* (start of the loop code would go here) */

	/* inside the loop, check the id of the menu item against the current page id */
	$currentMenuItemID = get_the_ID();
	if ($currentMenuItemID == $currentPageID) {
		/* treat the link to indicate that this is the current page */
	}
	else {
		/* all other links treated normally */
	}


</syntaxhighlight>

== Galleries ==

Implemented with the [http://wordpress.org/extend/plugins/nextgen-gallery/ NextGEN Gallery plugin].

=== Installation ===

* '''WP dashboard''' > '''Plugins''' > '''Add New'''
* Enter "NextGEN Gallery" in '''Search'''
* Install and make sure to click the '''Activate''' link after installation has completed.

=== Configuration ===

* '''WP dashboard''' > '''Gallery''' (only visible to Admin-level users) > '''Add Gallery/Images'''
* Enter the name of the gallery & submit.
* Upload images.
* (optional) '''WP dashboard''' > '''Gallery''' > '''Manage Gallery''' 
** Select the gallery to work on.
** (optional) Enter titles and descriptions for the images in the gallery. 
** (optional) Click '''Sort Gallery''' and drag'n'drop to arrange the display order of the images.
* '''WP dashboard''' > '''Gallery''' > '''Options'''
** '''Thumbnails''' tab 
*** Set thumbnails width & height here
*** It's necessary to re-create the thumbnails for the Gallery under '''Gallery''' > '''Manage Gallery''' after changing their dimensions.
** '''Gallery''' tab
*** Hide the "[Show as Slideshow]" link here.
* Stylesheet
** `/wordpress/wp-content/themes/[SITE_THEME]/style.css` 
** `.entry-content img` defines the border and padding for the thumbnail images.
** `/wordpress/wp-content/plugins/nextgen-gallery/css/nggallery.css` 
** `.ngg-gallery-thumbnail img` defines padding and margin around thumbnail images.
** `/wordpress/wp-content/plugins/nextgen-gallery/shutter/shutter-reloaded.css` 
** `#shName` Color of text in lightbox slideshow.

=== Displaying on a page ===

* Edit a page or post. 
* After the NextGEN Gallery plugin is installed a new button for NextGEN Galleries is added to the WYSIWYG editor buttons.
* Click that button and select the gallery from the dropdown list.

== Creating groups within a page ==

Example: Sara Varon: Books

Example: Sara Varon: Friends

* '''Advanced Custom Fields''' plugin [http://wordpress.org/extend/plugins/advanced-custom-fields/ here] and [http://www.advancedcustomfields.com/ here]
* Assign a '''custom variable''' to the sub-page. 
* Retrieve all valid custom variable values for the page grouping. 
<syntaxhighlight lang="php" highlight="6,7">
$parent_id = $post->ID;
/* with these arguments, only pages that have a "book_group" custom field value will be retrieved */
$args = array(
	'post_parent' => $parent_id,
	'post_type' => 'page',
	'meta_key' => 'book_group',
	'orderby' => 'meta_value menu_order',
	'order' => 'ASC'
);
$pagemenu = new WP_Query($args);
</syntaxhighlight>
* Access the custom variable values within "the loop" using methods supplied with the Advanced Custom Field plugin.
<syntaxhighlight lang="php">
<? the_field('book_group') ?>
</syntaxhighlight>
* The value of the custom field can be assigned to a variable (also using methods supplied by ACF plugin).
<syntaxhighlight lang="php">
<? $book_group = get_field('book_group') ?>
</syntaxhighlight>

== Displaying dates ==

* The WordPress functions `[http://codex.wordpress.org/Function_Reference/the_date the_date()]` and `[http://codex.wordpress.org/Function_Reference/the_time the_time()]` functions will insert the date into a page. 
* By default `the_date()` prints the date to the browser. Passing `TRUE` as its 4th argument will return the date value as a string instead.
<syntaxhighlight lang="php">
$my_date = the_date('F j, Y', '', '', true);
</syntaxhighlight>
* `the_date()` will not print or return the date for any posts with dates that match the date of a previous post. Use `the_time()` instead for this behavior.

== Linking a page to an external URL or another page ==

=== Page Links To plugin ===

* [http://wordpress.org/extend/plugins/page-links-to/ Page Links To plugin]
* The drawback of this is the the URL displayed in the browser's address bar will be the target URL.

=== .htaccess ===

* This doesn't seem to work. WordPress gets the original URL either way and works with that to serve up its content. If the original URL doesn't match a page or post in WP, you get an error. 

=== Creating a placeholder PHP page in a physical directory ===

* I was getting errors with this, it think because of the discrepancy between the directory levels of the various pages. Also, WordPress expects the site to be at a certain location as defined in the Dashboard settings. Pages that aren't at that location probably cause problems. 

[[Category:WordPress]]
[[Category:Web Development]]