Chapter 4. Developer reference

There are some extension points in eXo Knowledge, so that you can control how these components work by implementing or extending default implementations, then reconfigure these new components in the configuration.xml file.

ForumEventLifeCycle

Overview

ForumEventLifeCycle enables you to listen to the lifecycle of a forum. By implementing ForumEventLifeCycle, you can be notified of new posts and replies, categories and topics. This installation will be injected when the data flow is called to save data.

Configuration plug-in

You can find the configuration file of this component at: ext/social-integration/src/main/resources/conf/portal/configuration.xml.

For example, to add a Forum to a space of the Social application and keep new activities of Forum (such as new posts and topics) updated to the activities of space, do as follows:

<external-component-plugins>
	<target-component>org.exoplatform.forum.service.ForumService</target-component>
	<component-plugin>
		<name>ForumEventListener</name>
		<set-method>addListenerPlugin</set-method>
		<type>org.exoplatform.ks.ext.impl.ForumSpaceActivityPublisher</type>
	</component-plugin>
</external-component-plugins>

Tutorial

To use ForumEventLifeCycle class, do the following steps:

Step 1: Create a new class that extends ForumEventListener. Example: class ABCActivityPublisher

	public class ABCActivityPublisher extends ForumEventListener {
	..............
		}

Step 2: Override fuctions in this created class. In each function, you can write anythings to meet your needs:

	public class ABCActivityPublisher extends ForumEventListener {

		public void saveCategory(Category category){
		....
		}

		public void saveForum(Forum forum){
		....
		}

		public void addTopic(Topic topic, String categoryId, String forumId)){
		....
		}

		public void updateTopic(Topic topic, String categoryId, String forumId){
		....
		}

		public void addPost(Post post, String categoryId, String forumId, String topicId){
		....
		}

		public void updatePost(Post post, String categoryId, String forumId, String topicId){
		....
		}
	}

The function saveCategory is called when a category is added and/or edited.

The function saveForum is called when a forum is added and/or edited.

The function addTopic is called when a topic is added.

The function updateTopic is called when a topic is updated.

The function addPost is called when a post is added.

The function updatePost is called when a post is updated.

Step 3: Add a new configuration in configuration.xml file with the type that is the class created in the Step 1:

<external-component-plugins>
	<target-component>org.exoplatform.forum.service.ForumService</target-component>
	<component-plugin>
		<name>ForumEventListener</name>
		<set-method>addListenerPlugin</set-method>
		<type>{package}.{class name}</type>
	<!-- example
	<type>org.exoplatform.ks.ext.impl.ABCActivityPublisher</type>
	-->
	</component-plugin>
</external-component-plugins>

AnswerEventLifeCycle

Overview

AnswerEventLifeCycle installs event updates for the Answers data that is injected while saving answers, saving questions or posting comments.

Configuration plug-in

You can find the configuration file of this component at:_ext/social-integration/src/main/resources/conf/portal/configuration.xml_.

For example, to add Answers to a space of the Social application and keep new activities of Answers updated to the activities of space, do as follows:

<external-component-plugins>
	<target-component>org.exoplatform.faq.service.FAQService</target-component>
	<component-plugin>
		<name>AnswerEventListener</name>
		<set-method>addListenerPlugin</set-method>
		<type>org.exoplatform.ks.ext.impl.AnswersSpaceActivityPublisher</type>
	</component-plugin>
</external-component-plugins>

In which, AnswersSpaceActivityPublisher is the class to implement ForumEventLifeCycle.

Tutorial

To use AnswerEventLifeCycle class, do the following steps:

Step 1: Create a new class that extends AnswerEventListener. Example: ABCActivityPublisher

	public class ABCActivityPublisher extends AnswerEventListener {
	..............
	}

Step 2: Override fuctions in this created class. In each function, you can write anything to meet your needs:

	public class ABCActivityPublisher extends AnswerEventListener {

	 	public void saveQuestion(Question question, boolean isNew){
		....
		}

	 	public void saveAnswer(String questionId, Answer answer, boolean isNew){
		....
		}

		 public void saveAnswer(String questionId, Answer[] answers, boolean isNew){
		....
		}

	 	public void saveComment(String questionId, Comment comment, boolean isNew){
		....
		}
	}

