Linking Wordpress to a Coppermine Gallery using cpmfetch V2.2

[406man]

Introduction
I've described this topic in some depth as it was my main reason for getting involved with cpmfetch and I hope readers find it useful. I updated the cpmfetch code to Version 2.2 as described elsewhere in this forum so it could be used here. Wordpress is said to be the most popular site building tool on the Internet so there ought to be interest in linking it to a Coppermine gallery and I'm sharing the revised code with other users in this forum. You don't have to follow what I've done. This is the way I went about it and you might prefer some other method. If you have a different method, do share with us here what you did. The principles should be capable of being adapted to suit other types of web site but these are not described here as I don't have experience of them.

Principles
My main principles were:
- keep the code as simple as possible
- minimise the number of times when the Wordpress configuration has to be changed
- put the cpmfetch commands in a file which can be used in both live and test environments

Wordpress has a widely-used feature known as a shortcode which allow lines of PHP code to be added to a page. A shortcode looks like this:
[wpcode id="3548"].
To add the shortcode to a page either:
i) Use the Wordpress page editor
ii) or, if you use a plugin site builder like Elementor use its editor

The PHP code is written in a "snippet" which is given the shortcode. To maintain the snippet needs a plugin. I used the WPCode Lite plugin in its free basic mode and found it both reliable and easy to use. Initially I used Code Snippets and didn't get on with it at all. It was awkward to use and crashed. WPCode allows the PHP code to be added in the snippet and associated with the shortcode. The PHP snippet code for cpmfetch to fetch a grid of pictures using my recommended method has just two lines:

require '../your-gallery/cpmfetch/cpmrun.php';
cpmrun("cpmfetchsetup3.inc.php");

The PHP snippet code for a slide show is:

require '../your-gallery/cpmfetch/cpmrun.php';
cpmrun("cpmslideshowsetup5.inc.php");

In both cases above, adjust the directory reference and setup file name to suit your web site.

cpmrun.php is an included file containing a function called cpmrun which sets up the cpmfetch environment and calls the setup file. The setup file is passed into cpmrun as an argument. It knows whether an image grid or slideshow is wanted based on the name of the setup file passed in. If you change the setup file name - apart from the suffix as previously described – it probably won't work. A screenshot of the wpcode plugin is attached.

The setup file can be used with the test programs testfetch.php or testslideshow.php to check that the cpmfetch commands are working as expected. A huge advantage of this method is that the setup file can be tested with the test program and then used in the Wordpress snippet without any changes. Use of test programs and Include files is described in a separate article.

Using WPCode
When using WPCode to create a snippet it will automatically create the shortcode. This means the code snippet should created before the web page is edited to add the shortcode. Use the drop down button on the right side of the page to tell WPCode that you are entering a PHP Snippet. Paste in the PHP code, then press the Update button. Be sure to activate the shortcode using the Active slider button beside the Update button. The plugin will check the PHP syntax and warn of any problems including whether it can find the Include file in the Require statement. When the snippet has been accepted the shortcode can be copied from the lower part of the WPCode page. The web site page can then be edited to add a shortcode and the actual shortcode pasted in.

If you have difficulty at this stage one thing that can be done is to replace the code snippet with the very simple PHP code:

echo "Hello there"; 

When the web page is displayed the message "Hello there" should appear and will confirm whether the snippet and shortcode have been created correctly.

Relative Directory Reference
When implementing a code snippet for the first time, an area that could potentially cause you a problem is the directory reference in the require statement. If you get this wrong the plugin will complain when you update the snippet as it's not valid PHP code and cpmfetch can't run. On the up side, once you have it working it won't need changing unless you move your Wordpress code – which most people won't do. The structure is what is known as a relative directory reference so it has to consider the starting point and end point. In both my live and development environments the directory structure looks like this:

Wordpress is in directory /www/wp/  and the URL to access it is: https://www.mydomain.com/wp/index.php
The gallery is in directory /www/gallery/ and the URL to access it is:
https://www.mydomain.com/gallery/index.php
The cpmfetch code is in its own subdirectory so the URL for the test fetch program will be:
https://www.mydomain.com/gallery/cpmfetch/testfetch.php

www is a directory that can be seen when accessing the hosting space using a file transfer utility such as filezilla or WinSCP but doesn't appear in URLs

To figure out what the relative directory reference looks like involves comparing the two URLs. If you think of the two directory structures as a pyramid-like hierarchy and you were standing in the wp directory, to get to the cpmfetch directory you have to go up one level to the domain, then down to the gallery directory, then down again to the cpmfetch directory. So the Relative Directory Reference is:
UP ONE LEVEL   >>   DOWN ONE LEVEL TO gallery  >>   DOWN ONE LEVEL TO cpmfetch
which can be translated to :  ../  gallery /  cpmfetch  /   
Remove the spaces above to create the Require statement:   
require "../gallery/cpmfetch/cpmrun.php";
Note how the Relative Directory Reference and file name are surrounded with double quotes and a semi-colon added at the end.

If your directory structure means you need to go up two levels from Wordpress to www the Require statement will look like:
require '../../gallery/cpmfetch/cpmrun.php';

If the relative directory reference is wrong you will see an error message like the following when you try to view the page in Wordpress:

Warning: require(../gallery /cpmfetch/cpmrun.php): Failed to open stream: No such file or directory in C:\wamp64\www\wp\wp-content\plugins\insert-headers-and-footers\includes\class-wpcode-snippet-execute.php(292) : eval()'d code on line 1

Background: in wpcode the block of code in the snippet is stored in a single PHP variable. The variable is then executed as code using PHP's built-in eval function. This explains the "eval'd code" part of the error message.

Appearance
If you've followed the method I described and developed your cpmfetch code using included setup files and the testfetch or testslideshow test programs  you'll have an initial view of how the images or slideshow will look. Prepare for a possible shock when you view the same in Wordpress. It may well be the case that the CSS styling in your theme or plugin alters the image and text appearance to fit in with its own style. You may need to change the size or alignment of the images to get it all to fit.  This is where the power of the include files comes in because you only have to change the setup file and not the code in the snippet in Wordpress. Just change the include file, depending on where your environment is located, copy the include file to the hosting space if you have external hosting space, check how it looks by running the test program in the web browser, then if you are happy refresh Wordpress.

You might wish to have multiple sets of pictures from your gallery appearing in your Wordpress site. Each set needs its own shortcode and setup file

Summary
If you've followed the description above, I hope you've found that linking Wordpress with a Coppermine Gallery is straightforward. Similar principles can be used with other types of web site.