RedSnow HomePage RS-ClickCounter Readme

RS-ClickCounter CGI

程式名稱：RedSnow Utility - RSClick (RS-ClickCounter CGI)

版本編號：1.41 (Freeware 1.41)

最初設計：1.00 版：1999/01/18

改版記錄：

1.00 版：1998/12/06	本程式由本網頁作者設計的 DLCounter2 修改而成，本版完成本程式初步架構與基本功能的設計。
1.10 版：1999/01/21	加強查看點選紀錄的顯示內容及中文字樣的處理。
1.20 版：1999/04/18	製作本說明文件並調整範例程式和部分程式內的變數名稱，使變數名稱及設定的方式較為一致。
1.40 版：1999/10/17	加上橫條狀比例圖示、增加各項目顯示時的位置(靠左、靠右、居中)設定。
1.30 版：1999/07/17	增加排序功能，使顯示出來的統計結果較為美觀。

最後修改：

1.41 版：1999/11/02

補強本文件有關使用 FORM 形式呼叫程式的說明部分，以及增加避免亂碼產生的注意事項。

作者姓名：RedSnow WorkRoom - 傅鴻銘

版權宣告：
本程式為傅鴻銘個人作品，按照中華民國法律於程式完成並公開發表之時，即擁有著作權等相關權利，他人不得侵犯。

作者聲明：
本 (1.41) 版 RS-ClickCounter 為免費共享軟體，任何人均可在不違反法律及不損害本人權益之前提下免費合法的使用，本聲明可視為作者對使用者合法免費使用的保障與授權聲明，但如有違犯下列事項者將不受本聲明之保障，作者並保留所有法律追訴權利：

不得利用本程式進行商業行為，包含灌錄至儲存媒體上販售或隨商品附贈給客戶，如有商業用途須取得作者授權。
不得修改程式內部表頭部分之字樣與本程式說明文件的內容。
傳播本程式者有義務讓被傳播對象瞭解作者聲明，以免被傳播者侵犯作者權益。

緣起：
作者曾數度被網友詢問到票選的功能要如何製作？也有網友希望紅雪網頁能提供這樣的程式，而票選動作的運作原理基本上是與本網頁的另一支程式 DLCounter2 有點類似，因此作者利用了一點時間將 DLCounter2 作了一些修改及測試後，本程式主要是以滑鼠點選項目後作計數及相對的處理，因此將程式命名為 RS-ClickCounter，舉凡檔案下載次數、網頁點選次數、網站評價、各類票選....等的紀錄功能都可以藉由本程式來達成，雖然尚有許多已經構想好的功能還沒有寫出來，但是為了能讓網友們先享用現有功能，所以先發表目前的 1.41 版，讓需要的網友們使用及參考。

安裝 RS-ClickCounter：
本程式的安裝很簡單，只要將 RSClick130.zip 解壓縮到任何一個目錄內，接著利用文書處理程式對 RSClick.pl 及部分的 HTML 檔作一些適當的修改，然後使用 FTP 軟體將 RSClick.pl 程式上傳到網頁所屬的 cgi-bin 目錄、reddot.gif 上傳到網頁所屬的個人根目錄內，HTML 檔案則上傳到欲放置的適當目錄內就可以了，細部說明請閱讀下一段。

使用 RS-ClickCounter 的方法：

檢查 RSClick.pl 程式的第一行 Perl 解譯程式的路徑及名稱是否符合您網頁所屬站台的規定，若不符合站台規定請修改該行設定，如果您是 TacoMax 的居民，設定應該如下：
#!/usr/local/bin/perl
修改 $realpath 變數的值：
$realpath 是設定紀錄檔(*.cnt、*.log、*.chk)所放置的實體(真實)路徑，如果不知道何為實體路徑？請向網頁所屬站台的管理人員詢問，如果您是 TacoMax 的居民，請直接參考下列方式設定：
my($realpath) = "/home/city1/urid/www/";

注意：urid 字樣請改為您在 TacoMax 使用的帳號。
調整 $sortType 變數的值：
$sortType 是設定顯示統計資料時排序的方式，若是設成 "12" 則表示由小排至大，若設成 "21" 則表示由大排到小 (內定預設值)。
my($sortType) = "21";

