The AnswerHub Data Model

Overview

AnswerHub themes have a great deal of data exposed to them from the backend – another feature that enables AnswerHub to be completely customizable. When building your new theme, it will be helpful to keep in mind the different macros (easily called, bundled functionality) and objects that AnswerHub exposes.

Interceptors, controllers, and context (we isolate widget contexts to the widget) all add data to the model that FreeMarker uses to render itself.

Template Tables

Template Files You Can Override

Table 1: Base; Index; Questions, Answers & Comments; Edits & Revisions
Table 2: Users’ Profiles; Notifications
Table 3: General

📘
NOTES on base theme files located in answerhub/teamhub.home/themes/thub directory:
base-head.ftl: Contains the libraries we use. We encourage you to read about the libraries seen in this ftl file. The file also contains additional head content that will be pertinent to understanding what you can work with and how to properly modify a theme.
js_var_init.ftl: Contains variables for settings, translations, and security. This file will help you understand how to work with the backend.
i18n: We use this file for reference to better understand what changes you can make in.
js_var_extend.ftl: You can find all the translations in this file. This template is accessing URLs from JavaScript. You can see maximums for options, the type of markup language used, locale, etc.
js_var_extend.ftl: This file is where you can extend the JavaScript like grabbing settings and translations and using them in other locations. For example, to make them available everywhere, on all pages.

Table 1 Base; Index; Questions, Answers & Comments; Edits and Revisions Templates

TABLE 1: Lists various form elements that help users post questions, answers, and comments. This table also lists items that determine the appearance of where the user does these changes:

BASE AND INDEX TEMPLATES

Template	Location	Description
base.ftd	themes/thub	Main decorator; contains elements that will be present on (nearly) every page.
index.ftl	themes/thub	Contains elements present on AnswerHub homepage in the main body (recent Activity).

QUESTIONS, ANSWERS & COMMENTS TEMPLATES

Template	Location	Description
list.ftl	/questions	Contains list of questions used for main Questions page.
view.ftl	/questions	Shows single question as item with voting modules, user action and time stamps, etc.
ask.ftl	/questions	Contains elements within the page that holds the ask form.
question_item.ftl	/actions	Contains specific structure for question action item used in lists (question, author, timestamps).
post.ftl	/answers	Contains form elements used for and completing answering a question.
item.ftl	/answers	Produces view of completed answer.
answer_item.ftl	/answers	Contains specific structure for answer action item used in lists (answer, author, timestamp).
comment_item.ftl	/actions	Contains the specific structure for comment action item used in lists (comment, author, timestamp).
comment_add.ftl	/actions	Contains form elements used for adding comments to questions or answers.
comment_item.ftl	/nodes	Contains the display of comments beneath questions and answers.

EDITS/REVISIONS TEMPLATES

Template	Location	Description
revisions.ftl	/nodes	Contains the display of completed revised element (question, answer, or comment).

Table 2 User's Profiles and Notifications Templates

TABLE 2 includes templates that determine what users see on their profiles and notifications.

USER'S PROFILES TEMPLATES

Template	Location	Description
login.ftl	/users	Contains display of different methods of logging in (using OpenID, AnswerHub login info, Social Media).
register.ftl	/users	Contains display and form elements for registering on the AnswerHub site.
profile.ftl	/users	Contains basic structure for profile page and bypass information/code for new structure.
preferences.ftl	/users/profile	Contains form elements/checklist of user preferences.
sidebar.ftl	/users/profile	Contains elements present in the left sidebar, including the gravatar, and preferences button, email/inbox, etc.
pref_alteregos.ftl	/users/includes	Contains form elements/checklist for “AlterEgos;” used within the preferences.ftl, as shown above.
user_activity.ftl	/users/includes	Tab in the user profile; contains all activity for that specific user. Contains activity_item.ftl which is made up of other _item.ftl’s and includes votes, comments, Questions, Answers, edits, etc.
user_answers.ftl	/users/includes	Shows how the answer item will look within the activity stream in the user profile.
user_questions.ftl	/users/includes	Shows the display of the question item within the activity stream in the user profile.
user_badges.ftl	/users/includes	Tab in the other profile; contains all user-specific badges.
user_info.ftl	/users/includes	Tab in the user profile (profile); contains form elements (that are editable) that display user information such as name, email, bio, etc.
user_info_editable.ftl	/users/includes	Changes form elements from user_info.ftl (above) into editable fields / inputs.
user_karma.ftl	/users/includes	Tab in the user profile; contains all information related to Karma usage, displayed in graph form.

NOTIFICATIONS TEMPLATES

Template	Location	Description
newanswer.ftl	/notifications	Displays the name of the author who answered.
newfollower.ftl	/notifications	Displays the name of the new follower.
newquestion.ftl	/notifications	Displays the name of the author to the new question.
newsite.ftl	/notifications	Displays the new site name and the username of the person who created the new site.
newsitegroup.ftl	/notifications	Displays the new site group name and the username of the person who created the new site group.
statuschanged.ftl	/notifications	Displays the name of the author who changed the status, the node title that had the status changed, the previous status, and the new status.
welcome.ftl	/notifications	Displays the generic welcome email with a greeting, the login information (username), and a validate your email link. The type of message wording depends on whether you are the new user or the admin. The admin gets notified a new user joined and their username.

Table 3 General Listed Templates

TABLE 3 includes General listed templates  that act as the skeleton for many of the pages on your AnswerHub site. For example, the header, footer, sidebar blocks, and error messages are all produced from the templates here:

