I don’t know of any, but feel free to pop into #wordpress on irc.freenode.net – there are people there playing with code most of the time 🙂
(not me though! I know nothing !!)
Thanks for the tip, I might just do that (though most likely over the weekend when I have time to hack away at my leisure) 🙂
I second the request for some basic documentation on how the plugin architecture works. Not that any coding I’m doing right now is of sufficient quality to warrant it, but it would be nice to at least move towards that goal.
Concrete example: I did this horrible hack in which I modified some functions in template-functions-links.php and template-functions-category.php. If I ever want to upgrade that site to WP >1.2 it will be a nightmare. Could I put my definitions of these functions in a separate file somewhere so that it will “trump” the standard WP definition, without actually having to rewrite stuff down in the guts of WP?
Apologies if there is an obvious solution, I’m just a big PHP noob.
A lot of this stuff is on the Wiki. Did you need something step-by-step?
Here’s what you need to do:
Suppose you want to replace a certain bit of specific text in the main post content with a certain bit of HTML code. For example, you want to turn any text that reads “_FOO_” into HTML, <img src="bar.jpg" />.
What you need is to write a plugin that registers a filter. A filter is rendered onto text each time WordPress intends to send a specific bit of content to the browser. For example, all filter functions registered to “the_content” filter are called whenever the main body of the post is rendered to the browser.
For our example, here’s what you do… Declare a function in your plugin like so:
function mynamespace_fooToBar($content)
{
return preg_replace('|_FOO_|i', '<img src="bar.jpg" />', $content);
}
Use “mynamespace” to differentiate your functions from any other ones that might exist with the same name, since all plugin functions are declared in the global scope (all plugin functions are accessible from anywhere WordPress executes).
The preg_replace PHP function replaces all instances of “_FOO_” in the $content argument with the image tag. This value is returned by the function.
You also need to register your function with an additional function call:
add_filter('the_content', 'mynamespace_fooToBar');
This command tells WordPress to add your function to the queue of functions that is used to filter the main post content.
Here’s what happens- When WordPress is about to render your post to the browser, if looks for any functions that are registered to the ‘the_content’ filter. Since yours is, it calls your function and passes into it the text of the post body. Your function replaces all of the _FOO_s and returns the replacement content, which is then sent to the browser.
Note that if more than one filter is registered to ‘the_content’, all of the functions are executed on the content before it is sent to the browser. This allows you to stack many features onto the content display. You can set the order in which your filter is applied by specifying a third parameter to the add_filter function:
add_filter('the_content', 'mynamespace_fooToBar', 10);
The default value for this parameter is 10. Filters that specify lower numbers are executed first. If a filter has the same number as another filter, they are executed in the order that they are loaded. Currently, the order that plugins are loaded is the order in which they were activated. Hopefully, you won’t need to worry about all that, and can just specify a number and have it all work just fine.
‘the_content’ isn’t the only filter to which you can apply your functions. Virtually every template tag has a corresponding filter. Check the wiki for a listing.
That’s how a WordPress filter works.
Actions are a different matter, but work pretty much the same.
Instead of returning a value that is then passed to the next filter and so on, actions simply send their content directly to the browser.
A good example of an action is the ‘wp_head’ action. Use the ‘wp_head’ action to put stuff into the <head> section of the WordPress output. This is useful for adding, say, <meta> tags.
Here’s an example:
function mynamespace_head($unused)
{
echo '<meta rel="alternate stylesheet" ref="k3wl.css" />';
}
add_action('wp_head', 'mynamespace_head');
This will echo the meta tag into the WordPress head area on every page. Note that the parameter is literally “unused” but it is required by convention. Some actions pass the ID of the current post or comment through this parameter. Check the Wiki for details of which does what.
Need more?
Hey ringmaster, thanks a lot for the info, I’m looking through the Wiki now. Thanks a lot for the pointer, and many many thanks for the quick primer, after reading it I’ve allready got a couple of ideas on what I would need to do to make my little hack work. The ‘wp_head’ action was particularly useful, since the plugin would need to insert some css style tags into the head of the document. I’ll have to play around a bit to make it externally configurable, but I’m starting to see where I need to hook into WP to make things work. I’ll likely put a few hours into it this weekend and see if I can’t put out something usable by then. I’ve been getting a lot of use out of WP lately, would love to be able to contribute at least a silly little hack to the community in return. 🙂 I think I can figure the rest out through the Wiki so far…
Thanks ringmaster, I did read that wiki page but found it hard to think of my mod as a filter or action at the time.
I changed, among others, the function get_month_link in template-functions-links.php, which is called by get_archives, which in turn is called by putting “wp_get_archives()” in the template. Thinking about it now, I guess I could create an “action” called wp_get_archives1, which calls get_archives1, which calls my modified get_month_link function, but that seems like overkill when I really only want to modify that last function in the chain.
I was thinking about something like function overloading (a vague memory from when I was trying to learn C++ years ago). Ah, just found something:
http://de3.php.net/functions
PHP does not support function overloading, nor is it possible to undefine or redefine previously-declared functions.
I guess that settles it then. All plugins must be defined in terms of filters/actions?
eric, I believe it depends on what they do. Using ‘add_action’ or ‘add_filter’ serves to define the scope of a given function’s influence. This may not be appropriate for what you want to do, or it may solve all sorts of issues for you.
For my part, downloading and reading the code of other people’s plugins was a big help in clarifying the distinctions and possibilities.
Oh, and ringmaster, that’s a lovely explanation, and should be saved somewhere more prominent (cough, wiki, cough).
Okay, I’ve been reading through the Wiki, and I’ve gotten some ideas, but I’m still fairly clueless on some other things. Here’s more or less what I need to do to get my floaty tooltip plugin to work as I envision it:
– The plugin needs to add some scripts into the header of the main index page, and also somewhere in the body section of the page as well, which define the tooltip styles and positioning, and define the div that will contain the tooltips. I know I can use wp_head to insert the code into the header, but not sure how I’ll get the chunk of code that goes in the body section to show up (I usually stick that last chunk of code near the bottom of th epage, before the closing body tag). A dirty hack might be to write a filter that looks for some unique bit of HTML that WP always creates at the footer of the index page, and have the filter replace it with itself + extra code I need. However, I don’t know how doable that might be what with the things different templates can insert, e.g. if a template might modify the HTML at the bottom of the main index page. Right now, on my blog, I have the codes hardcoded into the Main index file.
– The plugin would also need to make it possible for me to insert some onMouseOver and onMouseOut JS actions to tags in the posts in order to have the tooltips appear and dissapear. These actions could be inserted into pretty much any tag, not just links. Ideally, I would like for it to be a button I click on in the editing interface, like the link button, that pops up a dialog asking you for what text to show in the tooltip. I’m guessing I could write a filter that goes something like _TOOLTIP:”Text To Insert”_ and have it parse the ‘Text To Insert’ bit and replace the _TOOLTIP_ bits with the onMouse events, but I’m kinda hoping to avoid making the user type in _TOOLTIP_, I’d rather it be a button they can click that will insert the onMouse code, or the filter text, into the editing window. I don’t quite see where I could hook into to insert the new button code, though. Right now, on my blog, I have it hard-coded into the quicktags.js file. I inserted a couple of new functions for parsing and inserting the onMouse code, and I had to modify a couple of the existing functions in there to get the button to show and assign it the proper functions to pop up the dialog asking for text. Also, I’d like to be able to give the user the choice to enter the background color and tooltip width at the same time, but that’s not critical. My problem is that I don’t really see where I could hook into quicktags.js or the editing interface through a plugin.
I’ll keep digging, but if anyone has any suggestions for me, I’d appreciate it a lot.
PHP does not support function overloading, nor is it possible to undefine or redefine previously-declared functions.
There is a difference between overloading and overriding. Overloading referrs to the ability to have a function with multiple definitions (usualy with different paramters or different data types) while overriding refers to being able to redefine a function. Which is what is sounds like you are doing…. but, I think this is only possible within the context of classes. IE, I inherit a base class, say cWPPosts and override the displayPost function.
But since WP isn’t classed, I don’t know how possible this really is.
TG
@pericat: guess you’re right, I’ll go try some other plugins before trying to make my own. it’s all too vague from the outside.
ringmaster: thanks again for the help! I get most of what you’re saying, I think I can hack it from here. Some of it might not be as ‘integrated’ as I’d have liked, but it’ll do for a 1.0, and since I’m learning WP hacking as I go. Wish me luck, and hopefully I’ll have something to show by this weekend.
@ringmaster: I was looking for guide to write wordpress plugin too. Thank you for detail explaination. I learned alot from your single post. 🙂
Thank you!
