WP-SNAP! WordPress Plugin
What Is WP-SNAP!?
WP-SNAP! (WordPress System for Navigating Alphabetized Posts) creates an alphabetical listing of post titles on a Category or Page template file. Navigation through the listings WP-SNAP! generates is accomplished using the alphabet itself. (For example, if a site visitor clicked on the letter D, any post titles that began with that letter would be showcased.) WP-SNAP! will work on any WordPress 2.1.x or higher site, but is particularly useful managing glossaries, indexes, reviews, or directories. Since it is said that a picture is worth a thousand words, here’s a screenshot of WP-SNAP! in action:
WP-SNAP! offers three different navigational styles and integration with both custom permalinks and the WordPress loop. Plugin options can be managed both site-wide and on the template itself with results either restricted to one category or broadened to include child categories as well. The clever web developer should have no problem seamlessly integrating WP-SNAP! into their latest project. Options have also been added to allow the customization of css class names and the appearance of html mark-up.
How To Configure WP-SNAP!
- Click on the link to the right to download the WP-SNAP! WordPress Plugin, extract it and upload it to your WordPress Plugins folder on your site.
- Activate the Plugin from the WordPress Administration Plugins tab.
- Edit the category templates your Theme uses, such as category.php, and add the following code above the start of the WordPress Loop:
<?php if (function_exists('wp_snap')) { echo wp_snap(); } ?> - Copy the CSS example below and paste it into your WordPress Theme stylesheet (you can style it better later).
- Upload the files and refresh the category page on your WordPress blog to see it in action.
- For further customization, go to WordPress Admin > Plugins > WP-SNAP! Settings. The available settings allow you to make site-wide changes to things like the alphabet, the navigational structure, permalink structure. You may also change the categories to be displayed and the menu navigational structure by passing variables as a query-string to the plugin like so:
<?php if (function_exists('wp_snap')) { echo wp_snap('arguments'); ?>There are currently four possible arguments: Category (‘cat’), Include Category Children (‘child’), Navigational Menu Style (‘menu’), and First Load (‘firstload’). Category must equal a category number from your WordPress installation, Include Category Children must equal true or false as to whether to include child categories (the default value is false), Navigational Menu Style must equal a number between 1 and 3 (corresponding with the three navigational styles offered in the admin options panel), and First Load must equal ALL, NONE or RECENT and will affect how WP-SNAP! displays posts/tags when it is first called on a template. Note that if RECENT is selected, the number of recent posts/tags to display can be controlled from the admin options page. For instance, to create a navigational menu for all posts in category 15, including child categories, using the default menu navigational style, and displaying recent posts on first load, WP-SNAP! would be called like this:
<?php if (function_exists('wp_snap')) { echo wp_snap('cat=15&child=true&firstload=recent'); } ?>To create a navigational menu for the current category, excluding child categories and using navigational menu style 3, WP-SNAP! would be called like this:
<?php if (function_exists('wp_snap')) { echo wp_snap('menu=3'); } ?>To create a navigational menu for all categories, using default navigational menu style, WP-SNAP! would be called like this:
<?php if (function_exists('wp_snap')) { echo wp_snap('cat=all'); } ?> - Test it out and enjoy!
Note: For the Plugin to work, you must have access to edit your WordPress Theme files. You must also have a category.php template file in your WordPress Theme. If you do not, you can create one following the instructions on the WordPress Codex for creating a category template file.
CSS Styling
It should be noted that this plugin does not inject any css styling information, so it is up to the user to add the appropriate class information to the WordPress Theme css stylesheet. Here is some sample code to get you started:
ol.snap_nav {
display: inline;
float: left;
clear: both;
list-style: none;
}
ol.snap_nav li {
display: block;
float: left;
padding: 0 2px 10px 0;
}
ol.snap_nav li a {
font-weight: bold
}
ol.snap_nav li.snap_selected a {
cursor: text;
}
ol.snap_titles {
clear: both;
display: block;
border: 0;
list-style: none;
}
Feedback
This plugin thrives on user feedback. Praise, ideas, and bug reports are all welcome. Use the comment form below to let me know what you think. Please keep in mind that I am not paid to work on this plugin and that delays between updates can and will occur. Please do not post questions about when the next update will be released. I appreciate your enthusiasm, but your comment will be deleted. If there is a significant delay between releases, I try to post a timeframe of when the next update can be expected.
Thank You
My thanks to Lorelle VanFossen for reviewing my plugin and allowing me to reuse her instructions on this page.
Change Log
- 08.2010.05 Version 0.9.4
- Rooted out a couple more bugs
- 08.2010.01 Version 0.9.3
- The bug hunt continues!
- 08.2010.01 Version 0.9.2
- Fixed more bugs
- 07.2010.31 Version 0.9.1
- Fixed several bugs with the database call
- 07.2010.30 Version 0.9
- Improved international character support
- Added warning if database is empty
- 02.2009.20 Version 0.8.6
- Fixed bug with posts beginning with misc. letters on sites not using fancy URLs
- Fixed bug with adminstrative menu
- 06.2008.10 Version 0.8.5
- Added international language file support
- Changed the method for passing data to the plugin
- Tracked down bugs
- 06.2008.08 Version 0.8.4
- Made the plugin compatible with WordPress’s new tagging system
- Corrected problem with listing recent posts
- 04.2008.03 Version 0.8.3
- Fixed a small — but significant — typo
- Moved the administrative submenu to plugins.php
- Added the ability to display All/None/Recent posts on first load
- 12.2007.02 Version 0.8.1
- Fixed incompatibility with PHP 4
- 11.2007.28 Version 0.8
- Added support for fancy URLs
- 10.2007.04 Version 0.7.3
- Fixed error with WordPress 2.3 database call
- 09.2007.28 Version 0.7.2
- Made database call compatible with WordPress 2.3
- 06.2007.02 Version 0.7.1
- Fixed error with database call
- 05.2007.30 Version 0.7
- Fixed issue preventing the display of more than 10 posts
- Fixed issue with sorting uppercase/lowercase post titles
- Restored ability to pass a category to the plugin
- Added ability to include category children in returned results
- Added ability to display all categories
- Added ability to change navigation style when calling the plugin
- Added support for Gengo (hopefully)
- 05.2007.12 Version 0.6.2
- Restored the ability to exclude first words from being alphabetized
- Cleaned-up some instructional text in the options menu
- 01.2007.21 Version 0.6.1
- Fixed a minor error with the $wp_snap_category variable
- 01.2007.20 Version 0.6
- Rebuilt the entire plugin to be better, stronger, faster
- Changed how results are displayed; plugin now plays well with the WordPress loop
- Removed option to pass a category number directly to the plugin, making it incompatible with Pages (feature to return if requested)
- Added nonce protection to the admin options panel
- Added option to group posts beginning with a number under ‘#’
- Fixed unencoded ampersands
- 09.2006.20 Version 0.5.4
- Updated WP-SNAP! to ignore posts with post-dated timestamps
- 08.2006.02 Version 0.5.3
- Fixed an error that affected certain navigational menu styles
- 08.2006.01 Version 0.5.2
- Updated alphabetization to accomodate accent marks; still needs refinement
- Fixed a logic error with the post title sort loop
- 06.2006.07 Version 0.5.1
- Squashed some bugs in the new ignore filter
- 06.2006.06 Version 0.5
- Words can now be filtered from the alphabetization process from the WP-SNAP! admin options menu
- 06.2006.01 Version 0.4
- Added ‘#’ to catch category entries beginning with non-alphanumeric characters
- Tweaked the code here and there
- Fixed the WP-SNAP! plugin url on the admin options page
- 05.2006.13 Version 0.3.1
- Fixed the url structure of the navigation when used on a Page
- Added ‘apply_filters’ to the post excerpt
- 05.2006.08 Version 0.3
- Plugin no longer displays excerpts for password protected posts, if the viewer is unauthorized
- If there is no excerpt for a post and excerpts are turned on, plugin now creates an excerpt from the post content
- Fixed a typo
- 03.2006.29 Version 0.2
- Added the ability to pass a category number directly to the plugin, making WP-SNAP compatible with Pages
- 03.2006.29 Version 0.1
- Initial Release
Comments
499 Responses
Leave a Reply
Frequently Asked Questions
-
When will the next version of your plugin be released?
As soon as I find the time, I will update the plugin and release a new version. I understand how frustrating it can be to be so close to having the perfect WordPress installation only to be held up by a plugin that just needs a little more work to be exactly what’s needed. However, please remember that I am not paid write this plugin and that, like you, I have a family and responsibilities that extend far beyond this little piece of code. I really appreciate your enthusiasm, but if you wish to reap the benefits of my freely given labor, then you must be satisfied with doing so on my timetable. Otherwise, if you simply cannot wait, you are more than welcome to modify and extend the capabilities of my plugin yourself.
-
Why do the results WP-SNAP! returns look funky? Why is it numbering every item?
A web page is composed of two parts: a document containing HTML code and a document containing styling code (known as a Cascading Style Sheet, or CSS for short). Because WordPress templates can look so drastically different from one another, I have intentionally avoided injecting any CSS information into WP-SNAP! However, I have included several ID selectors (that can even be modified from within wp-admin) that should allow you to style WP-SNAP! to look however you’d like. Those numbered lists? You can turn them off. I do ask that you try to refrain from asking me CSS related questions — while I would love to help you, my time is limited. If you would like to learn more about CSS, I suggest visiting A List Apart or Vitamin.
-
I tried using your plugin, but it just won’t work. What am I doing wrong?
Unfortunately, I don’t have the time to troubleshoot every installation of this plugin. However, if you believe you have discovered a bug, I encourage you to post a comment to my website and I will reply as soon as I can. I do request that you be as specific as possible when asking for assistance. Please provide a detailed account of the steps you took that resulted in the error you encountered so that I can try to reproduce it and more quickly deduce how to fix it.
Hi Nathan!
Everything works fine except group posts.
I’d like to group all my posts beginning with a number in a single page.
In the Navigational Menu Options I’ve checked “#0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ” menu style and “Group Post Titles Beginning With a Number”.
In the menu, “#ABCD…” is displayed but when I choose # it shows me all my posts, not only the ones begginning with a number.
Any idea?
I work with WP 2.8 and PHP 5.2.8
Seb — Are you sure it shows you ALL posts, or just posts beginning with numbers and miscellaneous characters? Have you tried turning off all plugins? I do not know of any bug with WP-SNAP! that would cause this.
Oh I’ve just realized I was using version 0.8.5 of WP-SNAP! Upgrading to 0.8.6 fixed the problem.
Sorry for disturbing, and thank you for answering ;)
Seb
Hi Nathan,
I installed your plugin (version 0.8.6) and it’s been working great until recently… We’ve been adding in a bunch of posts and suddenly we are getting an error when we go to this page:
http://www.depression-treatment.mobi/directory/california/
The error is:
Fatal error: Maximum execution time of 30 seconds exceeded in /hsphere/local/home/cliffsid/depression-treatment.mobi/directory/wp-content/plugins/wp-snap/wp-snap.php on line 229
Line 229 in the wp-snap.php file is the “return hmtl…” :
function accents($str) {
$str = htmlentities($str);
$str = preg_replace(‘/&([a-zA-Z])(uml|acute|grave|circ|tilde);/’,'$1′,$str);
return html_entity_decode($str);
}
I don’t know if one of our posts has a funny/special char in it that is causing the problem… it’s possible, but I don’t know which post it would be (we have 1600 posts).
Is there an easy way to find out what the problem is and which post is causing it? I don’t know that it’s a bug necessarily, but if it’s not designed to deal with certain characters, then we should avoid those characters in a post (so we’d need to know which ones to avoid).
If there is anything you can do or look at or help with I appreciate it.
Christa
Christa — The part of the plugin’s code that you quote is meant to strip out characters that cannot be sorted. My guess is that you are copying and pasting information into your WordPress blog from some sort of rich text editor. Make sure that you are sanitizing all of your text before adding it to your site. This is not a plugin issue, but an html/web server issue. Good luck.
By default, WP displays the 10 recent posts when using the following line;
php if (function_exists(‘wp_snap’)) { echo wp_snap(‘cat=3&firstload=RECENT’);
How do I change the default posts to, lets say, 20? I tried adding &showposts=20, as well as editing the “Define defaults” options in wp-snap.php but i couldn’t get it to work. Any ideas?
lightamatch — You change the number of posts by using query_posts(). Just make sure you call it after you call wp_snap().
Cool plugin, but I need to find a way to add three Norwegian characters. Out alphabet has three more letters, ÆØÅ you see. What do I have to change to get that running. I’ve tried a few things, but so far no luck…
Can you help me out?
Thanks for that great plugin. It is exactly what I was looking for. Sadly we had a problem with our german umlauts. All words beginning with an umlaut where listed under A. I checked your code and found the function accents. This function should exactly do what I expected, but it didn’t work. After a few tests i found out that the problem is the call of htmlentities(). You did not specify the charset-parameter and so the default iso-8859-1 is used. We use utf-8, which is also wordpress default. I changed line 227 of your code to htmlentities($str, ENT_COMPAT, ‘UTF-8′) and now it works perfect. For a final solution the setting of the WP character encoding should be used, but for me this quick solution is enough.
Thanks again with greetings from Austria
Peter
Thanks, Peter! It’s been a while since I looked at the international character sorting issue, but I’ll look into your suggestion and see how it works. The method I worked on involved building my own sort function — the testers I’ve given it to say it works but I just never had the time to really shake it down and make sure it was release worthy.
I’ve always gotten the sense that there are more articles on the web about sorting international characters, but that they are written in languages that actually have to deal with that issue. It’s been very frustrating trying to solve the issue as an English speaker.
Hi Peter,
Thanks for the workaround, it also solved my problem with German Umlauts :)
Greetz from Vienna, Austria,
Stephi
This plugin is fantastic! But not work with Custom Post Types. =/
Displays the following errors:
Warning: natcasesort () expects parameter 1 to Be array, null Given in my directory) (\ wp-content \ plugins \ wp-snap \ wp-snap.php on line 358
Warning: array_values () expects parameter 1 to Be array, null Given in my directory) (\ wp-content \ plugins \ wp-snap \ wp-snap.php on line 359
Warning: Invalid argument supplied for foreach () in my directory) (\ wp-content \ plugins \ wp-snap \ wp-snap.php on line 361
I’m using WordPress 3.0 + EasyPHP to test the plugin.
Any idea how to fix this?
I do not know of any bugs with the functionality of the plugin. The most likely cause of your issue is user error. Does the category you are calling have content? Are there existing posts? If there is no content, the plugin will not function. Do you have any other plugins running? Have you tried disabling ALL plugins except for WP-SNAP? If you legitimately think you’ve found a bug, please post detailed steps as to how to reproduce it or I cannot help you.
Hi, i’m using this plugin and i have one problem with it, it shows the “abc links” and they are clickable but when i click one of them it opens a blank page, it goes to URL: mysite/letter/browse-R/ for example but it is empty.
Do you know how i can fix this?
Thanks in advance
Unfortunately, you have not given me enough information to troubleshoot your problem. Please read my response to the post directly above yours. Have you tried the steps I suggested? If you believe that you’ve found a bug, you need to provide me with step-by-step instructions as how to reproduce it, otherwise I cannot help you.
I love this plugin. Exactly what I was looking for.
I have one question though.
Firstload can be set to all (shows every post in the cat), none (shows no posts) or recent (shows ordered by date). Is there a way for first load to just show the number of posts set by wordpress query (10/16/20) with the pagenation but still be in Alpha order, like “recent” but alphabetical instead of by date? When I don’t set firstload the posts for just “A” are shown. I wasn’t sure if I was missing something.
Thanks for a great plugin.
Try calling query_posts with a posts_per_page limit after calling wp_snap with a firstload of “all”. It will limit the number of posts that appear under each letter as well, but you could use an if statement with $_SERVER['REQUEST_URI'] to detect if you are on a specific letter and use that to keep wp_query from running.
I love this plug-in. However, I’m having a problem with the cat argument. There’s a conflict with another plugin (TDO Mini Forms) I use so that users can create and edit content using a form. When I don’t specify cat, so that all posts are served, the page looks fine. When I set cat to a value, multiple permalinks to the edit page show up and, most disturbing of all, the entire set of forms shows up below the footer.
http://www.sfarwa.net/category-index/
I’d appreciate suggestions. I know there’s a collision going on someplace that I’ve done simple experiments in trying to resolve with no success.
Using the multi-color theme; created category.php from the default page.php. Tried using their native archive.php with no different effect.
I need to use the cat argument as I’m using the snap index on two separate sets of posts.
Unfortunately, I don’t have the time to troubleshoot that conflict. If you’re able to determine that the problem lies with WP-SNAP, I will look into resolving it.
Hi Nathan i have this plugin running in my site.
It was working nice til i changed my hosting.
Now it show a “No post matching your criteria” message.
I tried uninstalling and installing it again.
I dont know what else to do.
You can check it at http://www.escenariorock.com/directorio/artistas
I just released a new version of the plugin today and its possible that there is a bug. But there’s no way for me to help you unless you tell me step-by-step what you’ve done to produce this result. I can’t fix a problem that I can’t reproduce. What version of WordPress are you using? Did you try turning off all other plugins? Where did you call the plugin? Is there content on your site?
I just caught a couple of bugs with the new version of the plugin. I’ve patched it and uploaded the new file. Give that one a shot.
Works like a charm again (version 0.9.1 under WP3.0.1). There are still tiny issues though.
Posts starting with ‘the’ and excluded in the ignore list don’t show at all anymore. Not under T, not under their original letter.
“Group Post Titles Beginning With a Number Under Miscellaneous” doesn’t work. All numbers are shown separately.
The style of the navigation at the top has changed. Active letter are not selectable anymore which reflects the layout. This can be changed in the CSS of course so is no major issue but still changed from previous versions.
Thanks for the feedback, Leon. Unfortunately, I was not able to duplicate an errors with the ignore list — it seems to be working fine. If you continue to experience that problem please provide me with instructions as to how to duplicate it and I will look into it further.
I was, however, able to fix the “Group Post” issue.
As to the issue about the navigation changing, that too was a bug fix. The behavior you are used to only occurred with navigational menu style #2 and #3 — menu style #1 never worked that way. Sorry for the CSS issues the fix raises.
Right, thanks for the update (still referred to as 0.9.1 on this page, you download 0.9.2)
The grouping works again. But the ignore list still doesn’t. This page doesn’t show up in this index (it did before). All entries from the exclusion list work ok, except the word ‘the’. Leaving the word ‘the’ from the exclusion list, make the posts show up under ‘T’.
Yes, I’m not doing much to keep this page up to date at the moment. This last plugin update took about three days — I’ll be happy if we can just get all the bugs worked out of the code.
So you’re saying that your ignore list works for everything except the word “the”? The ignore code was rewritten — maybe the problem is with how your ignore list is set-up? Try deleting your list, saving your settings, and then retyping in your list (items in the list should now be separated with a space instead of a pipe). If that doesn’t work, post again and I’ll email you about running some tests and figuring this out. Thanks!
I deleted the list, created a new one.
I reinstalled the plugin.
I renamed some of my posts.
Still the same result. It must be the exclusion list. I changed the title of a post to start with xx and added xx to the exclusion list and still no go. Seems like only a and an are processed…? Adding other excluded keywords to posts remove them from the index completely.
Thanks for letting me know. You are correct, there was a bug. I’ve corrected the code and released a new version. 3rd time is the charm, maybe? :)
And a charm it is :-) Thanks for the great work and support!
There is an error
Warning: preg_match() [function.preg-match]: Compilation failed: missing terminating ] for character class at offset 4 in /vrmd/homepages/u43800/blog/wp-content/plugins/wp-snap/wp-snap.php on line 395
i can not find the reason..
I have released a new version of the plugin that may address the errors you encountered. If you still are encountering problems, I need you to give me step-by-step instructions as to how I might reproduce them. Thanks.
I’m experiencing the exact same issue as Simona (I recently upgraded to v0.9.4 – I don’t recall this problem being present previously, but can’t swear to it). This error does not appear on every page, just the default glossary page that shows the alphabet (ie: the error does not appear on a page generated by clicking on a letter of the alphabet, just on the main glossary page). The error appears the same number of times as the number defined in the WP-SNAP setting “Display n recent posts”. Take a look at my glossary page, http://www.dooneyscafe.com/archives/category/dictionary, for an example.
Great plugin, and your support for it is appreciated!
Thanks,
HB
Just to follow-up here, I have heard from two people that there appears to be a problem with listing recent posts under certain circumstances. Unfortunately, I have not been able to pin-point what those circumstances are. I have not been able to reproduce the bug.
If anyone else is experiencing this problem, please post here and I will contact you via email about it. Hopefully we can get this resolved.
Thanks!
Does this plugin support pages yet? I would love to use this as an index for my review page which will have a large number of sub-pages underneath it. Anyway this plugin can support that?
Yeah, it can probably be done. I don’t really have the time to figure it out right now though. I’ll see what I can do.
Thank you so much for the consideration.
Hey Nathan,
I know you said time was limited, but this plugin is the only thing holding up a major site build I would like to complete this month. Anyway you can consider adding this functionality sometime soon?
Now that would be really awesome!
This plugin is a lifesaver! Haven’t had any problems with it at all! Thank you so much for putting it together!