下列參數可視需要調整其內定值(紅色標示部分)：

my($RecordFile) = "RSClick";	存取紀錄資料的檔案名稱(不需設副檔名，因副檔名固定使用 .cnt、.log 及 .chk)，程式執行時點選次數的資料將紀錄於本參數所設同名的 .cnt 檔案中。附註：本參數可由網頁端以 file 參數更改。
my($WantLog) = n;	n 設為 1 時表示記錄網頁被載入時之日期時間及瀏覽者 IP 等資料。 n 設為 0 時表示不記錄。本項若設為 1 則將會在執行時將點選者的 IP、點選時間....的資料記錄於和 $RecordFile 參數所設同名的 .log 檔案中。附註：本參數可由網頁端以 log 參數更改。
my($CheckOver) = n;	n 設為 1 時表示程式被執行時檢查是否為同一個人在同一次連線時重複點選(不重複紀錄)。 n 設為 0 時表示不檢查(可重複紀錄)。本項若設為 y 則將會在執行時產生與 $RecordFile 參數所設同名的 .chk 檔案。附註：本參數可由網頁端以 chk 參數更改。
my($PercentPic) = http://.../reddot.gif;	設定顯示百分比圖例所使用的圖形檔案放置位置及名稱，本項可以設定為相對路徑，但是若您搞不清楚如何設定相對路徑？或是使用本程式的頁面分置於不同的目錄內，那就還是設成完整的 URL 比較妥當，本程式附有一個名為 reddot.gif 的圖檔，僅僅 34 個 Byte，您可以使用自己設計的圖形來替代，不過得提醒您注意顯示的效果及檔案的大小。
my($PicHeight) = n;	n 值代表顯示前一項 $PercentPic 所設的圖形時，所欲顯示的高度點數。

注意：

上述前三項參數若非必要可不必修改，因為前三項參數均可由網頁端在呼叫時以參數設定的方式變更之。
如果您的 CGI 程式放置站台未給您足夠的權限由 CGI 程式中建立新檔案的話，您必須自行建立好上述 $RecordFile 變數所設定的檔案，並自行上傳到程式中 $realpath 參數所設定的目錄去。

設定或修改 HTML 檔案中的執行敘述，可以使用下列的兩種方式來呼叫程式：

超聯結形式：
<A HREF="http://www.tacocity.com.tw/cgi-bin/cgiwrap/urid/RSClick.pl?參數1&參數2...">....
FORM 形式：
1. <FORM ACTION="http://www.tacocity.com.tw/cgi-bin/cgiwrap/urid/RSClick.pl" METHOD="POST">
  <INPUT TYPE=HIDDEN NAME=參數1 VALUE="參數1的值">
  <INPUT TYPE=HIDDEN NAME=參數2 VALUE="參數2的值">
  ........
  <INPUT TYPE=SUBMIT VALUE="確定送出">
  </FORM>
  注意：
  以 FORM 形式執行時，若將各個參數設在 INPUT 項目內，則 ACTION 的程式名稱後即無須設定參數。
2. <FORM ACTION="http://www.tacocity.com.tw/cgi-bin/cgiwrap/urid/RSClick.pl?參數1&參數2..." METHOD="POST">
  <INPUT TYPE=SUBMIT VALUE="確定送出">
  </FORM>
  注意：
  以 FORM 形式執行時，若仍將各個參數設在 ACTION 的程式名稱後的話，FORM 主體內就不可以設有 INPUT 之類的 FORM 物件，否則程式將無法正確接收參數。

注意：urid 字樣請改為您在 TacoMax 使用的帳號名稱。

參數說明：

自第二個參數開始，各參數之間必須以 & 符號連結。
file=紀錄檔的檔案名稱
紀錄資料所使用的檔案名稱(不含副檔名)，內定名稱為 RSClick，紀錄時檔案的完整名稱為：
RSClick.cnt = 紀錄點選項目的名稱與次數。
RSClick.log = 紀錄點選者的 IP、時間....等資料 (log 參數設為 1 時使用)。
RSClick.chk = 檢查是否有重複點選時使用的暫存檔 (chk 參數設為 1 時使用)。

