When Will We See a Developer Documentation?

J

James

Well-known member
I can't wait to see a breakdown of XenForo's functions, so I was wondering when we'd see a documentation for developers.

The PHP code is easy to see a breakdown for, either by using an IDE such as Zend or running PHPDoc and making a documentation.

I'm wondering when we'll see a breakdown of things like template syntax? I could list some uses of template syntax, but I could guarantee I couldn't list them all.
 
Thanks Jake, I think I know all of the syntax there (though a great resource nonetheless). I was leaning more towards the advanced syntax.
xen:username - parameters it accepts
xen:helper - what functions can we access?

etc. etc.
 
The xen:helper functions can be seen in this file:

library/XenForo/Template/Helper/Core.php

An example of the syntax:

Code: 
{xen:helper username, $visitor}

The callbacks are defined in the file. For example, you can see the username key (used in the above example) is mapped to helperUserName which is a function in the same file so you can follow the code:

Code: 
	/**
	 * List of callbacks for the "helper" template tag. Maps the helper name (key)
	 * to a callback (value).
	 *
	 * Data received by this callback is not escaped!
	 *
	 * @var array
	 */
	public static $helperCallbacks = array(
		'avatar'        => array('self', 'helperAvatarUrl'),
		'avatarcropcss' => array('self', 'helperAvatarCropCss'),
		'username'      => array('self', 'helperUserName'),
		'usertitle'     => array('self', 'helperUserTitle'),
		'richusername'  => array('self', 'helperRichUserName'),
		'userblurb'     => array('self', 'helperUserBlurb'),
		'sortarrow'     => array('self', 'helperSortArrow'),
		'json'          => array('XenForo_ViewRenderer_Json', 'jsonEncodeForOutput'),
		'clearfix'      => array('XenForo_ViewRenderer_Css', 'helperClearfix'),
		'cssimportant'  => array('XenForo_ViewRenderer_Css', 'helperCssImportant'),
		'snippet'       => array('self', 'helperSnippet'),
		'bodytext'      => array('self', 'helperBodyText'),
		'bbcode'        => array('self', 'helperBbCode'),
		'highlight'     => array('XenForo_Helper_String', 'highlightSearchTerm'),
		'striphtml'     => array('self', 'helperStripHtml'),
		'linktitle'     => array('XenForo_Link', 'buildIntegerAndTitleUrlComponent'),
		'wrap'          => array('self', 'helperWrap'),
		'wordtrim'      => array('self', 'helperWordTrim'),
		'pagenumber'    => array('self', 'helperPageNumber'),
		'dump'          => array('self', 'helperDump'),
		'type'          => array('self', 'helperType'),
		'implode'       => array('self', 'helperImplode'),
		'rgba'			=> array('XenForo_Helper_Color', 'rgba'),
		'unrgba'        => array('XenForo_Helper_Color', 'unrgba'),
		'fullurl'       => array('XenForo_Link', 'convertUriToAbsoluteUri'),
		'ismemberof'    => array('self', 'helperIsMemberOf'),
		'twitterlang'   => array('self', 'helperTwitterLanguage'),
		'listitemid'    => array('XenForo_Template_Helper_Admin', 'getListItemId'),
	);

xen:username also calls the username helper. An example of the syntax (equivalent to previous example):

Code: 
<xen:username user="$visitor" />

You can see any additional parameters accepted by these functions if you look in the Core.php file. For example:

Code: 
	public static function helperUserName(array $user, $class = '', $rich = false)
	{
		return self::userNameHtml($user, '', $rich, array('class' => $class));
	}

You can see this function accepts a user record ($visitor in the previous examples), a class name, and a rich flag. You can see examples of this in the templates. For example:

Admin CP -> Appearance -> Templates -> member_card

Code: 
<xen:username user="$user" class="NoOverlay" />
 
Thanks Jake, that helps answer my queries. I'd assume all of the xen syntax can be found out this way.

Still, it'd be nice to know if/when this is being released as a general reference! :)
 
I know dev' doc's have/are being worked on, but like everything else, there are so many other things it's a matter of finding the time.
 
