marty > using cpshop hooks

Hooks are somewhat like the idea of server side includes (SSI). Hooks allow you to define locations in the page where you want a block of content to appear, by marking those locations with a <[hook:hookname]> tag, where "hookname" would be replaced with the hook's name (duh). The great thing about hooks is that you can decide when the hooks show up as well, meaning you can create content that appears, say, only on pages with mousepads, or only on pages with products from a certain store.

when to use hooks

Here are a few examples of when you might use hooks.

Problem: I want to have a special message appear on any poster product pages. Solution: Use product type hooks for all three poster product types: small poster, large poster and mini poster (product types 53, 54 and 92, respectively).

Problem: I want to put a disclaimer above a particular store's products. Solution: Use a store ID hook.

Problem: I want a piece of HTML to appear in every page of my cpshop, except for the pages under a particular alias. Solution: Create an alias hook and an all-pages hook, both with the same hook name. Put your special HTML in the all-pages hook content file, and leave the alias hook content file blank.

an example hook

It might be a little easier if we go through an example of creating a hook.

Let's say you have a special product you'd like to feature; in this example, let's assume it's this Junior Ringer T-Shirt. At the top of the product page, you'd like to place a "Product Of The Month" banner.

If this was your first hook, then you'd first add a "cphooks" subdirectory to your cpshop installation. All hook content goes in that directory.

Then you'd update your store template, adding a new hook called, appropriately enough, "banner." You'd place a <[hook:banner]> tag in your cpshop template where you'd want the banner to appear.

The next step is to create the actual hook content file, which is basically just a text file with HTML in it. Hooks can be used to target a specific alias, product type, store ID, section, or product, and the file name determines how the hook is targeted. The general file naming convention of a hook content file is:

[cpshop file].[target type].[target criteria].[hook name].txt

In this case, you'd want to create a hook for product no. 16826273. So you'd create the HTML to display your "Product Of The Month" graphic, and then save it in a file named:

cpshop.cgi.pno.16826273.banner.txt

which you'd then upload into the cphooks directory.

Finally, you'd go to cpadmin's Other Display Options section, and set the "Process Hooks?" option to "process hooks in template and code."

That's it. Now whenever that product page loaded, cpshop would see the hook content file, and display its contents where the <[hook:banner]> tag appeared in your template. On other pages, the hook wouldn't show anything -- it would just disappear.

hook target types & hierarchy

cpshop will look for hooks in the following order, using the first one it finds.

# page type filename format & example

1 specific product cpshop.cgi.pno.[productnumber].[hookname].txt
cpshop.cgi.pno.16826273.myfooter.txt

2 product type cpshop.cgi.type.[product type no].[hookname].txt
cpshop.cgi.type.114.myfooter.txt

3 all product pages cpshop.cgi.pno.all.[hookname].txt
cpshop.cgi.pno.all.myfooter.txt

4 specific section* cpshop.cgi.sno.[sectionnumber].[hookname].txt
cpshop.cgi.sno.347246.myfooter.txt

5 store ID alias cpshop.cgi.alias.[alias].[hookname].txt
cpshop.cgi.alias.mystore.myfooter.txt

6 store ID cpshop.cgi.sid.[store ID].[hookname].txt
cpshop.cgi.sid.heyisabel.myfooter.txt

7 all pages cpshop.cgi.all.[hookname].txt
cpshop.cgi.all.myfooter.txt

* pages within a section (subsections and product pages) will also qualify

troubleshooting hooks

Because hooks are such an advanced feature, it's often much harder to implement than most cpshop features. So if you're having trouble getting hooks to work, here are several things that you should double- and triple-check.

Do you have the "Process Hooks?" option in cpadmin set to "process hooks in template and code"? And if you're running multiple instances of cpshop, are you sure you have the setting turned on for the correct cpshop?
Have you checked your hook tag to make sure it's formed correctly: <[hook:myhookname]>
Are you positive the hook is in the right template? (Some people use a lot of template files, and get them mixed up.)
Have you checked to make sure your hook content files are all named correctly? The names are long and complicated, it'd be easy to slip in a typo...
Are you sure you're using the same hook name between the hook tag and the hook content file?
Are you sure the hooks were uploaded into the cphooks folder, in the right location on the right server?
Have you been doing all your testing with the cpoutput folder enabled? Output caching will cause the first pageload to be cached, rendering all further testing useless until you empty your cache. To disable Output Caching temporarily while testing hooks, rename your cpoutput directory (to "cpoutput2" for example). Then rename it back to cpoutput when you're done testing (and clear your cache, if necessary, to implement your changes).
Try hard-coding some text next to your hook during testing, like
the hook appears here: <[hook:myhook]>
or something to that effect. Then make sure that text appears on the page you're testing.