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
| 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. |
Updated about 4 years ago