Getting Started

Repository

In order to use all features of the user generated content addon some configurations have to be made and some documents and scripts need to be imported. There is file named ugc-4.X.X-sophora.zip in our Maven repository (X needs to be replaced by the version you are using). The archive consists of configurations and documents in the Sophora XML format. If you want to try the addon in a test environment, just import all of these files and use the order of the folders as import order.

If you want to configure your production system, you don't need to import the node types labeled "04_example_nodetypes". They are helpful for a fresh start in a system where there haven't been any quizzes, votings and forms before. You don't need to use them, if you configure your node types accordingly and configure the usage of your properties in the configuration file of the ugc-webapp.

Finally, you need to activate the parts of the addon you bought. Get in touch with us for this step.

Database

This addon needs to have a database in a MySQL database system. Create a database and ensure that you have a user that has been granted all rights to this database (at least SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX, CREATE TEMPORARY TABLES).
To be able to use emojis like 😀 in the user comments you have to add the lines

character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

in the MySQL server configuration. Furthermore in the database url of the application.yml file you have to add ?useUnicode=true. When creating the database the collation should be utf8mb4_unicode_ci.

Once the database has been set up and the UGC-Webapp has created the required tables, we recommend that you create additional indexes. This speeds up the creation of the document overview pages in the editorial-ui considerably.

CREATE INDEX `INDEX_USERCOMMENT_EXT-ID_CRE-AT_DEL-AT` ON `usercomment` (EXTERNALID, CREATEDAT, DELETEDAT) COMMENT '' ALGORITHM DEFAULT LOCK DEFAULT;
CREATE INDEX `INDEX_USERCOMMENT_EXT-ID_CRE-AT_APP-AT_DEN-AT_DEL-AT` ON `usercomment` (EXTERNALID, CREATEDAT, APPROVEDAT, DENIEDAT, DELETEDAT) COMMENT '' ALGORITHM DEFAULT LOCK DEFAULT; 
CREATE INDEX `INDEX_USERCOMMENT_EXT-ID_PARENTID_APP-AT_DEL-AT` ON `usercomment` (PARENTID, APPROVEDAT, DELETEDAT) COMMENT '' ALGORITHM DEFAULT LOCK DEFAULT;


CREATE INDEX `INDEX_IMAGEUPLOAD_EXT-ID_CRE-AT_DEL-AT` ON `imageupload` (EXTERNALID, CREATEDAT, DELETEDAT) COMMENT '' ALGORITHM DEFAULT LOCK DEFAULT;
CREATE INDEX `INDEX_IMAGEUPLOAD_EXT-ID_CRE-AT_APP-AT_DEN-AT_DEL-AT` ON `imageupload` (EXTERNALID, CREATEDAT, APPROVEDAT, DENIEDAT, DELETEDAT) COMMENT '' ALGORITHM DEFAULT LOCK DEFAULT;

CREATE INDEX `EXTERNALID` ON `userrating` (EXTERNALID) COMMENT '' ALGORITHM DEFAULT LOCK DEFAULT;

Install UGC-Webapp

Get the webapp packed as tar.gz that has the same minor version as your Sophora system from software.subshell.com. It's recommended to install the addon as a service. The following folder structure is typically used.

cms-install-directory
-- apps
---- ugc-4.X.X
------ ugc-4.X.X.jar
---- ugc > Symbolic link to ugc-4.X.X
---- ...
-- ugc
---- config
------ application.yml
------ logback.xml
---- logs
---- ugc.conf 
---- ugc.jar > Symbolic link to ../apps/ugc/ugc-4.X.X.jar

This hierarchy is analogous to the directory structure of the Sophora server.

In application.yml you should adapt the configuration of the connection to your Sophora server and database to match your settings.

# this configures the connection to your Sophora server. Adapt this to match with your settings
sophora-server: 
	host: "http://localhost:1196"
	username: "admin"
	password: "admin"

# configuration of the database connection. Adapt this to match with your settings
database : 
   	# url of the jdbc connection, the last part is the name of the database 
	url : "jdbc:mysql://localhost:3306/usercontent"
	# username for database 
	user : "USERNAME"
	# password for database 
	password : "PASSWORD"
	
# configure the port of the embedded jetty
server: 
	port: 9080
	
# ratings, image uploads and comments can be enabled for a list of node types
rating: {
	primaryTypes: ["sophora-content-nt:story"]
	
image-upload: 
	primaryTypes: ["sophora-content-nt:story"]
	
comment: 
	primaryTypes: ["sophora-content-nt:story"]
	
	
# make the ugc-webapp to your main app to enable full functionality
isMainApp: true

The ugc.conf file has to specify the logging configuration file and the application.yml file to use. Additionally other vmargs e.g. java heap size configurations can be added.

JAVA_OPTS='-Xmx1g -Dlogging.config=<cms-install-directory>/ugc/config/logback.xml -Dspring.config.location=<cms-install-directory>/ugc/config/application.yml'

You can start the ugc-webapp by executing ugc.jar.

Enable the Add-on in Your Delivery Webapp

To enable the addon in your webapp, you have to add two dependencies to your pom.xml

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

Additionally, you have to enable the Spring context for the submitter in the web.xml of your webapp

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

Now, you can use the tags of the taglib to save user generated content.

UGC-Demo Example Webapp

The project ugc-demo offers the possibity to test the features offered by the user generated content. Get the ugc-demo packed as tar.gz that has the same minor version as your Sophora system from our software repository.

Configuring UGC-Demo

In src/webapp/WEB-INF/sites/sophora.properties you should adapt the configuration of the connection to your Sophora server to match your settings. You can also adapt the configuration to activate caching.

Exemplary sophora.properties File:

sophora.serviceUrl=http://localhost:1196
 sophora.delivery.client.username=admin 
sophora.delivery.client.password=admin

 # Enable or disable DevToolbar 
sophora.delivery.showDevToolbar=true 

# Caching configuration 
sophora.delivery.cache.db=derbyng
 sophora.delivery.cache.enabled=false
sophora.delivery.cache.directory=../ugc-demo/cache
sophora.delivery.cache.remove.notify.email= 
sophora.delivery.cache.remove.filterPattern.structureNode=

 sophora.delivery.defaultNamespaces=sophora, sophora-content,sophora-extension,sophora-ugc 

sophora.ugc.baseurl=http://localhost:9080/ 

sophora.delivery.function.packageNames=com.subshell.sophora.ugc.functions, com.subshell.sophora.ugc.demo 
sophora.delivery.model.packageNames=com.subshell.sophora.ugc.functions

For further details about the properties supported in sophora.properties you can take a look at the documentation of the delivery configuration.

In src/webapp/WEB-INF/classes/submitter.properties you should adapt the url of the submitter to match your settings, for example:

sophora.ugc.submitter.webapp.url=http://localhost:9080/rest/submissions

Local Configuration Directory

Instead of adapting sophora.properties and submitter.properties in the ugc-demo you can use a local configuration directory. Therefore you can adapt src/webapp/META-INF/context.xml to match your local configuration directory's path.

Exemplary context.xml File:

<?xml version='1.0' encoding='utf-8'?>
 <Context>
 	<Parameter name="jsonDump" value="../ugc-demo/json_dump"/>
 	<Parameter name="localConfigDirectory" value="../ugc-demo"/>
 	<Environment name="logPath" value="../ugc-demo/logs" type="java.lang.String"/>
 </Context>

Starting UGC-Demo

You can start ugc-demo using Apache Tomcat. The URL to access the demo depends on your configuration. In a local environment e.g. you can access it under:

http://localhost:8080/ugc-demo/demosite/index.html