cmd=執行動作的種類
本參數的種類有三種，而各參數又有數項不等的資料需設定：

view,TITLE,
BORDER,
ALIGN1,
ALIGN2,
ALIGN3,
ALIGN4

本功能為查看點選次數的統計結果，TITLE 是設定欲顯示的標題字樣，BORDER 是設定欲顯示的邊框種類，ALIGN1 到 ALIGN4 這四項則是分別設定顯示統計結果的四個項目(點選項目、點選次數、圖示比例、比例數字)資料所顯示的規則(靠左、靠右、居中)，可用設定值及預設值如下表：

TITLE：
可用設定值為任意的中英文字樣，預設值為 "點選次數統計表" 字樣，本項目為選擇性設定項目。
BORDER：
可用設定值為 1(立體細邊框) 或 2(黑色細邊框)，預設值為 1 也就是立體邊框，本項目亦為選擇性設定項目。
ALIGN1 至 ALIGN4：
可用設定值為 L(靠左)、R(靠右)、C(居中)，預設值分別為 C(居中)、R(靠右)、L(靠左)、R(靠右)，這四個項目亦為選擇性設定項目。

統計的頁面將顯示 TITLE 參數所指定的標題字樣，並按照 BORDER 的設定來顯示統計表框的種類，及依據 ALIGN1 至 ALIGN4 的設定來顯示相關資料，若未設定逗號及左框內以綠色標示的項目，則將使用程式預設的資料來顯示標題、邊框及處理顯示的位置。

參數設定範例如下：
cmd=view
cmd=view,票選結果
cmd=view,票選結果,2
cmd=view,票選結果,2,C,R,L,R

顯示範例如下：
BORDER 項的值設為 2 時：

點選項目點選次數圖示比例比例數字

資訊分享 210 37.71%

技巧展示 112 20.12%

FAQ問答集 109 19.58%

免費資源 109 19.58%

網點服務 17 3.06%

總計 557 100%

BORDER 項的值設為 1，或不設定 BORDER 項時：

點選項目點選次數圖示比例比例數字

資訊分享 210 37.71%

技巧展示 112 20.12%

免費資源 109 19.58%

FAQ問答集 109 19.58%

網點服務 17 3.06%

總計 558 100%

url,PATH&FILE

PATH&FILE 是代表一個 HTTP 格式的網址或檔案名稱，執行的結果將會視其副檔名的種類而作不同的處理，若設定的名稱為一個純粹的網址或網頁名稱，那麼將會顯示該位址的內容於瀏覽器上，例如副檔名為 .zip 或 .exe 則會作檔案下載的動作，例如：
下載檔案：cmd=url,http://www.redsnow.com/myprog.zip
瀏覽網頁：cmd=url,http://www.redsnow.com/myprog.htm
查看圖檔：cmd=url,http://www.redsnow.com/myprog.gif

hit,NEXTPAGE

NEXTPAGE 是代表點選後欲顯示另一網頁的路徑及名稱，本功能為紀錄點選的次數並顯示 NEXTPAGE 參數所指定的頁面，若未設定逗號及前述的顯示頁面名稱則預設的動作是顯示點選的統計結果，例如：
cmd=hit,http://www.redsnow.com/ThankYou.htm

name=紀錄在 .cnt 檔案內的名稱
本參數的字樣中不可使用 & , 這兩個符號及空白字元，若字樣間需要使用空白字元必須以 + 符號來替代，並且大小寫的英文字元將視為不同的識別字樣，例如：
name=Microsoft+IE+5.0
log=n
設定是否紀錄點選者的 IP、點選時間....等資料：
n 設為 1 時表示記錄。
n 設為 0 時表示不記錄。
本項可省略而使用程式內 $WantLog 參數的預設值。
chk=n
設定是否允許同一個人在同一次連線時重複點選同一項目：
n 設為 1 時表示程式被執行時檢查是否為同一個人在同一次連線時重複點選(不重複紀錄)。
n 設為 0 時表示不檢查(可重複紀錄)。
本項可省略而使用程式內 $CheckOver 參數的預設值。

參數範例 (其它 HTML 相關指令予以省略)：

下載檔案：

