cgictrl-0.4(CGI framework for Ruby)

検索用語を入力 検索フォームを送信

Japanese

Copyright (C) 2009 Masahiko Ito

These programs is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

These programs is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with these programs; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Mail suggestions and bug reports for these programs to "Masahiko Ito" <m-ito@myh.no-ip.org>

Download

• cgictrl-0.4.tar.gz 2012.12.19
• cgictrl-0.3.tar.gz 2012.12.18
• cgictrl-0.2.tar.gz 2012.12.17
• cgictrl-0.1.tar.gz 2009.07.07

What's this ?

Feature

Executing cgi program is selected by transaction code. and cgi program indicate next transaction code to continue conversation process.

Basically, one cgi program send only one kind of view, and process input data from only this view.

cgi program put/get internal data into/from special area called SPA(Scratch Pad Area) in server. SPA is allocated uniquely per session by cgictrl.

Features are ...

• Easy MVC(Model-View-Control) model.
  • Model : cgi program that you deverop.
  • View : User interface is from html like definition file which is independent from Model and out_html() method which is called from Model.
  • Control : cgictrl.cgi(+ cgictrl_common.rb) gets input data from View, and decide to call which Model.
• Session control
  <input type="hidden" ...> passes session id to cgictrl, and cgictrl control session by this session id.
• Exclusive control
  Cgictrl do exclusive control by resource id which is defined with relation to transaction code. you don't need to care about exclusive control in your cgi program.
• Data link by SPA
  SPA area is created uniquely per session in server. you can use SPA to get/put internal data between cgi programs.
• Logging about input data from view
  Input data from <form> is logged into log file.
• Logging about view data
  Output data on view is logged into log file.
• Transaction control by http's authentication(Basic authentication etc), and logging about transaction deny.
  You can define permit transaction code by regex for user.
• Force to connect by https(ssl).
• View edit
  You make view skelton file(html-like), and edit/output skelton by using out_html() method. out_html() method do html-escape, so you protect cgi program from XSS atack easily.
• Converting character code
  You can convert charcter code to use nkf(Network Kanji Filter) module in ruby.

How to install

