1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

When Will We See a Developer Documentation?

Discussion in 'General XenForo Discussion and Feedback' started by James, Mar 16, 2011.

  1. James

    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.
  2. Jake Bunce

    Jake Bunce XenForo Moderator Staff Member

  3. James

    James Well-Known Member

    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.
    Sean Kendle likes this.
  4. Jake Bunce

    Jake Bunce XenForo Moderator Staff Member

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


    An example of the syntax:

    {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:

    	 * 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):

    <xen:username user="$visitor" />
    You can see any additional parameters accepted by these functions if you look in the Core.php file. For example:

    	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

    <xen:username user="$user" class="NoOverlay" />
    EQnoble, Pereira, Adam Howard and 3 others like this.
  5. James

    James Well-Known Member

    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! :)
    Sean Kendle likes this.
  6. Brogan

    Brogan XenForo Moderator Staff Member

    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 likes this.
  7. Jake Bunce

    Jake Bunce XenForo Moderator Staff Member

    There are also template tags defined here:


    	 * Set up the defaults. Primarily sets up the handlers for various functions/tags.
    	protected function _setupDefaults()
    			'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(),
    			'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.
    EQnoble and Adam Howard like this.
  8. vbresults

    vbresults Well-Known Member

    Where are the expansive developer docs I have heard so much about? I would like to get comfortable with the API. :)
    Sean Kendle likes this.
  9. James

    James Well-Known Member

    There isn't one yet, but you can run PHPDoc on the code :)
  10. pegasus

    pegasus Well-Known Member

    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).
  11. Chris D

    Chris D XenForo Developer Staff Member

    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.
    pegasus and Jake Bunce like this.
  12. pegasus

    pegasus Well-Known Member

    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.
  13. Chris D

    Chris D XenForo Developer Staff Member

    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/
  14. pegasus

    pegasus Well-Known Member

    Thanks, the helper method does create slightly cleaner code, so I will start updating the 85 templates I've already done :confused:
    Lee likes this.
  15. rhodes

    rhodes Active Member

    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.
    pegasus, BoostN and Lemminator like this.
  16. James

    James Well-Known Member

    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 :)
  17. rhodes

    rhodes Active Member

    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?
  18. Chris D

    Chris D XenForo Developer Staff Member

    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".
  19. rhodes

    rhodes Active Member

    That's good news, @Chris D . Is there already an estimated release date for xf 2.0?
  20. Chris D

    Chris D XenForo Developer Staff Member

    Not yet.

Share This Page