The function saveQuestion is called when a question is added and/or edited.
The function saveAnswer is called when an answer is added and/or edited.
The function saveAnswer is called when answers are added and/or edited.
The function saveComment is called when a comment is added and/or edited.

Step 3: Add a new configuration in the configuration.xml file with the type that is the class created in the Step 1:

<external-component-plugins>
	<target-component>org.exoplatform.faq.service.FAQService</target-component>
	<component-plugin>
		<name>AnswerEventListener</name>
		<set-method>addListenerPlugin</set-method>
		<type>{package}.{class name}</type>
	<!-- example
	<type>org.exoplatform.ks.ext.impl.ABCActivityPublisher</type>
	-->
	</component-plugin>
</external-component-plugins>

BBCodeRenderer

BBCodeRenderer is used in the core of eXo Knowledge to render BBCodes. In which, the data input is text, containing BBCode tags. The data output will be BBCode tags which have been encrypted into HTML tags.

You can find the configuration file of this component at: extension/webapp/src/main/webapp/WEB-INF/ks-extension/ks/forum/bbcodes-configuration.xml.

For example, to register BBCodeRenderer, do as follows:

<external-component-plugins>
	<target-component>org.exoplatform.ks.rendering.MarkupRenderingService</target-component>
	<component-plugin>
	 <name>BBCodeRenderer</name>
	 <set-method>registerRenderer</set-method>
	 <type>org.exoplatform.ks.rendering.spi.RendererPlugin</type>
	 <description>BBCode renderer</description>
	 <init-params>
		 <object-param>
			<name>renderer</name>
			<description>Extended BBCodeRenderer</description>
			<object type="org.exoplatform.ks.bbcode.core.BBCodeRenderer">
				<field name="bbCodeProvider">
					<object type="org.exoplatform.ks.bbcode.core.ExtendedBBCodeProvider"/>
				</field>
			</object>
		 </object-param>
	 </init-params>
	</component-plugin>
</external-component-plugins>

Explanation: ExtendedBBCodeProvider is the class to implement BBCodeProvider

Internal API

Applications of eXo Knowledge, such as Forum, Answers and Polls, use REST services to communicate with the server. This section describes REST Services of internal APIs.

Forum application

The Forum application of eXo Knowledge uses the ForumWebservice to provide all APIs to work with Forum, such as filtering IPs, viewing RSS, and more.

Service name	Service URL	Description	Location
ForumWebservice	$portalName/ $restcontextname/ ks/forum/	To call extended services of the Forum application.	* Maven groupId: org.exoplatform.ks * ArtifactId: exo.ks.web.webservice

APIs Usage

Use the following APIs to build all the functions of the Forum application:

Name	Description	Service URL endpoint	Parameters	Expected values
getMessage	To get all new posts with the number based on the maxcount value.	$portalName/ $restcontextname/ ks/forum/getmessage/	String maxcount	integer
filterIps	To ban IPs with no access to Forum.	$portalName/ $restcontextname/ ks/forum/filter/	String str	String in the IP format.
filterIpBanForum	To ban IPs with no access to a specific Forum.	$portalName/ $restcontextname/ ks/forum/ filterIpBanforum/	String forumId String str	string in the IP format, string in the Forum format
filterTagNameForum	To do quick search for tags that returns the list of tags.	$portalName/ $restcontextname/ ks/forum/ filterTagNameForum/	String str String userAndTopicId	Tag name id of user and topic
viewrss	To process the request by the user when he/she wants to view RSS.	$portalName/ $restcontextname/ ks/forum/rss/	String resourceid	category id forum id topic id
userrss	To process the request by users when they wants to view their own collected RSS.	$portalName /$restcontextname/ ks/forum/rss/user/	String resourceid	username id

Answers application

The Answers application of eXo Knowledge uses the FAQWebservice to view RSS.

