UGC | Version 4

Taglibrary

Learn how to integrate Sophora's UGC add on with your apps using the Java tag library.

<dependency>
  <groupId>com.subshell.sophora</groupId>
  <artifactId>ugc-taglib</artifactId>
  <version>X.X.X</version>
</dependency>

Besides the basic features the taglib allows you to monitor the number of submissions and limit the number of submissions the taglib should accept for a given intervall. When this limit is exceeded

  1. no more submissions will be accepted
  2. an e-mail is sent notifying you about this event

Tags

getUserComments, getAllUserComments, getPinnedUserComments

These three tags all use the same parameters and structure as described in the tables below. They differ in the way they deal with pinned comments. The getUserComments tag returns only comments that are not pinned, getPinnedUserComments returns only pinned comments, and getAllUserComments returns pinned and unpinned comments mixed. There are no differences for all three tags when it comes to responses to comments, because those cannot be pinned.

Parameters
ParameterDescription
ascendingboolean parameter to specify if sorting is ascending or not. Default: false.
asJsonIf true, returns the comments as serialized JSON. Default: false.
externalIdExternal ID of the document the comments should be retrieved for
orderByThe field the comments should be sorted by. Default: "createdAt"
pageNumberThe number of the page starting with 0
pageSizeThe size of the page.
maxResponsesThe maximum number of responses to fetch for every comment. Default: Interger.MAX_VALUE (i.e. "get all responses")
scopeScope of the result variable
varThe name of the result variable. Type: SimpleUserCommentWithResponsesPageResponse
SimpleUserCommentWithResponsesPageResponse
AttributesDescription
currentPageThe current page
entriesA list of comments. Type: SimpleUserCommentWithResponses
noOfPagesThe total number of pages
noOfResultsThe number of comments on the current page
SimpleUserComment
AttributesDescription
contentContent of the comment
headlineHeadline of the comment
timestampUnix timestamp as long value
externalUserIdThe ID of the user
usernameName of the user
SimpleUserCommentWithResponses
AttributesDescription
...The same attributes as SimpleUserComment
responsesA list of the responses. Type: SimpleUserComment
totalResponseCountTotal number of responses to this comment. Note: This number may be bigger than the size of responses when maxResponses has been set.

getSingleUserComment

Parameters
ParameterDescription
commentIdThe ID of the comment
ascendingboolean parameter to specify if sorting is ascending or not. Default: false.
asJsonIf true, returns the comments as serialized JSON. Default: false.
externalIdExternal ID of the document the comments should be retrieved for
orderByThe field the comments should be sorted by. Default: "createdAt"
pageNumberThe number of the page starting with 0
pageSizeThe size of the page.
scopeScope of the result variable
varThe name of the result variable. Type: SingleSimpleUserCommentPageResponse
SingleSimpleUserCommentPageResponse
AttributesDescription
currentPageThe current page
noOfPagesThe total number of pages
noOfResultsThe number of comments on the current page
commentThe comment with the given ID. Type:
responsesA list of the responses. Type: SimpleUserComment

getCommentStatistics, getImageUploadStatistics

With these tags you can get statistics for comments or image uploads. Via the filter map, the results of noOfCreated, noOfApproved, noOfNotApproved and total can be limited to a period by setting the start and end dates.

Parameters
ParameterDescription
ascendingboolean parameter to specify if sorting is ascending or not. Default: false.
orderByThe field the results should be sorted by. Default: "total"
pageNumberThe number of the page starting with 0
pageSizeThe size of the page
filterThe filter map. Available filter keys are: serialProgram, documentType, startDate, endDate
PageResponse
AttributesDescription
noOfPagesThe total number of pages
noOfResultsThe number of documents on the current page
currentPageThe current page
entriesA list of documents. Type: SimpleDocument
SimpleDocument
AttributesDescription
externalIdExternal ID of the document
sophoraIdSophora ID of the document
noOfCreatedNumber of open comments/images on the document
noOfApprovedNumber of approved comments/images on the document
noOfNotApprovedNumber of declined comments/images on the document
totalTotal number of comments/images on the document

storeDoubleOptIn

This tag should be used on the site where the user is directed to confirm his submission.

Parameters
ParameterDescription
optInIdID of the opt-in event
scopeScope of the result variable
varThe name of the result variable

storeForm

Stores a form submission to file. Returns true, if successful.

Parameters
ParameterDescription
externalIdExternal ID of the document
formDataMap<String,Object> where the key is the name of the form field and the value is the user input for that field. If the value contains binary data it has to be a Set of FileItems.
ipAddressIP address as String
referrerReferrer value of the HTTP request
scopeScope of the result variable
userAgentUser agent value of the HTTP request
maximumSizeMaximum size of binary data in bytes. Default is 5242880.
doubleOptInParamsMap<String,String> which contains key-value mappings that are used to replace keys in the text of double-opt-in e-mails.
varName of the result variable