• Extract package into anywhere you want under public_html.
• Make data directory for cgictrl. You can define this directory by setting param @cgictrl_data_dir in cgictrl_common.cgi.
  • tar xvzf cgictrl-0.4.tar.gz
  • mkdir ~/cgictrl
  • mkdir ~/cgictrl/html
  • mkdir ~/cgictrl/lock
  • mkdir ~/cgictrl/log
  • mkdir ~/cgictrl/spa
  • chmod ???? ~/cgictrl ~/cgictrl/html You must apply permission that httpd can read.
  • chmod ???? ~/cgictrl/lock ~/cgictrl/log ~/cgictrl/spa You must apply permission that httpd can read/write.
  • cp cgictrl-0.4/cgi-bin/* ~/public_html/cgi-bin/
  • cp cgictrl-0.4/cgictrl/*.txt ~/cgictrl/
  • cp cgictrl-0.4/cgictrl/html/* ~/cgictrl/html/

How to use

Setting files

• ~/cgictrl/resource.txt : You must define data resource which cgi program control exclusive for.
• ~/cgictrl/tran2pgm.txt : You must define cgi program which relation to transaction code and resource id which cgi program control exclusive for.
• ~/cgictrl/usertran.txt : You must define permit transaction for user.
• ~/cgictrl/html/*.html : View define by html-like file.

cgictrl.cgi(Cgi Control Program)

• cgictrl.cgi : <form action="..."> invoke only cgictrl.cgi. user cgi program is not invoked from <form action="...">. cgictrl.cgi invoke user cgi program.
• cgictrl_common.cgi : cgictrl class for ruby.

~/cgictrl/resource.txt setting

  ex. RES1=/home/m-ito/dat/database.txt

Special resource

`LOGFILE' means logging file. default value is defined in cgictrl_common.rb. If you don't know what you are doing, you should not change `LOGFILE'.

`SPADIR' means directory which include SPA. default value is defined in cgictrl_common.rb. If you don't know what you are doing, you should not change `SPADIR'.

~/cgictrl/tran2pgm.txt setting

  ex. SAMPLE1=/home/m-ito/public_html/RubyFrameWork/cgi-bin/sample1.cgi:RES1/A,RES2/G,RES3/A

Access mode is only comment now. Access mode is always fixed to `A'. In the future, you can select following as access mode.

• A : Update mode
• G : Read mode

~/cgictrl/usertran.txt setting

  ex. m-ito=TEST|SAMP_.*

If cgictrl is not configed to use httpd's authentication, user id is setted to `anonymous'. so you can define permit transaction for `anonymous'.

Some default values in cgictrl_common.cgi

Default value which must be changed

• Data directory for cgictrl
  @cgictrl_data_dir = "/home/m-ito/cgictrl"

Default values which may be changed

• No force to use https(ssl)
  @force_https = "n"
• Deny to continue from page which return to by Backward button.
  @backward_deny = "y"
• param for nkf
  @default_nkf_param = "-W -X -Z1 -w"
• log input data from <form>.
  @get_log_input_flag = "y"
• log output data to stdout.
  @get_log_send_flag = "y"
• log denial to execute transaction.
  @get_log_deny_flag = "y"
• log critical error which abort transaction.
  @get_log_error_flag = "y"
• exclusive retry interval(sec).
  @lock_sleep_sec = 1
• exclusive retry max count
  @lock_retry_max = 60
• life time for SPA(sec)
  @sweep_time_before = 2 * 24 * 60 * 60

Default values which sould keep default value.

• transaction to cgi program translation table
  @tran2pgm_file = @cgictrl_data_dir + "/" + "tran2pgm.txt"
• permit transaction to user table
  @usertran_file = @cgictrl_data_dir + "/" + "usertran.txt"
• resource table
  @resource_file = @cgictrl_data_dir + "/" + "resource.txt"
• directory for view file
  @html_dir = @cgictrl_data_dir + "/" + "html"
• file id of system error view file.
  @error_msg_id = "cgictrl_error"
• message name in system error view file.
  @error_msg_string = "error_message"
• parent directory for exclusive control
  @lock_parent_dir = @cgictrl_data_dir + "/" + "lock"
• format string of directory name for exclusive control.
  @lock_dir_format = "%s.dir"
• exclusive lock file name.
  @lock_file = "lock.txt"
• start string variable of item to replace, end string variable of item to replace in view file.
  @html_start_param = "START"
  @html_end_param = "END"
• start strint of item to replace, end string of item to replace in view file.
  @html_start_default = "@\{"
  @html_end_default = "\}@"
• internal start string of item to replace, internal end string variable of item to replace in view file(HEX).
  @start_str_hex = "01"
  @end_str_hex = "02"
• resources for logging.
  @log_file_res = "LOGFILE"
  @log_dir = @cgictrl_data_dir + "/" + "log"
  @log_file = @log_dir + "/" + "log.txt"
• resources for SPA(Scratch Pad Area)
  @spa_dir_res = "SPADIR"
  @spa_dir = @cgictrl_data_dir + "/" + "spa"

How to invoke

  ex. http://foo.org/cgi-bin/cgictrl.cgi?SYS_init_tran=TRANSACTION_CODE

How to create view file.

Differential from ordinary html file is

• note http protocol header.

      ex. Content-Type: text/html; charset=utf-8
    

• You must note following input tag between <form> and </form> for setting sessionid. You should not use <input type="hidden" ...> except following tag. You can pass internal data from transaction to transaction.

      <input type="hidden" name="SYS_sessionid" value="@{SYS_sessionid}@">
    

• String to replace in view file
  @{ITEM_NAME}@ or @{ITEM_NAME=DEFAULT_VALUE}@

  You can replace @{...}@ by out_html() method. If you don't call out_html(), @{...}@ will be replaced to empty string in first pattern and be replaced to DEFAULT_VALUE in second pattern.

• `START=STRING' at start of line change `@{' to STRING and `END=STRING' at start of line change `}@' to STRING. If special character is in STRING, character must be escaped by `\'. Default definition is following.

          START=@\{
          END=\}@
    

• If you want to use string in `START' or `END' in html sentence, you must use &foo; or #bar;.

User cgi program

  #--- user coding start ---
  #--- user coding end   ---
  

• sub_open()
  This is called at first of cgi program. you can put coding to initialize something(DB connection, your own exclusive control etc).
• sub_send()
  You can edit and output view by using data from SPA. cgictrl select this sub_send() or following sub_receive() and call it. you should return next transaction code at end of sub_send(). Usually own transaction code is returned.
• sub_receive()
  You get input data from view and process it. you should store data into SPA for next transaction. you must not use `SYS_' for top of SPA item name. because `SYS_' is used for internal purpose by cgictrl. cgictrl select this sub_receive() or above sub_send() and call it. you should return next transaction code according to result of processing data.
• sub_close()
  This is called at end of cgi program. you can put coding to teminate something (DB disconnect, your own exclusive control etc).

Method which is defined in Cgictrl class for user.

• start(nkf_param)

       client starting process.
  
       arg    : nkf_param ... parameter for nkf module(Network Kanji Filter)
       return : session id
      

• end(tran)

       client terminating process.
  
       arg    : tran ... next transaction to execute
       return : none
      

• is_send()

       get condition to call sub_send().
  
       arg    : none
       return : true  ... this is transaction which must send view
                false ... this is not transaction which must send view
      

• is_receive()

       get condition to call sub_receive()
  
       arg    : none
       return : true  ... this is transaction which must receive data
                false ... this is not transaction which must receive data
      

• get_realres(res)

       get real resource.
  
       arg    : res ... resource id
       return : string which show real resource
      

• get_input(key)

       get input data from view.
  
       arg    : key   ... item name
       return : value(string)
      

• set_input(key, value)

       set input data.
  
       arg    : key   ... item name
                value ... value
       return : none
      

• get_input_file(key)

       get input file from view.
  
       arg    : key   ... item name
       return : value
      

• set_input_file(key, value)

       set input file.
  
       arg    : key   ... item name
                value ... value
       return : none
      

• get_spa(key)

       get SPA data.
  
       arg    : key   ... item name
       return : value(string)
      

• set_spa(key, value)

       set SPA data.
  
       arg    : key   ... item name
                value ... value
       return : none
      

• clear_spa()

       clear SPA except item start with `SYS_'.
  
       arg    : none
       return : none
      

• destroy_spa()

       destory SPA.
  
       arg    : none
       return : none
      

• out_html(id, hash_param)

       output view.
  
       arg    : id         ... view file id
                hash_param ... { ITEM => VALUE, ... }
       return : true  ... success
                false ... failure
  
         if hash_param == { "key" => "value" }
            `@{key}@' will be replaced to `value' in `#{id}.html'
      

Sample

• calculate area of circular and volume of ball
• samp_calc_entry_e.{html|cgi}(entry view definition and entry cgi source)
• samp_calc_result_e.{html|cgi}(result view definition and resurl cgi source)

Epilogue