Service name	Service URL	Description	Location
FAQWebservice	$portalName/ $restcontextname/ ks/faq	To call extended services of the Answers application.	* Maven groupId: org.exoplatform.ks * ArtifactId: exo.ks.eXoApplication. faq.service

APIs Usage

Use the following APIs to build all the functions of Answers application:

Name	Description	Service URL endpoint	Parameters	Expected values
viewrss	To view RSS	$portalName/ $restcontextname/ ks/faq/rss/	String resourceid	category id, question id

Polls application

The Polls application of eXo Knowledge uses the PollWebservice to create and interact with the Polls gadget.

Service name	Service URL	Description	Location
PollWebservice	$portalName/ $restcontextname/ private/ks/poll	To call extended services of the Polls application.	* Maven groupId: org.exoplatform.ks * ArtifactId: exo.ks.eXoApplication. poll.service

APIs Usage

Use the following APIs to build all functions of the Answers application:

Name	Description	Service URL endpoint	Parameters	Expected values
viewPoll	To return data of the Polls system	$portalName/ $restcontextname/ private/ks/poll/ viewpoll/	String pollId	id of poll
votePoll	To update data for the Polls with the returned id	$portalName/ $restcontextname/ private/ks/poll /votepoll/	String pollId String indexVote	id of poll integer

FAQ Template Configuration

Configuration plug-in

Configuration plug-in is used to automatically set up a default template for the FAQ portlet. When the FAQ service starts, it will get values which are returned from the TemplatePlugin component to initialize the template for the FAQ portlet.

The template configuration plug-in is configured in the templates-configuration.xml file.

In details:

At the run time of the FAQ Service, FAQService component is called, then templates-configuration.xml file is executed. The component-plugin named addTemplatePlugin will be referred to org.exoplatform.faq.service.TemplatePlugin- to execute some objects and create default data for the Forum application.

<external-component-plugins>
  <target-component>org.exoplatform.faq.service.FAQService</target-component>
  <component-plugin>
    <name>faq.default.template</name>
    <set-method>addTemplatePlugin</set-method>
    <type>org.exoplatform.faq.service.TemplatePlugin</type>
    <init-params>
      <value-param>
        <name>viewerTemplate</name>
        <value>war:/ks-extension/ks/faq/templates/FAQViewerPortlet.gtmpl</value>
      </value-param>
    </init-params>
  </component-plugin>
</external-component-plugins>

The properties of template configuration plug-in are defined in init-params tag as follows:

    <init-params>
      <value-param>
        <name>viewerTemplate</name>
        <value>war:/ks-extension/ks/faq/templates/FAQViewerPortlet.gtmpl</value>
      </value-param>
    </init-params>

Name	Description	Value
viewerTemplate	Path of file template	war:/ks-extension/ks/faq/templates/ FAQViewerPortlet.gtmpl

Function name	Param	Return	Description
getCategoryInfo	Empty	CategoryInfo object	Get the object CategoryInfo
arrangeList	`(List< String > list)`: List of path	A new list is arranged	Arrange a list of path
render	`(String)`: The content of answers or comments	A new string is converted by function render	Render the content of answers or comments

The CategoryInfo class:

...
        private String id;
        private String path;
        private String name;
        private List<String> pathName;
        private List<QuestionInfo> questionInfos = new ArrayList<QuestionInfo>();
        private List<SubCategoryInfo> subCateInfos = new ArrayList<SubCategoryInfo>();
...

Param	Type	Description
id	`String`	The jcr node name of the category node
path	`String`	The jcr node path of the category node
name	`String`	The name of the category
pathName	`List<String>`	The path to the category includes a list of category names.
questionInfos	`List<QuestionInfo>`	The list of QuestionInfo object
subCateInfos	`List<SubCategoryInfo>`	The list of SubCategoryInfo object

The QuestionInfo class:

...
 	private String id;
        private String question;
        private String detail;
        private List<String> answers = new ArrayList<String>();
...

Param	Type	Description
id	`String`	The jcr node name of the question node
question	`String`	The content of the question
details	`String`	The question details
answers	`List<String>`	The list of the answers for the question

The SubCategoryInfo class:

The params of this class are the same as the CategoryInfo class. See here for more information.