James said:
Thanks Jake, that helps answer my queries. I'd assume all of the xen syntax can be found out this way.

Still, it'd be nice to know if/when this is being released as a general reference! :)
Click to expand...

There are also template tags defined here:

library/XenForo/Template/Compiler.php

Code: 
	/**
	 * Set up the defaults. Primarily sets up the handlers for various functions/tags.
	 */
	protected function _setupDefaults()
	{
		$this->addFunctionHandlers(array(
			'raw'       => new XenForo_Template_Compiler_Function_Raw(),
			'escape'    => new XenForo_Template_Compiler_Function_Escape(),
			'urlencode' => new XenForo_Template_Compiler_Function_UrlEncode(),
			'jsescape'  => new XenForo_Template_Compiler_Function_JsEscape(),

			'phrase'    => new XenForo_Template_Compiler_Function_Phrase(),
			'property'  => new XenForo_Template_Compiler_Function_Property(),
			'pagenav'   => new XenForo_Template_Compiler_Function_PageNav(),

			'if'        => new XenForo_Template_Compiler_Function_If(),
			'checked'   => new XenForo_Template_Compiler_Function_CheckedSelected(),
			'selected'  => new XenForo_Template_Compiler_Function_CheckedSelected(),

			'date'      => new XenForo_Template_Compiler_Function_DateTime(),
			'time'      => new XenForo_Template_Compiler_Function_DateTime(),
			'datetime'  => new XenForo_Template_Compiler_Function_DateTime(),

			'number'    => new XenForo_Template_Compiler_Function_Number(),

			'link'      => new XenForo_Template_Compiler_Function_Link(),
			'adminlink' => new XenForo_Template_Compiler_Function_Link(),

			'calc'      => new XenForo_Template_Compiler_Function_Calc(),
			'array'     => new XenForo_Template_Compiler_Function_Array(),
			'count'     => new XenForo_Template_Compiler_Function_Count(),
			'helper'    => new XenForo_Template_Compiler_Function_Helper(),
			'string'    => new XenForo_Template_Compiler_Function_String(),
		));

		$this->addTagHandlers(array(
			'foreach'      => new XenForo_Template_Compiler_Tag_Foreach(),

			'if'           => new XenForo_Template_Compiler_Tag_If(),
			'elseif'       => new XenForo_Template_Compiler_Tag_If(),
			'else'         => new XenForo_Template_Compiler_Tag_If(),
			'contentcheck' => new XenForo_Template_Compiler_Tag_If(),

			'navigation'   => new XenForo_Template_Compiler_Tag_Navigation(),
			'breadcrumb'   => new XenForo_Template_Compiler_Tag_Navigation(),

			'title'        => new XenForo_Template_Compiler_Tag_Title(),
			'description'  => new XenForo_Template_Compiler_Tag_Description(),
			'h1'           => new XenForo_Template_Compiler_Tag_H1(),
			'sidebar'      => new XenForo_Template_Compiler_Tag_Sidebar(),
			'topctrl'      => new XenForo_Template_Compiler_Tag_TopCtrl(),
			'container'    => new XenForo_Template_Compiler_Tag_Container(),

			'require'      => new XenForo_Template_Compiler_Tag_Require(),
			'include'      => new XenForo_Template_Compiler_Tag_Include(),
			'edithint'     => new XenForo_Template_Compiler_Tag_EditHint(),
			'set'          => new XenForo_Template_Compiler_Tag_Set(),
			'hook'         => new XenForo_Template_Compiler_Tag_Hook(),

			'formaction'   => new XenForo_Template_Compiler_Tag_FormAction(),

			'datetime'     => new XenForo_Template_Compiler_Tag_DateTime(),
			'avatar'       => new XenForo_Template_Compiler_Tag_Avatar(),
			'username'     => new XenForo_Template_Compiler_Tag_Username(),
			'likes'        => new XenForo_Template_Compiler_Tag_Likes(),
			'follow'       => new XenForo_Template_Compiler_Tag_Follow(),
			'pagenav'      => new XenForo_Template_Compiler_Tag_PageNav(),

		// note: comment and untreated are handled by the lexer/parser
		));
	}

