Take the 2-minute tour ×
WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. It's 100% free, no registration required.

I'm learning how to build html forms using PHP by taking an example from "simplr form registration" plugin.

I'm looking at this code:

$form .= apply_filters('simplr-reg-instructions', __('Please fill out this form to sign up for this site', 'simplr-reg'));

Can you please explain what is happning here - what the function does, why is the need for 'simplr-reg-instructions' and 'simplr-reg'?

Why can't this line simply be:

$form .= 'Please fill out this form to sign up for this site' ;

I've read the function reference but still can't figure it out.

share|improve this question

2 Answers 2

That line is using two different functions that need two separate explanations.

__()

This is a translation function. If the settings are done right, it will translate the first parameter from a list of pre-translated strings. If an installation has a file with a compiled translation for this function to use, it will use it. Of course, the plugin has to package its own translation, hence the second parameter. simplr-reg tells __() that the translation of the string 'Please fill out this form to sign up for this site' should be in the translation file associated with 'simplr-reg' (this is done earlier in the plugin by means of the load_plugin_textdomain() function).

The function then returns the translation. If there is no translation to return (e.g. the current language doesn't have a compiled translation, the string doesn't have a compiled translation for that package, etc.), the original input is returned.

So for a WordPress site in English, __( 'This', 'simplr-reg' ) is functionally the same as 'This'. To learn more about l10n (Localization), read up on it in the codex:

http://codex.wordpress.org/I18n_for_WordPress_Developers

apply_filters()

This function allows you to filter values used by the plugin as needed. This is one of the main concepts to grasp as a plugin developer. WordPress is extended through hooks, which are basically access points allowing you to time the execution of your plugin's actions and/or manipulate information/data that WordPress uses, etc.

To manipulate data such as the snippet of code you've asked about, you would use the function add_filter(). Here's a basic example of how this works:

add_filter( 'simplr-reg-instructions', 'wpse16573_my_filter' );

You'll probably recognize the first argument there. It's the same one used in add_filter above. This is the hook name. The second argument is the filter callback. It must be a valid callback to a function (read more about callbacks here). That line of code says "When the 'simplr-reg-instructions' hook is executed, run the function with the callback I provided." apply_filters() executes the hook found in its first argument, essentially meaning "execute all functions registered for this hook." apply_filters then passes all other arguments (in this case, 'Please fill out this form to sign up for this site') to the functions on that filter. So, the callback I used above should look like this:

function wpse16573_my_filter( $text ){
  $text = "<strong>$text</strong>";
  return $text;
}

There are two kinds of hooks in WordPress: filters (the kind we're using here) and actions. The main difference between the two is that filters expect you to return something and actions do not. So, for this filter, my example above adds some html around 'Please fill out this form to sign up for this site' and returns it.

Read more about actions and hooks here:

http://codex.wordpress.org/Plugin_API

share|improve this answer
    
John, thanks a lot. Great answer! But I can't seem to find even one "add_filter( 'simplr-reg-instructions',..." line in the plugin files. How can the apply_filter run than? –  Ash May 8 '11 at 7:31
1  
If there are no filters added to a hook, it just returns the original input right back. The filter isn't there for the plugin to use, it's there for you to be able to use if you need/want to so that you don't have to modify the plugin itself. –  John P Bloch May 9 '11 at 13:13
    
+1 Excellent Explanation - Reads Like the Docs Should ;-) –  Eddie B Jan 10 '13 at 4:00

You have two different functions here apply_filters and __()

apply_filters function is the WordPress way of letting you change/edit the value of variables using your own callback functions and the add_filter function. it accepts many arguments but the important ones are the first two:

$something = apply_filters( $tag, $value, $var ... );

$tag is the name of the filter hook which is used in add_filter eg:

add_filter($tag,callback_function);

$value is the actual value you will be able to change or edit.

$var is variables which your callback function can use, one or more.

__() function is used for translations:

__($message,$text_domain);

$message is the actual message to translate.

$text_domain is the text domain tag used for loading the plugin or theme translation with load_plugin_textdomain()

what it does?

It searches the localization module for the translation of $message, and passes the translation to the PHP return statement. If no translation is found for $message, it just returns $message.

So now the two functions in you case work in the same manner, the apply_filters will send any callback function associated with simplr-reg-instructions filter hook the translated value (if exists) of 'Please fill out this form to sign up for this site' using the text-domain of simplr-reg

share|improve this answer
    
Bainternet, thanks a lot! How is it that I can't find any "add_filter( 'simplr-reg-instructions', " lines in the plugin files? –  Ash May 8 '11 at 7:33
    
Its a hook left for developers who want to extend or filter the plugins functionality. –  Bainternet May 8 '11 at 7:55
    
So add_filter is not expected here? I don't understand why. Shouldn't apply_filters run all the functions associated with its hook by the add_filter functions? –  Ash May 8 '11 at 8:08
    
apply_filters is a place holder which lets you hook your own own functions using add_filter , so no add_filter is no expected unless you add own of your own –  Bainternet May 8 '11 at 9:23
    
Got it now. Thanks. –  Ash May 8 '11 at 9:49

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.