Join, Evaluate, Sort, and Print (csv) Tables on a web page
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
181123.csv
Expression.php
LICENSE
README.md
config.json
div.csv
index.php
jesp.css
jesp.js

README.md

jesp: Join, Evaluate, Sort, and Print csv files

jesp 讓你用一個 (共通的) primary key 把幾個 .csv 檔合併 (join) 起來。 除了可以指定只顯示其中一些欄位之外, 也可以自行以數學式定義新的 (衍生) 欄位。 還可以用數學式指定過濾條件, 只顯示少部分的列。 訪客所看到的最終表格, 點一下欄位名稱就可以把所有的列按照那個欄位排序。

安裝試用

你必須先安裝/啟用網頁伺服器 -- 例如 apache2。 也請先確認你的網頁已能使用 php。 (例如我在 ubuntu 18.04 底下, 要先 a2enmod php7.2 。) 再把整個 jesp 目錄放到你的網站下, 例如 /var/www/html/jesp/ 然後把瀏覽器指向 http://localhost/jesp/ , 就會看到一個表格。

顯示的表格是台股近年高現金殖利率個股的清單, 也就是 自己的明牌自己撈 的某日靜態網頁版。 關於這個清單的意義與投資風險, 請自行參考該文; 這裡只是拿它來作為 jesp 的使用範例而已。

設定檔

上述網址的完整版應該是 http://localhost/jesp/?c=config.json 表示從 config.json 讀取設定檔。 當你省略 c=... 時, jesp 的 index.php 會自動以同一目錄下的 config.json 作為設定檔。 這可以是一個相對路徑, 甚至可以是一個網址。

設定檔中的 csvfiles 陣列列出所有 csv 檔的檔名或網址; pkey 指定 (它們共同的) 主鍵 (primary key) 的名稱。 每個 csv 檔的第一列必須是欄位名稱; 每個 csv 檔內都必須包含這個主鍵欄位。 在這個範例當中有兩個 csv 檔: 181123.csv 是某日台股所有個股收盤價; div.csv 則是台股所有個股歷年現金股利表。 而它們共同的主鍵則是 「代號」, 例如代表台積電的 2330。

程式會去讀取每個 csv 檔, 並且用這個主鍵把所有的表格 join 在一起。 如果資料表內的主鍵值是數字, 就必須用 keyprefix 指定一個字串加到每一列的主鍵前面讓它變成字串。 例如 2330 就會變成 s2330。 因為 php 不會分辨整數 2330 跟字串 "2330", 因此當這樣長像的數字/字串被拿來當成陣列註標時, 會發生問題。 keyprefix 的目的就是要強制把它變成字串。

資料表當中若有文字欄位, 必須把欄位名稱列在textcols 陣列當中; 其餘欄位一律被當成數字處理。

想要顯示在網頁上的欄位請按照順序列在 col 陣列當中。 每一個欄位可以包含以下資訊:

  1. name : 在 csv 檔裡面以及在網頁上所顯示的欄位名稱。
  2. format : 顯示資料/數值時採用的 printf 格式化字串。
  3. var : 在運算式 (下詳) 裡面, 這個欄位的代號。 有點像是幫它取一個變數名稱的意思。 僅限用於從 csv 檔中讀進來的既有欄位。
  4. expr : 運算式 (下詳)。 僅限用於新建立的衍生欄位。

想要顯示既有的欄位, 只需要填寫 name 即可, 其他可省略。 同一個欄位可以重複出現兩次, 例如範例當中的 「名稱」。

也可以用 expr 定義新的欄位, 它的數值由既有欄位算出, 例如範例中的

    {
      "name": "今殖率",
      "expr": "y18/price*100",
      "format": "%.1f"
    },

這會在網頁上新增一個 「今殖率」 欄位, 它的值是從 「y18/收盤價*100」 算出來的, 其中的 「price」 就是 「收盤價」 欄位的變數名稱。 新欄位不可以引用彼此, 只能引用既有的欄位。 使用者自訂的新欄位的 var 只在 keep 設定 (下詳) 當中有意義。

最後, 在 json 設定檔裡的 keep 可以指定依據某些條件只保留部分的資料列。 例如: "keep": "dy_past>6" 表示只保留 「歷殖率」 大於 6 的資料列。 這裡還可以用 php 語法的 && 及 || 等等撰寫邏輯條件。

  1. 頁面操作: 點選欄位名稱, 可以令資料依據該欄由大到小排列。 再點一次, 改成由小到大排列。 若希望採用預設的 「點一次先由小到大、 點第二次由大到小」, 可修改 jesp.js 的設定, 刪掉 orderSequence 那一段。
  2. 數值欄位當中若出現 nan, 整列資料會被略過。 資料若有欠欄位, 也會被略過。 這個問題以後再改進。
  3. 撰寫 exprkeep 的運算式時, 有哪些內建數學函數可用? 請見 Expression.php 。 這外掛套件的目的是為了避免 eval 的資安危害。 我略修改其程式碼, 讓 ?: 三元運算子可用。
  4. 本程式省略各種錯誤檢查。 即使只是設定檔寫錯, 也有可能讓畫面完全不見。 使用者有可能經常需要 tail -f /var/log/apache2/error.log 以及 在瀏覽器裡打開 console 來自行除錯。 程式碼說明: 處處訝異的怪怪語言 phpDataTables 的固定表頭、 排名、 置中