getting started: setting up the database
getting started: database connections
getting started: live demo
making your own: code samples & break downs
making your own: loadCommentsEngine explained
making your own: for data driven sites
making your own: fancy web 2.0 URLs
the configuration file

Getting Started

This is a quick guide to get you started with the commentsEngine (cE) site wide commenting/discussion system.

setting up the database

Step One: finding the SQL file

In the download package find the folder called "SQL" and the file inside called "com_eng_db.sql”.

This contains all the SQL to create the database to hold all those exciting comments and discussions.

Step Two: Creating the database

So we have our SQL file, now we need to import it into a MySQL server. Open up PHPMyAdmin or some other MySQL administrator panel that you use.

First thing we need to do is to create a database. Lets call it "com_eng_db"

(note: if you already have a database for your website then you can skip that step – but if you are importing cE tables into an exsisting database then remember to make a backup first.)

Once you’re in then copy and paste the SQL code from the above file into the area of your administrator panel that normally allows you to run SQL queries.

database connections

Now that we have the database set up we need to create a database connection. Find the "config" folder in the download package and open the "config_global.php" file.

All we need to do is to change the first few settings. Enter your database server name, your database name and any login details for your database server. 

            define('DB_HOST', 'localhost');
            define('DB_NAME', 'yourdbase');
            define('DB_USERNAME', 'root');
            define('DB_PASSWORD', '');

More details on the other configuration settings can be found here

the live demo!

If you're anything like me then you want to quickly see this in action so I've created a live demo for you to have a quick look at and to use as a live coding example to refer to. This is located in the "index" folder in the download package - inside that folder find the "page.php" and "video.php" files. All the other js, css and image files that you need are also located in the index folder.

I've given you two live examples so you can search "across the site" by leaving comments on one page while search in the other.

You will also find a quick way to create user sessions for normal users and moderators so you can test out the system without too much fuss.

making your own

code samples & breakdowns

Okay, okay. Enough with the live demo. Let us dive into the actual code to understand all the features avaliable.

If setting up the database went well, the rest of this should be a breeze. If you have any issues use the live demo in the "index" folder as a working example.

I’ll explain all this code in a bit, but just to show you what it'll look like in the end:

In the head tag of your web page you'll need:

                <link rel="stylesheet" href="css/com_css.css" type="text/css">
                <script type="text/javascript" src="js/com_eng.js"></script>
                <script type="text/javascript" src="js/corners.js"></script>
                <script type="text/javascript" src="js/jquery-1.4.2.min.js"></script>
                
                <script>
                        $(document).ready(function () {
                        
                        
                           loadCommentsEngine('my_holiday_video','video');
                            
                            //just rounding corners using corners.js
                            $('.ub_corners').corner('5px');
                            
                        });
                </script>

And somewhere in the body of the page:

        <div id='com_eng'>loading comments engine...</div>

the code breakdown

First line is the import of the cE style sheet – pretty standard stuff.

        <link rel="stylesheet" href="css/com_css.css" type="text/css">

The next set of links include the actual commentsEngine js file, the corners js file (just to create corners on the html) and the standard jQuery file.

        
        <script type="text/javascript" src="js/com_eng.js"></script>
        
        
        <script type="text/javascript" src="js/corners.js"></script>
        
        
        <script type="text/javascript" src="js/jquery-1.4.2.min.js"></script>

And finally in the header section (inside the head tag), the import of the standard jQuery "document ready" opener and the basic cE function call (I’ll explain the functions in a moment) 

        <script>
                    $(document).ready(function () {

                       loadCommentsEngine('my_holiday_video','video');
                        //just rounding corners using corners.js
                        $('.ub_corners').corner('5px');
                        
                    });
        </script>

Then in the body of your page you need the actual cE container. Please keep the name of this container as "com_eng" – in future versions I’ll try to allow you to name the container whatever you like. 

        <div id='com_eng'>loading comments engine...</div>

explaining the loadCommentsEngine function

As cE works with both dyanmic data driven websites and static content I'll take some time to explain how the loader function (loadCommentsEngine) works in both cases (data driven and static content).

Let's look at all the parameters: (this is mainly for static websites but dynamic content owners should read this too)

First: this is the page or “content” ID value. So, for example, if your site hosted videos and the video ID value was “sJHjh767” then this is what should go in here for that particular page.

Second: this is the “content type” value. Now say that you had an awesome website that hosted videos and images. Now there is a chance that you may have a video and an image with the same ID value. This parameter allows you to prevent any clashes by allowing you to state a “content type”.