Template	Location	Description
flash_messages.ftl	/includes	Contains key messages that display success or failure due to permissions.
footer.ftl	/includes	Contains structure for the footer.
header.ftl	/includes	Acts as header for all pages; contains logo elements and navigation.ftl.
main-navbar.ftl	/includes	Contains main navigation elements.

Objects and Macros Tables

Table 4 Objects Tables

TABLE 4 lists the AnswerHub objects available to templates. FreeMarker and SiteMesh  may expose these additional objects in the course of rendering the templates. 

Name	Type	Description
currentUser	User	Can be null (if anonymous user); points to the currently logged-in user and allows access to his or her properties.
currentSite	Site	A reference to the current site that is being used. This is generally not null, except on templates that render when someone types in an invalid site URL.
currentMetaSite	Site	A reference to the meta-discussion site (for help about the current site) for the current site. This can be null if the administrator has not set up a meta site.
isMetaSite	Boolean	Non-null and true if the site you’re on is a meta site for another site in the system.
currentPrimarySite	Site	Only present if the current site is a meta site for another site. This variable points at the site this meta site is about.
req	HttpServletRequest	A reference to the Java Servlet Request object. See HttpServletRequestJavaDocs for more information on what is available.

Table 5 Macros Tables

TABLE 5 lists AnswerHub  macros available to templates, their parameters and describes what they do. 

GENERAL PURPOSE MACROS

Name	Example Usage	Description
@diff	<@diff base=${question.revision[0].body}” new=”${question.revisions[1].body}” /> Available Parameters: base: the original content to use in the diff. new: the new content to use in the diff.	Outputs a colored (and CSS styled) diff between two pieces of content.
@trans	<@trans key=”teamhub.welcome” />  Available Parameters:  key: the i18n key to lookup from the internationalized properties.  params: parameters to pass to render into the translatable property (e.g., the {0} and {1}).	Outputs the localized string for the given key. Looks in the core i18n files, the theme’s i18n files, and any plugins that might have provided i18n files.
@url	<@url path=”/images/up-button-green.png” />  Available Parameters:  name: the name of the TeamHubUrl path to translate into a URL. When used, additional parameters to the macro get treated as variables in the URL path.  path: a static path inside your theme you want to load.  obj: generate a URL to this object (used instead of the name attribute).  abs: boolean, generate a full URL (protocol, host, context, etc.) for this URL.	Generates a URL to the request resource. Can be relative or absolute and uses lookup keys or objects to generate URLs that change even if the mapping in the backend changes.
@relate	`<@relate node=question; rel>  <#if !rel.votedUp() && rel.canVoteUp()> Show this text if I haven’t voted on the question and still can  <#if>  </@relate>` Available Parameters:  node: the node (question, answer, comment, etc.) to relate to a user.  user: the user to relate to the node (optional) uses current user if not specified.	Relates a node and a user so the theme designer can make decisions in the templates for things like whether or not a user has voted on a particular node, flagged it, or marked it as a favorite.

SPECIFIC USE CASE MACROS

Name	Example Usage	Description
@teamhub.setting	<#import “macros/teamhub.ftl” as teamhub />  <@teamhub.setting key=”example.setting” >	Allows a theme designed to output the value of a setting (in strong form) into a template.
@teamhub.avatar	<#import “macros/teamhub.ftl as teamhub />  <@teamhub.avatar user=currentUser size=32 />  Available Parameters:  user: the user object to show the avatar for  size: what size (square) for the avatar  link: do we want to link the avatar to the profile?  cssClass: what CSS class to put on the avatar image  *imgTitle: what text to put in the title attribute of the image	Displays the avatar for the given user in whatever size you want. If you have Gravatar support enabled, then it will fetch the avatar from that service. Optionally, it allows you to link to the user’s profile.
@teamhub.paginate	<#import “macros/teamhub.ftl” as teamhub />  <@teamhub.paginate pager />  Available Parameters:  *pager: the pagination object that passes to the template	Outputs a paginator wherever this macro is placed. You need to pass the variable of the paginator to the macro for this to work. That variable is usually placed into the FreeMarker context by the controller for the page.
@teamhub.webpanels	<#import “macros/qato.ftl” as qato />  <@teamhub.webpanels “system.sidebar/bottom” />  Available Parameters:  location: a location string that plugins can add content to  context: additional data to pass into the web panel for rendering	Adds a location in your theme where plugins can add additional HTML (or FreeMarker) content. This loops over all the plugins that have specified a new web panel and renders their content.
@teamhub.buildUrlToSite	<#import “macros/teamhub.ftl” as teamhub />  <@teamhub.buildUrlToSite currentSite />  Available Parameters:  *site: a Site object to generate a URL to your AnswerHub site	Rarely used but useful, this generates a link to the current sites that are running.
@security.isAuthenticated	`<#import “macros/security.ftl” as security />  <@security.isAuthenticated> Show me if I’m authenticated  </@security.isAuthenticated>`	A simple macro that renders the body of the macro if the current user is authenticated with AnswerHub.
@security.isNotAuthenticated	`<#import “macros/security.ftl” as security />  <@security.isNotAuthenticated> Show me if I’m authenticated  </@security.isNotAuthenticated>`	Though similar to the above macro, this macro renders a message that states if the user is not authenticated.
@security.access	`<#import “macros/security.ftl” as security />  <@security.access allowIf=’ROLE_FOLLOW’>  Show me if the current user has permission to follow things.  </@security.isAuthenticated>`  Available Parameters:  allowIf: a role to check the current user to display the body of the macro  permission: what permission do we check (used with the object parameters)  *object: check permissions	This macro allows you to render content inside the body if and only if the current user has the permission of role passed in the parameters.