UI Components: Frequently Asked Questions

Version 6

    Questions and answers about the ui-components.xml file, used to configure user interface elements in the Jive SBS UI.

    What is this file used for?

    This is a simple XML-driven way to configure the UI. Using an XML file called ui-components.xml allows you to define tabs, user bar, actions available, navigation for the application and admin console.

     

    Why should I be interested in this file?

    This is the best way of hooking into the UI, especially the tabs and navigation links.  It provides you some upgrade protection, allows you to change portions of HTML without copying and modifying entire templates. In fact, UI rendering won't make sense without understanding ui-components and how they fit into how each page is rendered.

     

    What's the best current documentation about ui-components?

    The documentation (@TODO FIX) about plugins covers all the key uses of ui-components.xml. Also, see the reference in the latest documentation.

     

    If you're referencing objects, such as community in the XML file, that object has to be available in the current invoking Struts action. If you're using FreeMarker in your UI templates, the same development caveats apply: you need to have action methods available supplying objects for the FreeMarker expressions.

     

    For example, in the following snippet, your view action must have a getCommunity() method in order to execute properly:

    <item id="myitem" name="My Item">
        <url><![CDATA[myitem.jspa?communityID=${community.ID?c}</url>
     </item>
    

    How do I use the <when> clause?

    Use the <when> element to set a condition for displaying the UI. The <when> element's content is a FreeMarker expression that should evaluate to a boolean expression, which determines whether the item is displayed or not. For example, this is often useful in determining if someone has access to some functionality or view. Note that the <[CDATA[  brackets should be present to properly escape the section.


    Example:

    <tab id="jiveUserMenu4" name="userbar.menu.history.tab" accesskey="H"
         cssClass="jive-userbar-history">
         <when><![CDATA[JiveGlobals.getJiveBooleanProperty("skin.default.recentHistoryEnabled", true)]]></when>
     </tab>
    

    This element is extremely useful, but can present some issues when debugging. If you're getting an error in Jive macros displayTabs or renderActionSidebar, it's usually related to something invalid in your ui-components.xml. For example, if you see an error in renderActionSidebar while on the thread.ftl page, then you know to check the thread-actions component in ui-components.xml to look for clues. There, it's likely that one of the FreeMarker expressions is bad.

     

    Are there any other places you can use FreeMarker expressions?

    Yes, most element bodies can be evaluated with FreeMarker.  In most cases we're using FreeMarker to render the text. Only the <when> tag is considered a boolean value. The <url> result must be a valid URL.  For example:

    <tab id="blog" module="blogs" cssClass="jive-link-blog-small">
         <name><![CDATA[<@s.text name="sgroup.tab.blog" />]]></name>
         <description><![CDATA[<@s.text name="sgroup.tab.blog.desc" />]]></description>
         <when><![CDATA[jive.isModuleAvailable(blogs, socialGroup) && BlogPermHelper.getCanViewBlog(blog)]]></when>
         <url><![CDATA[<@s.url value='${JiveResourceResolver.getJiveObjectURL(socialGroup)}'/>?view=blog]]></url>
     </tab>
    

    Sometimes I see things as elements as well as attributes.  What gives?

    This allows you to sometimes define something statically or evaluated with FreeMarker.  The cssClass element, for example, can either be an attribute or an element. If it's an attribute it's considered a static value but if it's an element you can execute FreeMarker markup in

    <tab id="jiveUserMenu3" name="userbar.menu.toolbox.tab" accesskey="Y">
         <cssClass>
             <![CDATA[jive-userbar-toolbox<#if ((privateMessageCount + approvalItemCount + moderationItemCount) > 0) >new</#if>]]>
         </cssClass>
     </tab>
    

    How do I remove an item such as a link or tab from view via ui-components.xml?

    It is quite simple:

    <components>
         <component id="community-tabs">
             <hide id="documents"/>
         </component>
     </components>
    

    Can I have an example of adding a tab in a plugin?

    The plugin has a plugin.xml file with an entry like this:

    <components>
         <component id="admin-console">
             <tab id="import" module="import" cssClass="jive-link-chat-small">
                 <section id="section-import" name="Forums Importer"
                     description="Import from forums">
                     <item id="forums-import"
                         name="admin.decorator.menu.system.database.migration"
                         url="database-migration!default.jspa"
                         role="systemAdmin"
                         description="admin.decorator.menu.system.database.migration.description"/>
                 </section>
             </tab>
         </component>
     </components>