So you could have 

loadCommentsEngine('“3287oIUYy”','video');

and

loadCommentsEngine('“3287oIUYy”','images');

IMPORTANT: the name of the content type is important - in the current version of commentsEngine it refects directly in the dynamically generated links when searching across the site. More information about that here.

for data driven sites

Okay, now the fancy stuff. Dealing with dynamic content, IDs and types.

Hopefully you’ve read the section above, if not, then do so now.

If you have a data driven website then this is function call you need 

    loadCommentsEngine();

That’s it!

Okay, so how does this work? Well, it searches the url string of your web page to workout all the settings it requires. So if your web page loads with a content type and content ID in the URL eg:

Mydomain.com/?id=83jJhsy&type=videos

Then cE will automagically find and process everything for you. If you are missing say the content type value, say because you only deal with one type of content then use this: 

loadCommentsEngine(false,'video');

One thing I must point out is that your URL must have “type” and “id” as the names for these values.

If it doesn’t then don’t worry. Just open up com_eng.js in the index/js folder.

Now search & replace every instance of getUrlVars()['type'] and getUrlVars()['id'] renaming ‘id’/’type’ with your own field values.

So if your URL is like this

Mydomain.com/?contentid=83jJhsy&contenttype=videos

Then search and replace to this 

getUrlVars()['contenttype']
getUrlVars()['contentid']

Done!

search results & content types

Okay, just a quick word about content types and search results from site wide searches.

When searching across the site, cE creates links at the end of each comment to the page that the comment was left on. It currently takes in to account the content type (say 'video' or 'images') to create that link. So in this example: 

loadCommentsEngine('“3287oIUYy”','img');

If a comment was left on that page the link will look like this

"img.php?type=img&id=3287oIUYy".

If you site works on the basis that the page is always called, say 'content.php' or 'index.php' then that's okay. But you'll need to make some changes in the com_eng.js file in index/js folder around line 816.

This is not as scary as it looks if you're new to javascript! I'll show you an example below. 

switch(dataArray[x]['element_type']){
        case 'page':
                pageBuildUp = pageBuildUp.replace("##pageurl##",'page.php?type='+dataArray[x]['element_type']+'&id='+dataArray[x]['elementid']);
                break;
        case 'video':
                pageBuildUp = pageBuildUp.replace("##pageurl##",'video.php?type='+dataArray[x]['element_type']+'&id='+dataArray[x]['elementid']);
                break;
        case 'user':
                pageBuildUp = pageBuildUp.replace("##pageurl##",'user.php?type='+dataArray[x]['element_type']+'&id='+dataArray[x]['elementid']);
                break;
        case 'img':
                pageBuildUp = pageBuildUp.replace("##pageurl##",'img.php?type='+dataArray[x]['element_type']+'&id='+dataArray[x]['elementid']);
                break;
        default:
                pageBuildUp = pageBuildUp.replace("##pageurl##",'page.php?type='+dataArray[x]['element_type']+'&id='+dataArray[x]['elementid']);
                break;
        
}

So lets say all your content is displayed on a page called "content.php" and you use the type and id values to find your content then change it to the code below: 


    pageBuildUp = pageBuildUp.replace("##pageurl##",'content.php?type='+dataArray[x]['element_type']+'&id='+dataArray[x]['elementid']);

fancy web 2.0 URLs

I know what you’re thinking now. “My site is awesome web 2.0 cool, it’s URLs look like this:”

http://www.mydomain.com/videos/8su87sKK

Well that’s fine and dandy and it will work with this but it’s not a feature that is currently “supported”. So you’ll have to do some tinkering.

Now I’ve done some of the base work on this in the com_eng.js file in the function called "loadCommentsEngine" – see the parts that are “commented out”. Because there are so many ways this could work I could not code a catch all method. So you’ll have to play around with this and the area mentioned in search results & content types

If you are still having problems with this then as a last resort you can drop me an email for some help!

In future editions I will try to create a catch all system.

the configuration file

This is the configuration file settings for the commentsEngine.

variable values default value comments
FLOOD_CONTROL [true/false] true Set to true if you want to activate flood control.
FLOOD_CONTROL_DURATION [numeric value] 30 Flood control wait time in seconds. This will only work if ‘FLOOD_CONTROL’ is set to true.
MOD_Q [true/false] true Set to true if you want moderate comments before showing them. This applies across the whole site.

That's your lot. If you find any bugs or features you'd like to see in future editions then contact me asap