View source for How to configure ContentMetrics

[[ContentMetrics]] is added to a web site by configuring a ContentMetrics (CM) server and then registering the source web site that will communicate with the CM server.

== Configuring the ContentMetrics server ==

A ContentMetrics server (<code>'''%CM-SERVER%'''</code>) can be hosted on any web server that has MySQL 5+ and PHP 5+. Current available servers are:

* http://www.scottdstrader.com/cm/

The source web site must be registered with a user profile name (<code>'''%PROFILE-NAME%'''</code>) and host name (<code>'''%HOST-NAME%'''</code>). The <code>'''%PROFILE-NAME%'''</code> uniquely identifies the owner of the web site or sites being tracked by ContentMetrics. The <code>'''%HOST-NAME%'''</code> is the [http://en.wikipedia.org/wiki/Hostname hostname] of the web site without prefixes or suffixes such as <code>www.</code> or <code>.com</code>.

== Configuring the source web site ==

The following style sheet and two JavaScript file must be added to the <code><head></code> section of any page that will communication with the CM server:

 <link rel="stylesheet" type="text/css" media="screen"
     href="'''%CM-SERVER%'''/style/cm.css" />
 <script type="text/javascript"
     src="'''%CM-SERVER%'''/javascript/prototype-1.6.0/prototype.js"></script>
 <script type="text/javascript"
     src="'''%CM-SERVER%'''/javascript/cm.js"></script>

With these entries added, any number of regions can be added to the page. Each region will track metrics for that region and display configurable results. The result will display wherever the script is placed on the page. Here is the basic format of the region script:

 <script type="text/javascript"
     src="'''%CM-SERVER%'''/region_create.php?id='''%PROFILE-NAME%'''&region='''%REGION-ID%'''&votes='''%VOTES%'''&actions='''%ACTIONS%'''&metrics='''%METRICS%'''">
 </script>

[[Image:cm-region.png|thumb|An example of a region script displaying the metrics 1111111,1010]]

The following values are required:

* <code>'''%CM-SERVER%'''</code> and <code>'''%PROFILE-NAME%'''</code> - The CM server that will track the data under the profile registered on that server
* <code>'''%REGION-ID%'''</code> - A unique value within the registered <code>'''%HOST-NAME%'''</code>
* <code>'''%VOTES%'''</code> - A comma-delimited pair of maximum up- and down-votes:

<table class="wikitable">
<tr>
<th>Value (position)</th><th>Description</th>
</tr>
<tr>
<td>N,0</td><td>(default: 1) Maximum positive vote value. If 1, then an up-arrow is displayed. If &gt;1, then N number of right-pointing carets are displayed.</td>
</tr>
<tr>
<td>0,N</td><td>(default: -1) Maximum negative vote value. If 11, then an down-arrow is displayed. If &lt;1, then N number of left-pointing carets are displayed.</td>
</tr>
</table>

* <code>'''%ACTIONS%'''</code> - A [http://en.wikipedia.org/wiki/Mask_(computing) bit mask] of allowable actions for this view of the reigon:

<table class="wikitable">
<tr>
<th>Value (position)</th><th>Description</th>
</tr>
<tr>
<td>100,00</td><td>Record each visit. Turn off to use the region only for displaying metrics and voting on the content.</td>
</tr>
<tr>
<td>010,00</td><td>Allow visitors to up vote</td>
</tr>
<tr>
<td>001,00</td><td>Allow visitors to down vote</td>
</tr>
<tr>
<td></td><td></td>
</tr>
<tr>
<td>000,10</td><td>Display link to allow visitors to view reports</td>
</tr>
<tr>
<td>000,01</td><td>Display link to allow visitors to view [[ContentMetrics]]</td>
</tr>
</table>

* <code>'''%METRICS%'''</code> - A bit mask of what recorded metrics should be displayed. A comma is used to divide these into differnt sections.

<table class="wikitable">
<tr>
<th>Value (position)</th><th>Description</th>
</tr>
<tr>
<td>100,00000,0000</td><td>Display total visits</td>
</tr>
<tr>
<td>010,00000,0000</td><td>Display total unique visitors</td>
</tr>
<tr>
<td>001,00000,0000</td><td>Display total visits for the current visitor</td>
</tr>
<tr>
<td></td><td></td>
</tr>
<tr>
<td>000,10000,0000</td><td>Display total vote value (up votes - down votes)</td>
</tr>
<tr>
<td>000,01000,0000</td><td>Display average vote value (only useful when allowing muti-value votes)</td>
</tr>
<tr>
<td>000,00100,0000</td><td>Display total up votes</td>
</tr>
<tr>
<td>000,00010,0000</td><td>Display total down votes (as negative)</td>
</tr>
<tr>
<td>000,00001,0000</td><td>Display vote value for the current visitor</td>
</tr>
<tr>
<td></td><td></td>
</tr>
<tr>
<td>000,00000,1000</td><td>Display date and time of the first visit</td>
</tr>
<tr>
<td>000,00000,0100</td><td>Display date and time of the most recent visit</td>
</tr>
<tr>
<td>000,00000,0010</td><td>Display date and time of the first visit for the current visitor</td>
</tr>
<tr>
<td>000,00000,0001</td><td>Display date and time of the most recent visit for the current visitor</td>
</tr>
</table>

Any character that is not a zero or a one will be deleted before being interpreted by the CM server. The comma will be used in these example for convention, but any other character could be used (e.g. +, :, or X) Similarly, if not all bit value are specified, those missing will default to zero (off).

== Examples ==

Here are some examples of region scripts. These assume that the containing web page resides on a '''%HOST-NAME%''' registered under ''etheradmin'' on the CM server ''www.scottdstrader.com'':

 http://www.scottdstrader.com/cm/region_create.php?id=etheradmin&region=article-id-1024&actions=011&metrics=1111100,1100

This tracks metrics for the region ''article-id-1024''. Names are unique identifiers on the host name and can be referenced across any number of pages or even multiple times within a page. For a blog, you may want to include a region script for an article in multiple places: the main page, the category page, and the article's permalink page.

The actions ''011'' enable voting but do not record a unique visit when the page is displayed. This allows you to display metrics in a summary listing page without recording the viewing of those metrics as an actual visit. The actual page would contain the actions ''111'' in order to record the visit.

The metrics ''1111100'' (looking at the first seven) will display everything except those for the current visitor. The date/time metrics ''1100'' (the last four) will display the first and most recent visit, again excluding the first and most recent for the current visitor.

[[Category:ContentMetrics]]