Getting Started with ContentRoller

 

 

Introduction

 

ContentRoller is an easy to configure, setup, customize, and use social news, links and blogging environment similar to sites like Digg, Buzzup, DZone, The Server Side, Slashdot, etc.  ContentRoller also makes for a nice personal blogging environment.  ContentRoller has tons of features.  Including:

 

• Fresh, Rising, Popular, Older, Voting and Activity Views
• Article Voting and Spam Flagging With/Without Login
• Article Commenting (with voting and spam flagging)
• Optionally Allows Anonymous Commenting
• Completely Configurable Look and Feel
• Large Number of Configuration Options
• Supports Multiple RSS Feed Types
• Can Import From External RSS Feeds
• Advanced Searching (uses Lucene for indexing)
• Uses Ehcache for Object Caching
• Tag Cloud (with name normalization)
• New User Registration with Email Verification
• Can Define Allowed HTML
• Administrator Role Access
• Extremely Server Friendly
• WYSIWYG HTML Editing

 

Installation:

 

Of course, the goal is for ContentRoller to be an extremely easy environment to install, customize and use.  To this end, we currently provide a MySQL version of ContentRoller, and an embedded database version.  You can also use any other database by simply creating the database and pointing to it via JNDI (jPersist will adapt).

 

Installing ContentRoller is simply a matter of dropping the ContentRoller.war file into your servlet container’s (Tomcat, Resin) webapps directory.  In the case of the embedded version you’re done.  Simply start the server and type http://localhost:8080/ContentRoller and you should see what you see at http://www.ContentRoller.com.

 

In the case of the MySQL version, you first need to create the database in MySQL.  If you haven’t already, download the ContentRoller.sql file.  Then simply import the database into MySQL:

 

mysql -u user_with_create_permissions -ppassword < ContentRoller.sql

 

Then, create a new MySQL user and password (username=ContentRoller, password=ContentRoller), and assign it SELECT, INSERT, UPDATE and DELETE privileges for the ContentRoller database.  If your database server is accessible to others, you will want to change the username and password to something more secure, but this also requires changing the JNDI definition.

 

Next, you will need to copy the mysql-connector-java-*.jar file from /WEB-INF/lib to your shared lib directory.

 

If using Tomcat you’re good to go (Tomcat is predefined in the META-INF directory).  If you’re using Resin or another servlet container you may need to define a JNDI database resource.  For resin this would be:

 

<database jndi-name="jdbc/ContentRoller">

    <driver type="com.mysql.jdbc.Driver">

        <url>jdbc:mysql://localhost/ContentRoller</url>

        <user>ContentRoller</user>

        <password>ContentRoller</password>

    </driver>

</database>

 

At this point ContentRoller should be ready for use.  So, start the server and type http://localhost:8080/ContentRoller and you should see what you see at http://www.ContentRoller.com.

 

Installing ContentRoller as the default application (runs as http://www.host.com) usually just requires ContentRoller being moved to the ROOT directory in the webapps directory.

 

Getting ContentRoller to run under other containers may require more expertise, but it’s a simple Java servlet and should be easy for Java oriented web developers.  However, if you need assistance we are more then happy to provide support.

 

 

Customizing ContentRoller

 

As mentioned the goal is for ease of use.  ContentRoller was designed to be easily configured and customized via the following:

 

• ContentRoller style sheets (styles directory)
• ContentRoller JSP based templates  (WEB-INF/templates directory)
• Using Tags (tag files) and a Simple API
• ContentRoller properties and configuration files

 

The configuration and properties files are in the WEB-INF directory and they are as follows:

 

• ContentRoller.properties (a Java properties file that provides configuration properties to both the Java API and to the JSP via ${contentManager.properties.propertyName}), feel free to edit and/or add to it.

 

• ContentRoller.cloudTags (a little miss-leading, these are the normalized names that are seen in the tag cloud. example: Java, java).

 

• ContentRoller.feeds (optional external feeds that are imported into ContentRoller and it’s database).

 

• ContentRoller.htmlTags (you can control exactly what is and is not allowed for HTML content).

 

NOTE: It is not intended that any of the tag files be modified for simple changes, but you can modify them if you like (tag files are likely to change over time).  All the tag files are simple and can easily be copied and modified.  For example, if you want different menu options simply copy WEB-INF/tags/ContentRoller/menu.tag to WEB-INF/templates/menu.jsp make your changes and include it in the template:

 

• <jsp:include page=”/WEB-INF/templates/menu.jsp” />

 

 

Administration

 

One of the best features of ContentRoller is the fact that it is mostly self-managing.  There is not a whole lot of anything that has to be done outside of normal server and database activities.  However, there are some things an administrator needs to do, such as editing unwanted content and removing spam.

 

With ContentRoller spam can be managed by the users.  As users spam vote an article/comment, a minimum threshold may be reached at which time the article/comment will be marked as spam.  As more users spam vote, the spam will eventually reach a maximum threshold and the article/comment will be removed.  However, if an administrator spams an article, it will be given the maximum number and removed from all queues.  An administrator can also, at anytime, edit any article and/or make it not visible. 

 

NOTE: Reaching maximum spam only affects the article’s ability to be in the queues, but it can still come up in searches.  So, if an article is offensive, it should be edited and the offensive content removed.  However, comments are not searchable and will not be seen.

 

 

Managing Users

 

User management is also self-managed.  However, to define a trusted user (users who can enter HTML content unchecked), or to define an administrator, you have to edit the users table directly.  There is no way to change the administrator/trusted status via the web interface.  You can also disable a user account by deleting it and/or changing the password (adding a single character to the front of the encrypted password is very effective).

 

Database

 

The database is simple, and while referential integrity exists between article related tables, there is none associated with the user table.  This may change in the future, but for now the reasons are as follows:

 

• Feeds submit articles and we don’t want to create a user to have a feed.
• We have no need for cascading deletes and updates.
• and, we’re not keeping statistics on user activities.

 

Changes can be made to the database tables and/or their data (providing table names and column names are within jPersist’s mapping abilities) at anytime.  You can also change defaults, data types (within reason and acceptable bounds), and data size with no ill-effects to jPersist and/or ContentRoller.

 

However, if you change article data (clean the database, update searchable columns, etc), then the search index should be rebuilt (see next section).

 

 

Search Index

 

ContentRoller uses Apache’s Lucene for search indexing.  If the index gets out of sync with the database (via updates and/or deletes), your searches can start returning odd results.  If this happens, it’s time to rebuild the index.

 

Rebuilding the index happens when the index does not exist, so simply delete the index directory and/or all the files in it.

 

• Social News, Links, and Blogging
• Single- and Multi-User Blogging
• Database driven (JNDI/JDBC, can use any database)
• Popular, Fresh, Older, Rising and Activity Views
• Article Voting and Spam Flagging With/Without Login
• Article Commenting (with voting and spam flagging)
• Optionally Allows Anonymous Commenting
• Provides a Blogging API With Tags
• Simple JSP Templates
• Completely Configurable Look and Feel
• Large Number of Configuration Options
• Supports Multiple RSS Feed Types
• Can Import From External RSS Feeds
• Advanced Searching
• Search Results Can be RSS Feeds
• Search Results Can Also be Menu Items
• Uses Java 1.5-1.6 Concurrent Collections
• Uses Object Caching
• Tag Cloud (with normalization)
• New User Registration with Email Verification
• Can Define HTML That Is Allowed
• Administrator Role Access
• Extremely Server Friendly