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
- no more submissions will be accepted
- an e-mail is sent notifying you about this event
storeDoubleOptIn
This tag should be used on the site where the user is directed to confirm his submission.
Parameters| Parameter | Description |
|---|
| optInId | ID of the opt-in event |
| scope | Scope of the result variable |
| var | The name 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| Parameter | Description |
|---|
| var | Set the name of the variable that stores the result. |
| scope | Scope of the result variable |
Attributes of the result| Attribute | Description |
|---|
| success | boolean property that signals if saving the upload to file was successful |
| error | Enum 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| Parameter | Description |
|---|
| externalId | External ID of the document |
| formData | Map<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. |
| ipAddress | IP address as String |
| referrer | Referrer value of the HTTP request |
| scope | Scope of the result variable |
| selections | Map<String,Object> where the key is the external ID of the question document and the value is the ID of the answer |
| userAgent | User agent value of the HTTP request |
| maximumSize | Maximum size of binary data in bytes. Default is 5242880. |
| doubleOptInParams | Map<String,String> which contains key-value mappings that are used to replace keys in the text of double-opt-in e-mails. |
| var | Name of the result variable |
storeUserRating
Stores a user rating to file. Returns true, if successful.
Parameters| Parameter | Description |
|---|
| documentType | Primary type of the document |
| externalId | External ID of the document |
| ipAddress | IP Address as String |
| scope | Scope of the result variable |
| serialProgram | Serial program of the document, only relevant, if serial programs are used |
| value | Value of the rating |
| var | Name of the result variable |
storeVoting
Stores a voting result of a user to file. Returns true, if successful.
Parameters| Parameter | Description |
|---|
| externalId | External ID of the document |
| formData | Map<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. |
| ipAddress | IP address as String |
| referrer | Referrer value of the HTTP request |
| scope | Scope of the result variable |
| selections | Map<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) |
| userAgent | User agent value of the HTTP request |
| maximumSize | Maximum size of binary data in bytes. Default is 5242880. |
| doubleOptInParams | Map<String,String> which contains key-value mappings that are used to replace keys in the text of double-opt-in e-mails. |
| var | Name 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:
| Property | Description |
|---|
${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:
| Property | Description |
|---|
${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. |
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:
| Property | Description |
|---|
${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| Property | Description | Default |
|---|
sophora.ugc.baseurl | Set 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.packageNames | Append "com.subshell.sophora.ugc.functions" to this list for registering the node function | |
sophora.delivery.model.packageNames | Append "com.subshell.sophora.ugc.functions" to this list for registering the node function | |
sophora.ugc.maxImageWidth | The maximum width for image uploads (larger images will be scaled) | 2000 |
sophora.ugc.maxImageHeight | The maximum height for image uploads (larger images will be scaled) | 2000 |
sophora.ugc.minImageWidth | The minimum width for image uploads to accept | 960 |
sophora.ugc.minImageHeight | The minimum height for image uploads to accept | 960 |
sophora.ugc.maxImageFileSize | The maximum file size for image uploads in bytes. Larger files will not be accepted. | 5242880 |
sophora.ugc.maxBinaryDataFileSize | The maximum file size for binary form data in bytes. Larger files will not be accepted. | 5242880 |
sophora.ugc.clamdHost | Host of the clamd service to scan image uploads and binary form data for viruses | |
sophora.ugc.clamdPort | Port of the clamd service to scan image uploads and binary form data for viruses | 0 |
sophora.ugc.clamdErrorForVirus | A detected virus should cause an error response | false |
sophora.ugc.request.maxNumberOfCurrentConnections | The maximum number of current connections to get the rest template | 50 |
sophora.ugc.request.connectionTimeoutMs | The connection timeout in milliseconds for the request to get the rest template | 2000 |
sophora.ugc.request.socketTimeoutMs | The socket timeout in milliseconds for the request to get the rest template | 2000 |
sophora.ugc.request.errorCacheTimeMs | The time in millisecons how long an error entry will be in the error cache | 300000 |
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| Property | Description | Default |
|---|
sophora.ugc.loadrestriction.enabled | Restrict the number of submissions allowed | false |
sophora.ugc.loadrestriction.updateinterval | The interval in milliseconds to write a new load information, which will be sent to the ugc-webapp | 10000 |
sophora.ugc.loadrestriction.requestsPerMinute | The number of requests | 10000 |
sophora.ugc.loadrestriction.email.template.subject | Subject of the notification e-mail | \u00dcberlastsituation auf Server |
sophora.ugc.loadrestriction.email.template.text | Text of the notification e-mail | Der Server hat die erlaubten Requests pro Minute \u00fcberschritten |
sophora.ugc.loadrestriction.email.template.from | From of the notification e-mail | |
sophora.ugc.loadrestriction.email.template.replyTo | Reply-To of the notification e-mail | |
sophora.ugc.loadrestriction.email.template.to | To whom shall the notification e-mail be sent.
This field is mandatory | |
sophora.ugc.loadrestriction.email.template.cc | CC of the notification e-mail | |
sophora.ugc.loadrestriction.email.template.bcc | BCC of the notification e-mail | |
sophora.ugc.loadrestriction.email.transport.host | Hostname or IP of the SMTP server | |
sophora.ugc.loadrestriction.email.transport.port | Port of the SMTP server | 25 |
sophora.ugc.loadrestriction.email.transport.user | Username for SMTP server | |
sophora.ugc.loadrestriction.email.transport.password | Password for SMTP server | |
sophora.ugc.loadrestriction.email.transport.starttls.enable | Use starttls for the connection to the SMTP server | true |
sophora.ugc.loadrestriction.minutesBetweenNotficiations | Send notifications only certain number of minutes after the last notification | 20 |
sophora.ugc.loadmonitoring.enabled | Enable the reporting of the number of submissions to the ugc-webapp | true |
