This file describes the process of installing and configuration Nanocomment. A guide to switching from NBCom to Nanocomment is provided inline with these instructions, so this file is of use both to users installing to a fresh Nanoblogger directory and those replacing NBCom. ------------------------------------------------------------------------------- REQUIREMENTS See README for the list of required software. ------------------------------------------------------------------------------- DATABASE SETUP Nanocomment can be configured to use either a MySQL or a PostgreSQL database. If you'd like to save your comments from NBCom, a script is provided in sql/nbcom_convert.sh to output the necessary data as a series of insert statements. To create a new database in mysql, login as root and run the following: mysql> create database blog_comments; mysql> grant all privileges on blog_comments.* to 'blog'@'localhost' identified by 'PASSWORD'; Replacing PASSWORD with a password of your choosing. For postgresql, login as the database user to template1 and run the following: template1=# create database blog_comments; template1=# create role blog login password 'PASSWORD'; For postgresql, be sure to add the blog user to pg_hba.conf if necessary. Now run the appropriate script to create the comments table. For mysql: mysql -u blog -p blog_comments < sql/mysql_create_table.sql And for postgresql, run as the database user: psql -d blog_comments < sql/pgsql_create_table.sql Following this you will be able to import the data saved from NBCom. To provide the login credentials to Nanocomment, create a file in your blog directory named scripts/db.php (if you change the path of this file, edit the path at the top of cmt.php) containing a database identifier in the MDB2 format assigned to the variable $dsn. The contents of the file should look something like this: The syntax for mysql is the same; just replace "pgsql" with "mysql". Be careful not to include any whitespace outside of the delimiters (excepting a newline at the end of the file), as this could prematurely start output from the script, making it unable to then send the necessary HTTP headers. ------------------------------------------------------------------------------- A NOTE ON POSTGRESQL AND COUNT() Due to the way PostgreSQL handles indices, the count() function must perform a sequential scan of the table for every use. MySQL does not have this problem. If you use PostgreSQL and expect a large number of comments, this can cause the query to retrieve comment counts to become very slow. See http://archives.postgresql.org/pgsql-hackers/2005-01/msg00247.php for more information on this problem. One possible workaround described at http://www.varlena.com/GeneralBits/120.php is to use a separate table to store counts, updated by a trigger on the comments table. For Nanocomment, such a table would require the counts for each group of entry_id. To use this solution, run the following in the blog_comments database as the database user: create language plpgsql; create table comment_counts ( entry_id varchar not null, comment_count integer not null, CONSTRAINT comment_counts_pk PRIMARY KEY(entry_id) ); create or replace function count_init() returns trigger as $$ begin insert into comment_counts (entry_id, comment_count) values (NEW.entry_id, 0); return NEW; exception when unique_violation then return NEW; end; $$ language 'plpgsql'; create trigger count_init before insert on comments for each row execute procedure count_init(); create or replace function count_trig() returns trigger as $$ begin if TG_OP = 'INSERT' then update comment_counts set comment_count = comment_count + 1 where entry_id = NEW.entry_id; elsif TG_OP = 'DELETE' then update comment_counts set comment_count = comment_count - 1 where entry_id = NEW.entry_id; end if; return null; end; $$ language 'plpgsql'; create trigger comment_counts after insert or delete on comments for each row execute procedure count_trig(); grant select, insert, update on comment_counts to blog; Note that the count_trig() trigger selects the count row for update, so if you use this database outside of Nanocomment, long transactions inserting or deleting from the comments database will lock the rows. If you have existing data, initialize comment_counts with the following query: insert into comment_counts (entry_id, comment_count) (select entry_id, count(*) from comments group by entry_id); To make use of the new count method, replace $query in scripts/javascript.php with the following: select comment_count as count, entry_id from comment_counts; This will, of course, require a sequential scan of the comment_counts table, but this table will have fewer rows than comments except in the case of one comment per entry. ------------------------------------------------------------------------------- INSTALLING THE FILES The Nanocomment code is spread across several PHP scripts, some of which are generated from template files. A plugin is provided to generate the templates, and, in order to use the comment body XHTML validation, a set of XML Schema files must be installed. The file schema/bcml.xsd is the base of the blog comment schema definition, and a set of XHTML schema modules are provided to prevent a flurry a HTTP requests for every comment validation. The files should be installed in your blog directory as follows: $BLOG_DIR/ cmt.php img.php plugins/ nanocomment.sh schema/ bcml.xsd ... (all other files provided in schema) scripts/ Auth_TypeKey.php error.php funcs.php javascript.php rss2.php trackback.php templates/ consts.php display.php display_error.php display_header.php nanocomment.htm If you wish to change the scripts path, edit the paths in cmt.php, img.php, plugins/nanocomment.sh, scripts/funcs.php, scripts/javascript.php, scripts/rss2.php and templates/display_header.php. If you wish to change the schema path, change the NC_BCML_SCHEMA variable in your blog.conf, described below. cmt.php and img.php are the only scripts that read input from the user. Accessing the other PHP scripts directly won't do anything terrible, but you still may want to deny access to them via .htaccess or whatever means is allowed by your web server. Note that templates/nanocomment.htm is based on the makepage.htm template. If you've modified makepage.htm, you may want to modify nanocomment.htm to match. ------------------------------------------------------------------------------- MODIFYING BLOG.CONF The contents of nanocomment.conf must be copied into your blog.conf file and modified to suit your needs. The only variable that does not have an appropriate default is NC_TYPEKEY_KEY, which must be set to your Typekey token if you choose to use Typekey to identify commenters. Typekey authentication can be turned on using the NC_USE_TYPEKEY variable. If you want to use the RELAX-NG comment body validation instead of the XML-Schema validation, for example if you're using a version of libxml2 older than 2.6.23, set NC_BCML_VALIDATION_TYPE to "relaxng" Modify the BLOG_URL_ACTION variable in blog.conf to point to the cmt.php script: BLOG_URL_ACTION="cmt.php?article=" This is the same BLOG_URL_ACTION as used by NBCom. ------------------------------------------------------------------------------- MODIFYING TEMPLATES Two template changes are necessary to make use of Nanocomment: the entry templates must be modified to include comment links, and the page templates must be modified to include the javascript code to add comment counts. For clean installations of Nanoblogger, entry.htm, permalink_entry.htm and category_entry.htm already contain the following line: It's important to note here what appears after BLOG_URL_ACTION, as this will be used as the entry_ids for your comments. Nanocomment supports three different forms: $ARCHIVES_DIR/$permalink_file as provided in the Nanoblogger comments, /$permalink_file as suggested by NBCom, and $NB_EntryID. $permalink_file cannot be unless ENTRY_ARCHIVES is set to "1" in blog.conf, so I recommend using $NB_EntryID. If you already use NBCom, you will want this entry_id to match your current scheme in order that existing comment links will continue to work. If you do not currently use one of these three forms, you will need to modify the article_id_to_link function in scripts/funcs.php to convert your existing IDs to entry links. Besides the link to the comments page, an extra bit of Javascript is necessary to add the comment counts. In entry.htm, permalink_entry.htm and category_entry.htm, replace the commented-out line with something like the following if you haven't already for NBCom: | $template_cmtlink Note that the $NB_EntryID provided as the id attribute to the span and the parameter to getElementById must appear as such regardless of the parameter you provide to $BLOG_URL_ACTION. Only the argument to checkPosts should change if you use a different variable for the entry_id. If you wish to use trackbacks, also add the following: | $template_trackback In addition, you should provide links to the trackback URL for the entry. There are two means of doing so: a link with rel="trackback", and a block of RDF. The rel="trackback" link only makes sense when one is provided for page, so it should only be added to permalink_entry.htm. To use this, you might want to add the following to the now-crowded line of links beneath the entry: | Trackback link for this entry The RDF block contains the entry it describes, so it can be added to all three template pages. It looks like this: Now add the following below to category_archive.htm, main_index.htm, makepage.htm, month_archive.htm and permalink.htm if not already added for NBCom: ------------------------------------------------------------------------------- COMMENTS ON ARTICLES Article comments are somewhat more difficult, as the article plugin in nanoblogger 3.3 uses the makepage template which is shared by the archive index and is also a common choice for third-party plugins. My recommendtation is to use a separate template for articles. This can be done through additions to blog.conf and requires no plugin modifications. Make a copy of makepage.htm as article.htm in your templates directory. To your blog.conf, add the following: ARTICLE_TEMPLATE="$BLOG_DIR/templates/article.htm" $NB_TEMPLATE_DIR is not available at the time blog.conf is loaded. Add the following to article.htm:
$template_cmtlink
This relies on two variables set by the article plugin: $article_file, which is the path from the articles directory to the generated page, and $article_srcfile, which is the text file from which it was generated. $article_file is used as the ID to store the comment and the variable used for the link from the comments page back to the article. The "nanocomment/" prefix is provided as a special case in article_id_to_link so that everything after the / is assumed to be the path from the blog directory to the article in question. $article_srcfile is used for the span id, since it's less likely to contain characters that would be illegal for that attribute. ------------------------------------------------------------------------------- MODIFYING THE STYLESHEET Nanoblogger stylesheets already come with code for comments, so you probably don't need to change anything here. Nanocomment uses the classes "comments-head" and "comments-body", both of which appear in the nanoblogger stylesheets, and "comments-author", which is not in the nanoblogger stylesheets but available if you wish to use it for special formatting of the author name and link. The trackback display uses the classes "trackback-url" and "trackback-body", also defined in the default stylesheets. ------------------------------------------------------------------------------- UPDATING THE BLOG If you are switching from NBCom and did not change the template files, run "nb -u" to generate the Nanocomment script files. If you had to update any of the template files, run "nb -u all" to regenerate all of your pages with the Nanocomment additions.