CpmFetch walkthrough

Using CpmFetch in Your World - Quick Start

Congratulations! You've installed and configured CpmFetch on your web server and are ready to try to grabbing content from CPG.

This section will not teach you everything. In fact, I only plan on teaching you how to get a few random images from your gallery onto another PHP page in your site. However, while doing this, I will explain what it all is and how it works. After that I will turn you loose on the full range of commands and modifications. Then you can do some really cool things.

Basis for this Quick Start Guide

This tutorial is based on the following assumptions:

1. You have CPG off the root of your web site in a folder named "cpg".

2. You have uploaded the "cpmfetch" folder into your "cpg" directory.

3. You have successfully run the installer (install.php).

4. You are using a test file named index2.php in the root of your web site (to play with CpmFetch without messing up your real index.php file).

5. Your index2.php has the HTML tag structure set up inside it already (HTML, HEAD, BODY, etc.

You do not need to have everything as I have listed it above. If your CPG program is in a folder named "gallery" then you just need to be mindful of that and substitute "gallery" where appropriate.

Our First CpmFetch Code

Lets look at some code. I will refer to them by line number starting with the include line.

<?php
  include_once "./cpg/cpmfetch/cpmfetch.php";
  $objCpm = new cpm("./cpg/cpmfetch/cpmfetch_config.php");
  $options = array("subtitle" => "File name : {{pFilename}}");
  $objCpm->cpm_viewLastAddedMedia(1, 4, $options);
  $objCpm->cpm_viewRandomMediaFrom("cat=1",1, 4, $options);
  $objCpm->cpm_close(); 
?>

Don't be scared! This example is as bad as using CpmFetch can get. By working through this example you will learn enough to cover the rest on your own.

This code, when inserted into your index2.php file, will get the last four images uploaded to your site and display them in one row of four columns. The it will display four random images from category one in a second row of four images.

Every image will have a subtitle that says "This file name is " and then each particular images filename.

This example is more complicated than it needs to be, but I want to cover the most important aspects of using CpmFetch.

Before I cover what each line does, I need to explain to you what an "object" is. Don't worry if you don't understand right away. It will come to you at some point.

As Much as You Need to Know About Classes and objects...

Remember this:

Class = Blueprint of house

Object = Real house

A "class" is a part of a computer program that contains a blueprint of information and functions. An object is that blueprint put into action.

A real life example we can relate to is a house. If we are going to build a house, we have a blueprint. The blueprint shows what goes where, and how each part will connect together. It shows a living room, a dining room, a bedroom. But, you cannot do much more with a blueprint than look at it.

If you take this class or "blueprint" and build a real house, you now have an object. In this "house" object you can put things in it, you can paint it, you can even tear it down.

With a program, you can take a blueprint (or class) and make many objects which are all similar, but still different. You can build ten houses from the same blueprint, but they are not all the exact same house.

This brings us to lines 1 and 2 of our example code.

Line 1: Getting the CpmFetch Blueprint

include_once "./cpg/cpmfetch/cpmfetch.php"; // Line 1

The include_once statement tells PHP to get a specific file and make it available for use. The important part is the path and filename. Paths are important as you move around your web site.

The include statement is run from whereever your PHP file is located and has to be told how to get to your cpmfetch.php file. Since the index2.php file is at the root of your web site we need to go into the "/cpg/cpmfetch" directories to find it.

Let's break it apart:

. = means the current directory - you need this since just starting with a / means to go to the top of the file system.

./cpg = means from here, go into the directory named cpg.

./cpg/cpmfetch = means go into the directory named cpg then, cpmfetch

If you need to go up a level, it is represented by ".."

The last part gives the filename "cpmfetch.php". This contains the class blueprint for CpmFetch. This gives PHP access to anything in that file.

Now, you almost have the CpmFetch blueprint. The include_once statement told PHP that we want to use what is inside that file. Inside lurks a blueprint named "cpm". This is what we are really after.

Line 2: Getting Real - Creating the CpmFetch Object.

include_once "./cpg/cpmfetch/cpmfetch.php"; // Line 1

$objCpm = new cpm("./cpg/cpmfetch/cpmfetch_config.php"); // Line 2

In line 1, we told PHP about a file containing a new class (or blueprint) named cpm.

In line 2, we tell PHP that we want to create a new object from the blueprint named cpm.

Because its brand new, it needs to know about all sorts of things - like where the database is, how to get to it, where your pictures are... Thanks to my programming and your running of the install.php script earlier, we have all that information tucked away into our cpmfetch_config.php file!

So all we need to do is tell our new CpmFetch object where to find that file. It knows what to do from there.

Let's take line 2 step by step:

The first thing we need to do is give our new object a name. In our example, we will name it $objCpm. You could easily name it $cpmfetch, $bob, $myFineDogSpot, or anything else PHP accepts as a name.

$objCpm

Next, we use PHP's new command to create an object from the blueprint and give it to $objCpm.

$objCpm = new cpm();

We need to tell our object where to find our configuration file so we will pass it what is called a parameter; in this case a string (aka text) in quotes.

$objCpm = new cpm("./cpg/cpmfetch/cpmfetch_config.php");

Now $objCpm now knows as much as it can know about your photo gallery and is ready to display photos, give stats, and more.

Line 3: Options are Optional - But Great Fun!

$options = array("subtitle" => "File name : {{pFilename}}"); // Line 3

If you ever intend to do cool stuff with CpmFetch or PHP, pay attention. The above line creates an array. An array is just a list. But unlike a plain list of things, you can give each line its own name. A real life example would be a list of phone numbers:

$myFriends = array(
	"GauGau" => "860-555-5555" ,
	"Nibbler" => "860-555-5551",
	"VinRoc" => "860-555-5552",
	"Highlander" => "860-555-5552"
	);

This gives us a list we refer to as "myFriends" and allows us to find a number by a persons name.

We often do a lot more with something like:

$options = array(
	"subtitle" => "File name is: {{pFilename}}" ,
	"imagesize" => "int",
	"imagestyle" => "someCSSName",
	"imagewidth" => "300"
	);

By using an array, we can pass lots of information and settings into CpmFetch easily. For basic usage, we do not even need to pass in options, but it is required to adjust it to your needs.

NOTE: A common error is to just set an array like above and think CpmFetch will automagically know about it. Until you send the $options array into CpmFetch, it means nothing.

Now we will see how to actually do something with what you have learned so far - and tell CpmFetch about our $options array.

Line 4: Whats New in Your CPG... Our First Function Call

$objCpm->cpm_viewLastAddedMedia(1, 4, $options); // Line 4

Notice that this and all commands you want to give your CpmFetch object start off with:

$objCpm

When we created our object from our blueprint, this is what we named it. Unless we use this, PHP has no idea what you are talking about.

In this case, we want to use the command cpm_viewLastAddedMedia() to show us the most recently added images to our gallery.

CpmFetch has functions for almost everything. I am not going to go over them all here as they are listed in the rest of the documentation. I will however teach you how to read the documentation.

The above call is shown in the documentation like so:

cpm_viewLastAddedMedia (int $rows, int $columns, [array�$options = ""])

The $rows and $columns are where you tell it how many rows and columns of images you want. When you do that, you are telling it how many images you want total. The fact they say "int" in front means it expects an integer (a number).

If you want a total of 8 pictures shown in 4 rows of 2 each, then you want:

rows = 4, columns = 2

If you want a total of 2 pictures shown in 1 row , then you want:

rows = 1, columns = 2

If you want just 1 photo, then you want:

rows = 1, columns = 1

For other combinations of numbers, I suggest referring to any text on basic math.

Now, you may notice the [array $options=""] entry. This little wonder tells you two things:

The part that says "array" tells you it expects an array. The part after where it says ="" means that it is optional.

When you don't supply a value, CpmFetch will use whatever it lists inside the quotes. In this case, nothing. You can only omit parameters that show this.

So, when we do:

$objCpm->cpm_viewLastAddedMedia(1, 4, $options); // Line 4

It tells our CpmFetch object that we want 1 row of 4 columns and also that it should know about these other options that we have set up (in the previous step).

Line 5: When You Don't Want Everything. The CpmFetch Source parameter.

$objCpm->cpm_viewRandomMediaFrom("cat=1",1, 4, $options); // Line 5

The function call is named cpm_viewRandomMediaFrom - and with it, you tell CpmFetch to get random pictures from a specific source. All functions that end in "From" take the $source entry as the first parameter.

The source tag is one of the most powerful aspects of CpmFetch calls. It allows you to define (in simple terms) where to get images from.

In the documentation it will look like:

void cpm_viewRandomMediaFrom (mixed $source , int $rows, int $columns, [array $options = ""]);

Most of that will look familiar. The new one is $source. This is a string that you can pass in. Currently CpmFetch supports the following types to be passed in as a source: cat, album, owner, keyword, or text.

For now, we will focus on cat and album - these allow you to select specific categories and / or specific albums.

Most of the time you will be using something like:

"cat=5,6" - Use photos from categories 5 or 6

or

"cat=5,6:album=10" - Use photos from categories 5 or 6 or album 10.

Now, you can combine these however you want. The order does not matter, but you can only have one of each in your source string. You can list multiple entries by separating them with commas. Different types need to be separated by colons.

Line 6: Shutting CpmFetch Down

$objCpm->cpm_close(); // Line 6

It's always good to clean up after yourself. When you are done getting pictures, its best to call the cpm_close() function. This lets CpmFetch close its connections to the database.

Note, there is no rush to do this. In fact, if you are using CpmFetch all over your page, you can keep it open until the end of the page and close it then.

You may have problems if you are using CpmFetch inside a forum or CMS program such as SMF, Tiny Portal, Joomba, etc. These programs open a connection to the database before CpmFetch, and when you call cpm_close - it could close the forums database connection accidentally.

It is best to try it with the cpm_close and look for error messages. If your forum complains about not connecting, remove the cpm_close statement.