範例	RSClick.pl?file=DLCount&cmd=url,http://www.redsnow.com/abc.exe&name=My+ABC+Program
解說	下載位於 http://www.redsnow.com/ 的 abc.exe 這個檔案。紀錄 "My ABC Program" 字樣及計次資料於 DLCount.cnt 這個檔案中。

滿意度調查：

範例	RSClick.pl?file=HitCount&cmd=hit&name=還可以啦！&log=1&chk=1
解說	紀錄 "還可以啦！" 字樣及計次資料於 HitCount.cnt 這個檔案中。將點選者的 IP 及點選時間紀錄於 HitCount.log 這個檔案中。不允許同一個人在同一次連線時點選 "還可以啦！" 這個計次項目。因為 cmd 參數僅設定 hit 而沒有設定後續的顯示頁面參數，所以執行後會顯示 HitCount.cnt 這個檔案內的統計結果。

瀏覽次數紀錄 (可放在選單的連結項目裡)：

範例	RSClick.pl?file=PageCount&cmd=url,http://www.redsnow.com/free.htm&name=免費資源&log=1
解說	紀錄 "免費資源" 字樣及計次資料於 PageCount.cnt 這個檔案中。將點選瀏覽免費資源這個頁面訪客的 IP 及點選時間紀錄於 PageCount.log 這個檔案中。由瀏覽器載入 http://www.redsnow.com/free.htm 這個頁面檔案。

查看統計結果：

範例	RSClick.pl?file=FileCount&cmd=view,檔案下載次數統計表
解說	查看 FileCount.cnt 這個檔案中的點選次數紀錄，並以統計表的形式顯示出來。顯示統計資料的結果時，標題名稱顯示為 "檔案下載次數統計表"。

將程式(RSClick.pl)、設定好或更改過的 HTML 檔，以 FTP 程式上載到網站上：
RSClick.pl → 您的帳號目錄內的 cgi-bin 次目錄
reddot.gif → 您的帳號目錄內根目錄
HTML 檔案 → 您的帳號目錄內任意適當位置
注意：如果您的 CGI 程式放置站台未給您足夠的權限由 CGI 程式中建立新檔案的話，您必須自行建立好各個 *.cnt、*.log 及 *.chk 這些檔案，並自行上傳到程式中 $realpath 參數所設定的目錄去。
更改相關檔案的屬性：
RSClick.pl 屬性至少設為 700。
reddot.gif 屬性至少設為 644。
注意：某些站台的屬性要求有不一樣，應以各站台的規定為準。
有關亂碼問題：
有些網友在使用本程式後，曾反映過 name 參數使用中文字樣的話會產生亂碼，經作者到網友的網頁去作實地測試時卻又一切都正常，因此這個問題一直讓作者很頭疼，經網友提供資訊及作者反覆多次測試後，發現有以下的事情必須注意：
1. 若使用 FORM 方式來呼叫執行本程式的話，請確定符合 FORM 形式的呼叫設定要求。

其它事項：

使用本程式需在 Web Server 的 CGI 能提供正常服務時，才能發揮適切的作用，如果 CGI 不能運作，則您指定的網頁也將無法顯示出來，請您使用前要慎思。
統計結果中的百分比係僅供參考之用，因為顧及版面的安排及顯示上的美觀，故百分比的小數點僅取兩位數來顯示，加總的的結果可能不會是剛好百分之一百，若您真的對百分比的準確性很在意的話，可以自行更改顯示的規則。
舊用戶請注意：本程式自 1.3 版開始將資料檔的分隔符號更改了，如果您已經是 1.3 之前版本的使用者，而您希望沿用舊資料檔的話，請自行修改資料檔內各資料的分隔符號，將原先的一個冒號 (:) 改為兩個冒號 (::)。
如果您想將本程式擺在您的網頁上分享給更多的網友，請告訴作者您放置程式的網頁位址，作者在本程式有更新資訊或有其它程式要分享出來時會知會您一聲。
如果您對本程式有任何意見或想給作者一點鼓勵，歡迎您到作者網頁留言或來信指教。

　聯絡作者：redsnow@pmail.net

　作者網頁：http://www.tacocity.com.tw/redsnow/index.htm

　本文撰寫於中華民國88年04月17日　修改於中華民國88年10月24日