How to create your own helpers 1.1

[Fuhrmann]

Fuhrmann submitted a new resource:

How to create your own helpers (version 1.0) - I'll teach you how to create your own helpers to use in templates.

Helpers provide extra functions that you can use inside the XenForo templates.

Currently there are many Helpers, following some them:

avatar -> Helper to fetch the URL of a user's avatar.
username -> Produces a <a href="members/username.123" class="username">Username</a> snippet.
usertitle -> Helper to get the user title for the specified user.
richusername -> Outputs the necessary HTML for a rich username (includes the display style markup class)....

Read more about this resource...

 

[Chris D]

Fuhrmann, that is a great guide and has helped me do something I wanted to do.

However, what if, instead of adding a new helperCallback, I wanted to overwrite an existing one?

Is that even possible?

 

[Chris D]

I've worked it out, thanks to a post from ragtek here: http://xenforo.com/community/thread...-class-and-override-protected-function.25889/

 

[Fuhrmann]

Good to know!

 

[x7iBiT]

What's the difference between helper and hook?

 

[Chris D]

Hooks are used, usually by add on creators, to inject new code or replace existing code into templates.

Helpers are usually more specific and serve a specific task. They don't necessarily return something you can see, either. For example there's a helper that can tell you if a member is in a specified user group. That just returns either true or false to use in conditionals.

Other times helpers are used to render blocks of information. I guess as a time saver. If you imagine the HTML code required to render someone's custom avatar. You need the div container, you need the URL to their current avatar, you need their profile URL etc. Well all that can be produced with a single line of code such as {xen:helper avatar, $user}.

Helpers aren't always used by add on developers either. Obviously they can be created by add on developers but they can be used by anyone. If you want to add some code visible to only your members in a certain group or display an avatar in a new location then you can do so using any of the predefined helpers.

I hope that explains it ok for you.

 

[Liam W]

Can a helper return an array that can be used in a xen:foreach tag?

 

[Chris D]

I believe you would get an array to string conversion helper but I haven't tested it.

Best thing to do is edit one of the core helpers temporarily and have it output a php array. Then use the helper in a template and verify.

It's worth noting that you could use a combination of xen:set and xen:callback tags to set the array and then use the set var to loop through the array.

 

[Liam W]

I believe you would get an array to string conversion helper but I haven't tested it.

Best thing to do is edit one of the core helpers temporarily and have it output a php array. Then use the helper in a template and verify.

It's worth noting that you could use a combination of xen:set and xen:callback tags to set the array and then use the set var to loop through the array.

Haha, as luck would have it I just opened the discussion helper and whadda you know, it returns an array!

I'll have to check the template to see how it's used, but it seems it is possible

 

[Chris D]

That's good!

 

[Fuhrmann]

Fuhrmann updated How to create your own helpers with a new update entry:

Update download file

As @AdamCapriola noticed, the examples and the resource file was different. It is updated now.

Read the rest of this update entry...

 

[DeltaHF]

Another great tutorial, thanks!

"echo" in the $helperCallbacks array is just the name of your particular custom helper, right? One thing you might want to mention - it seems this name cannot contain a capital letter. I nearly went crazy trying to figure out why my custom helper didn't work, and that was it - I had named it after the method which did its calculation, which contained a capital letter in camel case.

Should a custom helper always return a string?

 

[Fuhrmann]

Another great tutorial, thanks!

"echo" in the $helperCallbacks array is just the name of your particular custom helper, right? One thing you might want to mention - it seems this name cannot contain a capital letter. I nearly went crazy trying to figure out why my custom helper didn't work, and that was it - I had named it after the method which did its calculation, which contained a capital letter in camel case.

Should a custom helper always return a string?

Hey thanks!

And yes, 'echo' is the name of the helper.

And about always returning a string...not always. You can return true or false too. But I guess most of the times you will be returning a string.

 

[infis]

Can I call my helper with named parameters?

For example:

public static function username(array $sp_member, $username = '', $rich = false, array $attributes = array())

I want have analog of username helper with attributes. To call this from templates as:

<h3 class="username">{xen:helper sp_user, $member, '', true, 'class=StatusTooltip'}</h3>

How I can send to my helper array of parameters?

 

[HeadHodge]

@Fuhrmann,

Thanks for this great write-up. After reading it though, my first thought is hmmm.... why don't I just use the <xen:callback> tag instead? It's much simpler to do than going through the exercise of creating a helper (IMO).

Do you think callbacks can do the same thing as helpers?

 

[Chris D]

It depends exactly what you want to do, but yeah, callbacks can be useful.

Worth noting that this tutorial (as valid as it is) way pre-dates the inclusion of the callback tag in XenForo

 

[HeadHodge]

It depends exactly what you want to do, but yeah, callbacks can be useful.

Worth noting that this tutorial (as valid as it is) way pre-dates the inclusion of the callback tag in XenForo

Thanks for the reply.
Yeah that is what I suspected (that it was written before callbacks), that's why I was asking.

I guess you could use callbacks instead of Hooks too??

 

[Chris D]

Yep, you could

 

[HeadHodge]

Yep, you could

Helpers, Hooks, and everything that starts with an "H".

 

[Rob]

I coulda sworn this thread was locked earlier :S (sorry for the report)

Anyway.... @Fuhrmann could the tutorial point out that helper names must be in lower case? I spent hours yesterday cussing you whilst trying to get "myHelper" to work until I went back to the drawing board and then realised they must have to be all lower case.

Is anyone able to go more in depth on this now that callbacks would appear to be a better alternative?
How would you achieve the example in the op, but with a callback?