storeImageUpload

The form data is expected to be of the type multipart/form-data in UTF-8 encoding. This tag extracts the form data from the request directly. The parameters that are expected are:

  • externalUserId: the ID of the user. If the user is identified by his name, the field must be filled with the username.
  • username: the name of the user
  • headline: headline of the comment
  • content: text of the comment
  • imageData: the image to be uploaded (type needs to be file)
  • externalId: the external ID of the document
  • documentType: the primary type or node type of the document
  • categoryExternalId: the external ID of the document describing the category of this comment, only relevant, if categories are used.

Parameters
ParameterDescription
varSet the name of the variable that stores the result.
scopeScope of the result variable
Attributes of the result
AttributeDescription
successboolean property that signals if saving the upload to file was successful
errorEnum of Type ImageUploadError that holds the information on the type of error

storeQuiz

Stores a user submission for a quiz to file. Returns true, if successful.

Parameters
ParameterDescription
externalIdExternal ID of the document
formDataMap<String,Object> where the key is the name of the form field and the value is the user input for that field. If the value contains binary data it has to be a Set of FileItems.
ipAddressIP address as String
referrerReferrer value of the HTTP request
scopeScope of the result variable
selectionsMap<String,Object> where the key is the external ID of the question document and the value is the ID of the answer
userAgentUser agent value of the HTTP request
maximumSizeMaximum size of binary data in bytes. Default is 5242880.
doubleOptInParamsMap<String,String> which contains key-value mappings that are used to replace keys in the text of double-opt-in e-mails.
varName of the result variable

storeUserComment

Stores a user comment to file. Returns true, if successful.

Parameters
ParameterDescription
contentContent of the comment
documentTypePrimary type of the document
externalIdExternal ID of the document
parentIdThe id of the parent comment, if this is a response
headlineHeadline of the comment
ipAddressIP address as String
scopeScope of the result variable
serialProgramSerial program of the document, only relevant, if serial programs are used
categoryExternalIdThe external ID of the document describing the category of this comment, only relevant, if categories are used.
externalUserIdThe ID of the user. If the user is identified by his name, the field must be filled with the username.
usernameName of the user
varName of the result variable
typeType of the comment. Values could be "EDITOR", "GUEST" or null (default)

storeUserRating

Stores a user rating to file. Returns true, if successful.

Parameters
ParameterDescription
documentTypePrimary type of the document
externalIdExternal ID of the document
ipAddressIP Address as String
scopeScope of the result variable
serialProgramSerial program of the document, only relevant, if serial programs are used
valueValue of the rating
varName of the result variable

storeVoting

Stores a voting result of a user to file. Returns true, if successful.

Parameters
ParameterDescription
externalIdExternal ID of the document
formDataMap<String,Object> where the key is the name of the form field and the value is the user input for that field. If the value contains binary data it has to be a Set of FileItems.
ipAddressIP address as String
referrerReferrer value of the HTTP request
scopeScope of the result variable
selectionsMap<String,Object> where the key is the ID of the voting item and the value is the rank, which the user gave to the item (starting with 1)
userAgentUser agent value of the HTTP request
maximumSizeMaximum size of binary data in bytes. Default is 5242880.
doubleOptInParamsMap<String,String> which contains key-value mappings that are used to replace keys in the text of double-opt-in e-mails.
varName of the result variable

Example usage for a voting:

<jsp:useBean id="formData" class="java.util.HashMap" scope="request" />
<jsp:useBean id="selections" class="java.util.HashMap" scope="request" />
<%-- Here you have to insert the form data and the answers to the map --%>
<c:set var="referrer"><%=request.getHeader("referer")%></c:set> 
<sophora:storeVoting userAgent="${header['User-Agent']}" externalId="${param.votingExternalId}" formData="${formData}" selections="${selections}" ipAddress="<%=request.getRemoteAddr()%>" referrer="${referrer}" />

In this example, the map input should be provided as follows:

  • the keys of the form data map should be the field name, the values should be the values for that field
  • the keys of the selections map should be the UUID of the voting item, the values should be the rank the user has given to this voting item (starting with 1)

Node Functions

The node function gets its information from the webapp and supports caching. I.e., every time the user makes a submission the cache gets invalidated for that document.

Voting: getSimpleReport/getRankingReport

For evaluation of an voting there exists a node function. On the voting document node you invoke depending on the voting type the functions getSimpleReport or getRankingReport to get the report bean. The bean provides you with following information:

PropertyDescription
${report.headline}The headline of the voting document
${report.noOfParticipants}The number of participants in this voting
${report.winner}A bean with the voting item report for the voting item that won the voting
${report.votingItemReports}A list of voting item reports sorted by points

Each voting item has its own report. Each item has the following properties:

PropertyDescription
${item.name}The name of the voting item
${item.uuid}UUID of the item
${item.points}Points that were calculated for this item
${item.votesPerPlace}The votes this item got for each possible place. Only available, if the voting is designed as a ranking between all voting items.

There is a legacy report function called getReport, which returns a ranking report. Please refrain from using this function as it might be removed in future versions.

Rating: getRatingEvaluation

For each document you can get an evaluation of the already submitted Ratings by calling the node function getRatingEvaluation. The bean you get in return has the following properties:

PropertyDescription
${rating.externalId}The external id of the document the rating is for
${rating.numberOfRatings}The number of rating submissions
${rating.average}The average of all submitted ratings

Configuration of the Taglib

sophora.properties
PropertyDescriptionDefault
sophora.ugc.baseurlSet the address of your adminstration web app. If the administration webapp is using HTTP basic authentication, you may configure this in the form of http://user:password@localhost:9080/.http://localhost:9080/
sophora.delivery.function.packageNamesAppend "com.subshell.sophora.ugc.functions" to this list for registering the node function
sophora.delivery.model.packageNamesAppend "com.subshell.sophora.ugc.functions" to this list for registering the node function
sophora.ugc.maxImageWidthThe maximum width for image uploads (larger images will be scaled)2000
sophora.ugc.maxImageHeightThe maximum height for image uploads (larger images will be scaled)2000
sophora.ugc.minImageWidthThe minimum width for image uploads to accept960
sophora.ugc.minImageHeightThe minimum height for image uploads to accept960
sophora.ugc.maxImageFileSizeThe maximum file size for image uploads in bytes. Larger files will not be accepted.5242880
sophora.ugc.maxBinaryDataFileSizeThe maximum file size for binary form data in bytes. Larger files will not be accepted.5242880
sophora.ugc.clamdHostHost of the clamd service to scan image uploads and binary form data for viruses
sophora.ugc.clamdPortPort of the clamd service to scan image uploads and binary form data for viruses

You should at least configure the URL to your ugc-webapp in the property sophora.ugc.baseurl to display user generated content in your webapp.

Load Monitoring Configuration

If you want to use the load monitoring feature, you need to start a Spring context in your delivery webapp, that has this functionality. To achieve this you need to add the following in your web.xml:

<context-param> 
  <param-name>contextConfigLocation</param-name>
  <param-value>classpath:spring-usercontent.xml</param-value> 
</context-param> 
<listener> 
  <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> 
</listener>

There are several parameters to configure this feature in a file called taglib.properties. This file can be placed in your classpath and in the config folder of the webapp. The properties in the config folder have precedence.

taglib.properties
PropertyDescriptionDefault
sophora.ugc.loadrestriction.enabledRestrict the number of submissions allowedfalse
sophora.ugc.loadrestriction.updateintervalThe interval in milliseconds to write a new load information, which will be sent to the ugc-webapp10000
sophora.ugc.loadrestriction.requestsPerMinuteThe number of requests10000
sophora.ugc.loadrestriction.email.template.subjectSubject of the notification e-mail\u00dcberlastsituation auf Server
sophora.ugc.loadrestriction.email.template.textText of the notification e-mailDer Server hat die erlaubten Requests pro Minute \u00fcberschritten
sophora.ugc.loadrestriction.email.template.fromFrom of the notification e-mail
sophora.ugc.loadrestriction.email.template.replyToReply-To of the notification e-mail
sophora.ugc.loadrestriction.email.template.toTo whom shall the notification e-mail be sent.
This field is mandatory
sophora.ugc.loadrestriction.email.template.ccCC of the notification e-mail
sophora.ugc.loadrestriction.email.template.bccBCC of the notification e-mail
sophora.ugc.loadrestriction.email.transport.hostHostname or IP of the SMTP server
sophora.ugc.loadrestriction.email.transport.portPort of the SMTP server25
sophora.ugc.loadrestriction.email.transport.userUsername for SMTP server
sophora.ugc.loadrestriction.email.transport.passwordPassword for SMTP server
sophora.ugc.loadrestriction.email.transport.starttls.enableUse starttls for the connection to the SMTP servertrue
sophora.ugc.loadrestriction.minutesBetweenNotficiationsSend notifications only certain number of minutes after the last notification20
sophora.ugc.loadmonitoring.enabledEnable the reporting of the number of submissions to the ugc-webapptrue

Last modified on 10/16/20

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.

Icon