The AnswerHub Data Model

For AnswerHub versions 1.8 and 1.9.

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

TemplateLocationDescription
base.ftdthemes/thubMain decorator; contains elements that will be present on (nearly) every page.
index.ftlthemes/thubContains elements present on AnswerHub homepage in the main body (recent Activity).

QUESTIONS, ANSWERS & COMMENTS TEMPLATES

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

EDITS/REVISIONS TEMPLATES

TemplateLocationDescription
revisions.ftl/nodesContains 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

TemplateLocationDescription
login.ftl/usersContains display of different methods of logging in (using OpenID, AnswerHub login info, Social Media).
register.ftl/usersContains display and form elements for registering on the AnswerHub site.
profile.ftl/usersContains basic structure for profile page and bypass information/code for new structure.
preferences.ftl/users/profileContains form elements/checklist of user preferences.
sidebar.ftl/users/profileContains elements present in the left sidebar, including the gravatar, and preferences button, email/inbox, etc.
pref_alteregos.ftl/users/includesContains form elements/checklist for “AlterEgos;” used within the preferences.ftl, as shown above.
user_activity.ftl/users/includesTab 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/includesShows how the answer item will look within the activity stream in the user profile.
user_questions.ftl/users/includesShows the display of the question item within the activity stream in the user profile.
user_badges.ftl/users/includesTab in the other profile; contains all user-specific badges.
user_info.ftl/users/includesTab 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/includesChanges form elements from user_info.ftl (above) into editable fields / inputs.
user_karma.ftl/users/includesTab in the user profile; contains all information related to Karma usage, displayed in graph form.

NOTIFICATIONS TEMPLATES

TemplateLocationDescription
newanswer.ftl/notificationsDisplays the name of the author who answered.
newfollower.ftl/notificationsDisplays the name of the new follower.
newquestion.ftl/notificationsDisplays the name of the author to the new question.
newsite.ftl/notificationsDisplays the new site name and the username of the person who created the new site.
newsitegroup.ftl/notificationsDisplays the new site group name and the username of the person who created the new site group.
statuschanged.ftl/notificationsDisplays 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/notificationsDisplays 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:

TemplateLocationDescription
flash_messages.ftl/includesContains key messages that display success or failure due to permissions.
footer.ftl/includesContains structure for the footer.
header.ftl/includesActs as header for all pages; contains logo elements and navigation.ftl.
main-navbar.ftl/includesContains 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. 

NameTypeDescription
currentUserUserCan be null (if anonymous user); points to the currently logged-in user and allows access to his or her properties.
currentSiteSiteA 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.
currentMetaSiteSiteA 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.
isMetaSiteBooleanNon-null and true if the site you’re on is a meta site for another site in the system.
currentPrimarySiteSiteOnly present if the current site is a meta site for another site. This variable points at the site this meta site is about.
reqHttpServletRequestA 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

NameExample UsageDescription
@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

NameExample UsageDescription
@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.