Again, you can follow the code at this point. Each tag is mapped to a class name.
 
Correct me if I'm wrong, but it looks like we can't add our our functionHandler or tagHandler to the compiler. Every time the template compiler is used, it's created directly using "new" instead of the wonderful loadDynamicClass. This greatly saddens me. If there is another way to add my own handlers to the compiler without making file edits, please let me know (sooner would be better).
 
It isn't currently possible. It was also suggested by devs that it might never be.

EDIT: Typically, although these tag and function handlers are much more user friendly and cleaner to work with, it is also true that most of them simply return a call to a template helper.

We can add our own template helpers and this is what I did recently while I was working on a project.

The syntax is ugly... mine had lots of parameters so it looked something like:

{xen:helper helpername, 'param1', '', 'param3', 'param4', '', '', ''}

But it works.
 
I had looked into helpers prior to your suggestion and hadn't found a hook or other way to register the helper before I needed to begin this project. Currently I am using xen:hook with a name that template_hook recognizes and passes to the appropriate callback to process the params and content as if it was its own tag. It's not as clean or efficient as having added the tag natively, but it gets the job done.
 
pegasus said:
I had looked into helpers prior to your suggestion and hadn't found a hook or other way to register the helper before I needed to begin this project. Currently I am using xen:hook with a name that template_hook recognizes and passes to the appropriate callback to process the params and content as if it was its own tag. It's not as clean or efficient as having added the tag natively, but it gets the job done.
Click to expand...
Yeah, that would definitely work.

You might find this useful: http://xenforo.com/community/resources/how-to-create-your-own-helpers.332/

Also, this add on: http://xenforo.com/community/resources/display-utc-time-helper.1040/
 
Thanks, the helper method does create slightly cleaner code, so I will start updating the 85 templates I've already done :confused:
 
  • Like
Reactions: Lee
Like @James I also would be happy about an official Xenforo developer documentation and a breakdown of XenForo's functions. Of course we have the very interesting "Have you seen" section and the "Development Tutorials and Resources" forum covering several Xenforo concepts.

But in the long run this is no alternative for a complete documentation. Because of this lack of documentation it is very difficult and time consuming for a new developer to familiarize with XenForo. I am sure there is a very long todo list for the Xenforo team. But five years after James' first posting I would like to repeat this question.
 
I'm assuming they aren't going to release a 1.x documentation when 2.0 is around the corner (or a series of corners). Perhaps we can expect a more official documentation relating to the second version, especially given the modern standards being used :)
 
James said:
I'm assuming they aren't going to release a 1.x documentation when 2.0 is around the corner (or a series of corners). Perhaps we can expect a more official documentation relating to the second version, especially given the modern standards being used :)
Click to expand...
XF 2.0 around the corner is just an assumption, @James . But even if so ten thousands of XF 1.x forums will keep on running for years. In my opinion XF is far too complex now for developers to manage efficiently without a developer documentation. So @Mike , @Chris D please allow me to ask when we will see an official developer documentation?
 
Very unlikely you will see additional documentation created for XF1.

Documentation (in a form yet to be decided) for XF2 will be created when XF2 is nearing completion or has been completed.

It's worth noting that we do acknowledge the view that documentation is somewhat lacking, but at the same time it's worth remembering that 6 years on we are seeing many development projects be completed that use the full spectrum of XF framework, and developers are generally finding their way via the generally well documented PHPDoc blocks within code. It's also worth noting that development related questions are asked and often solved quite quickly. I therefore do not agree that "XF is far too complex".
 
You must log in or register to reply here.

Similar threads

C
  • Question Question
XF 2.2 Schema Documentation?
Replies
2
Views
558
chris p
C
kirsty
XF 2.2 Passing attributes to a class widget?
Replies
1
Views
153
kirsty
kirsty
DKGE
  • Question Question
XF 2.2 Addon templates tags documentation
Replies
3
Views
1K
thetechguy
T
Foxtrek_64
Add-on Stock Replies
Replies
0
Views
91
Foxtrek_64
Foxtrek_64
elw323
Add-on Top 10 List - Member's Choice
Replies
0
Views
353
elw323
elw323
Top Bottom