OSSWEB(n) 2.0 "OSSWEB Framework"

NAME

OSSWEB - Framework for developers

TABLE OF CONTENTS

    TABLE OF CONTENTS
    DESCRIPTION
    History
    Why Naviserver?
    Concepts
        Components
        Security Model
        Page Templates
        Request Routing
        Database Access
        SQL Query Abstraction
    Installing OSSWEB
        PostgresQL Installation
        OSSWEB Installation
        Development Mode
    Tutorial: First Application
        Database Model
        Albums List
        Creating Albums
        Updating Albums
        Uploading Photos
    OSSWEB API
        Namespace Hierarchy
        Core Procs
        Cache Procs
        Type Validation Procs
        Conversion Procs
        Connection Procs
        Database Procs
        SQL Support Procs
        Forms and Widget Procs
        HTML Procs
        Template Procs
        Custom Tags
        File Storage Procs
        Utility Procs
        Scheduling Procs
        Admin Procs
        Lookup Procs
    COPYRIGHT

DESCRIPTION

Web development framework based on Tcl language and Naviserver application server.

History

Why another Web application framework, how many exist already, can't you just pick one and use it? This is a good question and as i see how many frameworks exist today, not an easy one. Back at 2000 when i was building high performance http proxy, i needed small scripting language to embed into my server. At that time i liked Python and did all scripting tasks using it but the server i was working on had to be multi-threaded and Python did not support threads very well. It has one master lock which allows only one thread to execute Python code, so multiple interpreters in one address space will be serialize one after another which gives not very good performance if you need to serve hundreds or thousands requests. Perl i never liked, PHP was for Apache only, the only 2 languages i found were Lua and Tcl. For some reason i do not remember now i chose Tcl. It was very easy to embed, C API is very well documented and simple. So in no time my proxy server was able to call small scripts in multiple threads and it gave a lot of additional functionality because some things were much easier to cod ein scripting language than in C.

Then another big project came in and i had to choose Web application platform but the trick was, it was supposed to be really big system, and Web was only part of it. The system had to support job scheduling, different communication protocols, background tasks, different databases and other non-Web related stuff and at the same time it should be accessible and configured only through Web interface. I forgot to mention that open-source tools were preferable and we were not Microsoft shop, but we had some software running on Windows we needed to connect to. Having experience with Apache, PHP and Java i was still looking when i found at that time active web site of the company called ArsDigita. The forums on that site were so interesting and useful so i digged up deeper and found execelent book by Philip Greenspun, Philip and Alex's Guide to Web Publishing available at http://philip.greenspun.com/panda/. I used Tcl by that time, so i was basically hooked. I installed AOLserver and started playing with it to see if this is what i need for my new project. It turned out that combination of AOLserver and some parts of ArsDigita open-source software called ACS were almost perfectly fit but what was more important, the platform was giving almost unlimited posibilities as in Web space and also in other backend or server architecture related domains. The AOLserver's API, Tcl and C was so powerfull and rich, extending it was so easy, after almost 2 years of development and maintaining the whole system was built just using AOLServer, Tcl. C was used only for specific modules like SNMP, ICMP protocols, database driver and other low-level stuff. During the development, the system grew from pieces of former ACS system into completely different Web application framework with its own security model, API and data model. By the time ArsDigita disappeared we no longer actually needed it because we were completely independent from any outside companies, all tools we used were open-sourced.

Why Naviserver?

We were using AOLserver since 2001, started with version 3.3. After several years i collected a bunch of patches and modules that i was trying to keep up-to-date with new versions of AOLserver. I tried to submit my patches, some have been accepted, some not but after some time it was obvious that AOLserver is intended to be Web server only while i wanted it to be more versatile application platform where Web is just one of the features. I wanted the server to supported different protocols, not just HTTP, more flexible API, more modules and functions. I am not saying i was right and others were wrong, but i saw the potential of the server to be much bigger than just a Web server and not embracing it was very frustrating for me. So, Naviserver was born as a fork of AOLserver version 4.0.10. Since then a lot of stuff have been added and changed in Naviserver that those two servers cannot be simply switched, Naviserver has much larger API set which is not available in AOLserver.

So, enough history and explanations, let's get closer to the OSSWEB/Naviserver framework and how they are bound to each other.

Concepts

Components

Let's start from the lowest level up to the top. The programming language is Tcl. Arguably it is not the best language but it is very old and still being actively developed, it is very stable, supports threads natively, has good library of useful applications and modules. And it is so simple it is nothing to learn actually, there is no syntax, but the specific syntax can be built using Tcl and we are using this feature. Created as a glue language it actually grew up into general purpose programming language. It is not popular as Java, Perl, Python or Ruby but still has large community and used in many applications. On other hand, popularity never bothered me much, if i like the language, it does the job i do not care how many people using it and i am not going to switch just because it does not make headlines anymore. So, next level is Naviserver, Tcl is embedded into it very deeply, the language is part of the core, that's why Naviserver is very high performance server even with scripting language, there is no overhead, Tcl interpreters are used when they are needed, then they are put back into the pools of availabld interpreters, so other threads can re-use existing interpreter at any time. Also, Tcl in Naviserver is the developement language, more than 200 Tcl functions are available for a developer ranging from accessing internal server state to inter-thread communications and Web page filters.

The biggest difference between Naviserver and other Web server like Apache or lighttpd or other pure Web server that it is capable of not just serving Web page but provide complete server infrastructure that can be used to build more complex server applications. For example, if some actions needs to be run every once in a while, there is internal scheduler than can run Tcl scripts the same way as cron does. Every script can access database using the same API, all additional library functions are available to every thread the same way as system calls from glibc are avaialbel to all user programs. Socket callbacks and client functions, access to file system and database, local cache with expiration for any kind of data, shared variables with automatic locking and more can be used to develop backend applications in addition to Web applications.

So, let's start with describing how Naviserver processes HTTP request. There are many ways to build request processors, i will describe how OSSWEB framework does it. Naviserver is getting much better documentation now, so many answers on specific programming issues can be found there.

Naviserver's HTTP driver is listening for example on port 80. It can accept and process multiple connections at once, it uses async I/O, therefore is able to accept and process many connections without spawning threads. Once a connection is accepted and HTTP request line and headers are read and parsed, driver passes this request structure to first available connection thread. There are can be different thread pools defined with minimum and maximum parameters, which prevents from overloadig the system with too many threads and at the same time keeps some number of idle threads ready to process new requests. That connection thread will be responsible now what to do with the request and for returning valid HTTP response, driver thread will continue to accept new connections and reading HTTP requests from other sockets.

In Naviserver there are different methods how to serve HTTP requests:

• register Tcl proc for particular methdod and URL
  
  
• register filter for particular method or URL
  
  
• let the server resolve request URL into file and serve static file back to the browser (this method is always registered and is called at the end if nobody handled request)

The difference between registered Tcl proc and filter is that once the Tcl proc is executed and finished, the connection is closed, it is responsibility of that Tcl proc to provide valid HTTP response.

The registerted filter works same way as Tcl proc but there can be multiple filters registered for the same method or URL and each filter can decide if the processing stops here or next filter can continue processing the request. The filters give more flexibility, there are several stages when different set of filters are called during request processing, those stages called preauth, postauth and trace which means during processing of any request the server calls

1. preauth filters first,
   
   
2. if no errors, it performs HTTP authorization if exists, usually everybody uses cookies nowadays, so basic HTTP authorization is rare,
   
   
3. then the server calls postauth filters, once the connection is closed, all trace filters are called.

The execution chain looks like this:

1. accept socket
   
   
2. read headers
   
   
3. queue
   
   
4. preauth filters
   
   
5. basic authorization if required
   
   
6. postauth filters
   
   
7. Tcl proc if registered
   
   
8. close conection
   
   
9. trace filters

To show this in action there are two examples how to register Tcl handlers in Naviserver:

ns_register_proc GET /*.oss template_handler ns_register_filter preauth GET /* security_handler ns_register_filter postauth GET *.oss template_handler

Second command registers security handler to be called first for all requests. Third command registers template handler. Security filter can return stop return code that will tell the server not to call any further filters otherwise server will match next filter and execute it, if processing is till enabled the server will continue until all matched filters are called.

OSSWEB uses those features to install its own filters for security and template processing, security filter is registered as preauth, so it is called early as the first filter, then if request processing continues, template filter can be called if required.

Security Model

Security filter can be registered for particular url patterns or as global filter for the whole site. It performs session support, user authentication and authorization. If session is not valid, user is redirected automatically to login page. If session is valid, security filter passes control to other filters or procs so it behaves completely transparent to the application. It even can be disabled completely in case of public site, but one nice feature it supports is public sessions, for every new connection it creates new session and assignes cookies so you can track the same user if you need it.

When HTTP request comes the only information we have is request line with query parameters and/or cookies.

These are examples of HTTP requests:

GET /index.html HTTP/1.0 GET /MyObjects/MyPortal.oss?account_id=123

Is it possible to create security layer that will serve security part and will be almost independent from application itself?

The reason many applications have it own security implementation because their security implementation too tightly bound to application logic. Why not to define security functions, put it into separate API and implement it as much independently from language or Web server as possible.

In this case application is the client to security sybsystem and should accept some rules or restrictions that this security subsytem introduces. The idea is not new, this is just slightly different approach for building Web application. Instead of creating application logic and then adding access restriction to it we can just use existing security implementation and just use its API. Our security model is based on naming convention for application requests. When you write your code, you should use this convention or API for building links between various parts of the application. Security layer is located between Web server and your application and takes these requests and applies them against it access database. Also we will use SQL database for storing sesison/user related information. All this will provide us with robust security system that can be used for many Web aplications.

The idea is that every request to our secure application web site should be processed through security handler. This handler verifies user credentials and allows request pass or rejects it according to access priviliges this user has in our security database. Actually we have two tasks which are connected, but at the same time separated from each other. First, we need to authenticate user, in other words we have know to who is trying to access our restricted web site. And second, we need to determine the user's access rights to the requested resource. Both these tasks should use the same database, at least they should have access to the same user information. First task can be accomplished by using cookies or native HTTP autentication method. Second task is itself our security model implementation.

For every request that matches this pattern the security handler is called and verifies request path, parameters and/or cookies. It tries to check these against security permissions that are stored in database for each particular user or group of users.

Our users and sessions tables look like this, not all columns are shown here for brievity:

TABLE ossweb_users user_id INTEGER user_name VARCHAR password VARCHAR salt VARCHAR salt2 VARCHAR TABLE ossweb_user_sessions user_id INTEGER session_id VARCHAR ipaddr VARCHAR login_time TIMESTAMP access_time TIMESTAMP

• user_id will contain unique identifier for each user.
  
  
• user_name will contain name a user will use in order to login into the system. password will contain encrypted user password.
  
  
• salt is special column which will be used for password generation and verification.
  
  
• session_id will contain unique id which identifies each user session. This is different from user_id, because session identifier will be different for any session even for the same user. It will be used for tracking and autorization user interaction with secure application.
  
  
• login_time will contain date and time a user last successful logon into the system.
  
  
• access_time will contain date and time of last user request for current session. This information will used in trackin and expiring user sessions after some time of inactivity.
  
  
• ipaddr will contain IP address for current session, it is set during login time, so even if you move browser's cookie file from one computer to another, this will not allow to continue the same session. The server will check IP addres from users table for this session with the IP address of current HTTP request. Because they are different, you will be prompted for login.

And finally we create access permission table which will contain access rights for each user or group. Any user can have many records in this database, we can define as many access record as needed. There is no technical limits, just logic of secuirty for each particular application.

TABLE ossweb_acls acl_id INTEGER obj_id INTEGER obj_type CHAR project_name VARCHAR app_name VARCHAR page_name VARCHAR cmd_name VARCHAR ctx_name VARCHAR value CHAR

• obj_id is a column which contains id from users or groups tables only. In order to achieve this, it is possible to write trigger which will verify that inserted ID is id either users or groups table.
  
  
• obj_type determines type of object that is stored in obj_id column.
  
  
• value contains Y if access is granted to specified in this record application, or refued in case of N. Using N allows us to open access to the whole context and restrict access to specific parts within this context.

Each user will have two cookies:

• user_id - unique permanent ID that identifies user
  
  
• session_id - temporary cookie that specifies particular session for each user_id.

user_id cookie is assigned after a user successfully logged in into the system. It is unique identifier which is primary key in the 'ossweb_users' table. We can keep this cookie for a long time in the browser, because the same user always uses the same user_id. It is useful for example for public sites or public open part of secured sites. You can show some specific customized information for this particular user, like it is done on many Web portals. When a user provides his/her user name and password, we just look into the table and try to find record with provided user name. In case of success we verify provided password with existing one from database. We keep passwords encrypted in the database using SHA1 digest encryption algorithms. So for verification we have to calculate digest from provided user password with the salt which is kept in the database. This salt is just some randomly calculated string, the more unique the salt is the more secure the system and the more difficult it to break. Resulting encrypted string should be the same as the encrypted password.

To store a password we do:

• set salt with unique generated string
  
  
• create encrypted password with result from SHA1(password,salt)
  
  
• store encrypted password and the salt into the table
  
  
• create salt2 by encrypting them using SHA1(user,password). We keep salt2 for cases when login page supports SHA1 Javascript encryption, in this case on the login page, when user provided name and password, Javascript will encrypt them using SHA1 and will send that encrypted digest to OSSWEB server, which will compare it to salt2 column. they will match only if user provided correct name and passoword and at the same time even without using SSL this method will never send clear text password over the Internet.

• find user in the database
  
  
• create encrypted password by calling SHA1(password,salt)
  
  
• compare encrypted password with the value of password column If the password is correct, we generate unique session Id for this user, store it into the table and user's browser cookie and let this user in into the system. Also, if encrypted token was send instead of clear text username and password, just compare it with sal2.

• project
  
  
• application
  
  
• page
  
  
• command
  
  
• context

/project_name/app_name/page_name.oss[?cmd=command[.context]] or /project_name/app_name/page_name.oss[?cmd=command][&ctx=context]

• project_name is the directory, where all applications for this project are located.
  
  
• app_name is the directory where all pages for this application is located. Applications may be registered in the database. In this case security filter will refuse any requests with invalid/unknown application.
  
  
• page_name is any application-specific meaningful part of the application logic. We can register all possible pages within an application or allow security admin to enter any pages in permission database. In general it is a web page name: file name with html or dynamic server parsed page. It even can be virtual dynamic page whereby its contents are generated on the fly by web server.
  
  
• cmd is optional command within current page, more like some specific operation or action. Commmand may consist from two parts, command name itself and command execution context. This context defines additional logic layer inside current command operation. This is usefull when complex application context has the same command for more than one object within this is context. For example, command 'Move' may be applied to files, directories, documents and urls within one repository context.
  
  
• ctx is command context in different form, as a query parameter. It is used so for convenience, because sometimes for example in submit buttons there is impossible to use names that look like 'update.order' or 'update.account'. It is better to use command name as 'Update' and set command context using hidden form field.

/demo/knowledgebase/file.oss /demo/knowledgebase/edit.oss /demo/knowledgebase/file.app?cmd=move /demo/order/search.oss /demo/order/account.oss?cmd=show /demo/order/account.oss?cmd=add.service /demo/order/account.oss?cmd=add&ctx=package

After we parsed request, OSSWEB will scan access database. Database access table 'ossweb_acls' contains all 5 tokens as columns. Each column may contain actual value or *, which means 'everything'.

All records are sorted in a such way, that more specific rows are always at the top and more generic at the bottom.

We retrieve permissions from 'ossweb_acls' table for the specified user and all gropus this user belongs to. Sorting this way allows us to use the first match because more specific matches are always ahead of more generic ones. We do not need to scan all records every time. Because it is possible to check access permissions inside application, we load all permissions into memory and call special routine that will scan this list for the match. This way we do not need to call SQL database every time we want to verify access to some parts of our application.

For example our user has access to 2 projects, 'portal' and 'doc'. Within project he has access to application called main. Within this application he can execute 'view' and 'search' for any pages. The page with user preferences 'prefs' can be updated by this user and any commands except 'delete' can be executed in the page 'apps'.

obj_id | obj_type | project_name | app_name | page_name | cmd_name | ctx_name | value -----+----------+--------------+----------+-------------+----------+-------------+------- 0 | G | portal | main | apps | delete | link | Y 0 | G | portal | main | apps | delete | * | N 0 | G | portal | main | prefs | update | * | Y 0 | G | portal | main | * | search | * | Y 0 | G | portal | main | * | view | * | Y 0 | G | doc | * | * | view | * | Y 0 | G | portal | main | * | * | * | Y 0 | G | unknown | * | * | * | * | N

The last line in the list will make OSSWEB to deny all unknown requests regardless of the format, because by default all all security elements set to unknown and only command is set to view, it is very easy to define any kind fo filter that will restrict access to Web applications.

OSSWEB has Web administrative interface that allows to create security permissions per user or user group.

Page Templates

Now, when our session is authenticated and we got the green light to proceed to the application, OSSWEB core engine will try to route the request to the application page. As i said above, there are multiple way to create application pages but we start with simplest way, projects are directories, applications are directories inside the projects and application pages are .adp and .tcl files inside the application directories. Thus, the request

/demo/hello/world.oss?cmd=view

All page directories and files are located under Naviserver pageroot which is /usr/local/ns/pages according to supplied with OSSWEB config file. To install OSSWEB if it is not isntalled yet, refer to README file in the OSSWEB distribution.

To create example page we should create project and aplication directories and world.adp file:

mkdir -p /usr/local/ns/pages/demo/hello cd /usr/local/ns/pages/demo/hello

<BODY> Hello World </BODY>

http://localhost:8080/demo/hello/world.oss

File world.adp

<BODY> Hello World, current time is @current_time@ </BODY>

set current_time [ns_fmttime [ns_time]]

Simply put, in OSSWEB templating system .tcl file prepares the data to be shown on the page and .adp file formats and presents that data to the user.

Let's show one more example, we add page counter to hello world application to show how many time this page was shown. No database will be used, we keep the counter value in memory.

Just add one more command to world.tcl file File world.tcl

set current_time [ns_fmttime [ns_time]] set counter [nsv_incr HellowWorld PageCounter]

<BODY> Hello World, current time is @current_time@, page is shown @counter@ times </BODY>

Let's show how processing logic can be used inside templates. We will show greeting depending on time of day in our previous example. We will use OSSWEB registered tags. File world.tcl

set current_time [ns_fmttime [ns_time]] set hour [ns_fmttime [ns_time] "%H"] set counter [nsv_incr HellowWorld PageCounter]

<BODY> Good <case> <when @hour@ gt 11> Afternoon <when @hour@ gt 18> Evening <else> Morning </case> <P> Hello World, current time is @current_time@, page is shown @counter@ times <P> <ossweb::link -text Refresh> </BODY>

Another useful feature to show data from the database on the page, there are several methods how to do this:

• Show Tcl list
  
  If we need to format Tcl list we can use <list> tag:

  In .tcl file: set list { one two three } In .adp file: <OL> <list name=list> <LI> @list:item@ </list> </OL>

  
  
  
• Show Tcl list as DB row
  
  We can retrieve a row from database and store it in Tcl list, each list item will represent separate row as Tcl list:

  In .tcl file: set row [ossweb::db::multilist "SELECT user_name,user_email FROM ossweb_users"] In .adp file: <OL> <multilist name=row> <LI> @row:1@, @row:2> </multilist> </OL>

  
  
  
• Show DB row
  
  We can retrieve multiple records from database and store them in so-called datasource, which is a collection of Tcl arrays:

  In .tcl file: ossweb::db::multirow rows "SELECT first_name,last_name,user_email FROM ossweb_ursers" -eval { set row(full_name) "$row(first_name) $row(last_name)" } In .adp file: <multirow name=rows> @rows.full_name@ <if @row.user_email@ ne ""> Email: @rows.user_email@ </if> <BR> </multirow>

  
  
  
• Show DB row in the tag
  
  Show records without any .tcl file

  <foreach name=row query="SELECT user_name FROM ossweb_users"> @row.user_name@ </foreach> or <foreach name=row query=sql:ossweb.user.list> @row.user_name@ </foreach>

Request Routing

Once the server found and called our page, it is up to us what to do next. We can retrieve all query parameter using ns_queryget command and perform our logic and return HTTP response back to client. But doing all that over and over again for every page would be tedious and time consuming. OSSWEB offers flexible request routing method that will simplify request processing and minimize amount of code that needs to written.

Because security handler parses and splits request into pre-defined elements, inside the page we know which command was requested. We just need to write so-called callback on that command that will be automatically called. Inside that callback you need to write only what is related to that particular command. In OSSWEB that means every page needs to call ossweb::conn::process command. It accepts list of commands and corresponding callbacks to call, also you can specify where to go after successfull execution of the callback and where to go in case of error. Of course every callback can do routing itself to the next point as well, it is up to you to decide how it is more convenient in this particular application.

Let's show how the code looks like:

# Update record ossweb::conn::callback update {} { ... } # Read record from the DB and show form ossweb::conn::callback edit {} { ... } # View all records ossweb::conn::callback view {} { ... } ossweb::conn::process \ -eval { update { -exec update -next "cmd view" -on_error "cmd edit" } edit { -exec edit -on_error "cmd edit" } default { -exec view } }

The way the "next" statement works, it re-evaluates the same page, i.e. re-executes ossweb::conn::process again with new command. But it re-evaluates itself in the same address space, so all Tcl variables and other objects are available. Deep inside OSSWEB actually does not parse the same Tcl file more than once, after the first time, Tcl code is compiled, wrapped into Tcl proc and cached by the Tcl interpreter, so next time OSSWEB actually just calls the Tcl command, no reading and parsing involved. But OSSWEB monitors the file and if it was modified, it is reloaded and recompiled.

For example let's assume update callback failed with some error, OSSWEB sees the "-on_error" statement, sets system command to "edit" and re-evaluates the page again. Now ossweb::conn::process is called with command edit, so OSSWEB calls callback "edit" which does something, for example shows the form to the user with error message.

If no errors occured in "update" callback, "-next" statement sets command to "view", OSSWEB re-evaluates the page and callback "view" is called which will show all records including just made changes.

Actually, the above form is kind of verbose, another way to do the same is to rely on OSSWEB ability to automatically call callbacks for each command. Only in this case we have to handle errors and routing in every callback.

# Update record ossweb::conn::callback update {} { ... ossweb::conn::next cmd view } # Read record from the DB and show form ossweb::conn::callback edit {} { ... ossweb::conn::next cmd view } # View all records ossweb::conn::callback view {} { } ossweb::conn::process \ -on_error "cmd view"

Also, callbacks "update" and "view" now define what to do after they finish, they call special command ossweb::conn::next which changes execution context and sets new command to "view".

This looks simple but make the code and programming more like writing callbacks and routing between them. Another useful feature is that ossweb::conn::process converts incoming query parameters into local Tcl variables, so ther are accessable in every callback. For security reasons, not all parameters get converted, only those you are interested in.

The format is list of triples: varname type default_value ....

For example:

ossweb::conn::callback view {} { if { $id != "" } { ... } } ossweb::conn::process \ -columns { id int "" name "" "" }

There is possible to keep different command in the different files and route requests flow between pages as well.

This is page update.tcl

# Update record ossweb::conn::callback update {} { ... ossweb::conn::next -page view -cmd view } ossweb::conn::process -on_error "-page view -cmd edit"

set id [ossweb::sql::quote [ns_queryget id]] if { [ossweb::db::multivalue "SELECT * FROM account WHERE id=$id"] } { ossweb::conn::set_msg "Unable to read account record" ossweb::conn::next -cmd error -page index return }

# View all records ossweb::conn::callback view {} { ... } ossweb::conn::process -on_error index

Database Access

OSSWEB provides high level access to databases using native Naviserver database drivers and database API. Naviserver includes drivers for most databases like PostgreSQL, MySQL, Oracle, Informix, Interbase, Sybse, SQL Server, Berkeley DB. OSSWEB supports PostgreSQL only.

In order to access databse, it needs to be configured in the main Naviserver config file, it includes so called database pools, when access to each database has unique name which is used in the applications, never any application uses database username or passwords directly. This makes applications very portable and independent of specific database, just update config file and application will use different database server. Applications just request database handle from the named pool, if no connections to the database yet, Naviserver connects to databse, and returns the handle to the caller. Once application is done, it returns handle back to the pool and any other thread can reuse already opened database handle. This way not too many open connections to database are able to maintain very high number of users or working threads.

OSSWEB does not provide any mapping or object layer on top of SQL access. Database API provides one-to-one mapping between database columns and Tcl variables. Once read from the database program can access values from the SQL tables as Tcl variables. For updates Tcl variables will be used as well for corresponding SQL columns. It is up to the program to set them with appropriate values. There are helper procs that make working with database even more easier and there is object system module otcl that provides dynamic objects similar to Ruby or Python that can be used to build object-oriented layer. In most cases storing and manipulating Tcl variables or arrays with database access is enough.

There are several API calls available for the developer:

• ossweb::db::value sql
  
  This call returns single value, given SQL statement should be SELECT or stored procedure call.

  set date [ossweb::db::value "SELECT NOW()"]

  
  
  
• ossweb::db::list sql
  
  This call returns list of columns from all records that met the given criteria.

  set names [ossweb::db::list "SELECT user_name FROM ossweb_users"] foreach name $names { ns_log notice Column: $name }

  
  
  
• ossweb::db::multivalue arg sql
  
  This call reads specified columns from the given row and stores them in the local Tcl variables with the same names

  if { [ossweb::db::multivalue "SELECT user_id,user_name FROM ossweb_users WHERE user_id=1"] } { error "Record not found" } ns_log Notice User ID : $user_id ns_log Notice User Name : $user_name

  
  
  
• ossweb::db::multilist sql
  
  This call returns a list of all records that met the critwria where each item is a Tcl list with all the specified columns.

  set users [ossweb::db::list "SELECT user_id,user_name FROM ossweb_users"] foreach user $users { foreach { user_id user_name } $user {} ns_log notice User: $user_id $user_name }

  
  
  
• ossweb::db::multirow name sql
  
  This call prepares so-called datasource with given name which then can be used in the template using <multirow> tag. Basically this is a list of records which can be accessed by index and name.

  ossweb::db::multirow users "SELECT user_id,user_name FROM ossweb_users"

  and in .adp template we can easily show the list of users as

  <UL> <multirow name=users> <LI> @users.user_id@ @users.user_name@ </multirow> </OL>

  
  
  
• ossweb::db::multipage sql1 sql2
  
  This call is similar to multirow but uses 2 SQL statements instead of one and provides ability to split many records into pages. First SQL statement receives all primary keys meeting given criteria, second statement just shows one page at a time. Keys are caches, so every time page number is given, the only second SQL statement is called to retrieve records for given page.

  ossweb::db::multipage users \ "SELECT user_id FROM ossweb_users" \ "SELECT user_id,user_name,user_email FROM ossweb_users WHERE user_id IN (CURRENT_PAGE_SET)" \ -page $page ossweb::conn::process -columns { page int 1 }

  First time when called, page is assigned with default value of 1, so datasource users will contain records for tthe first page. Tag <multipage> will generate standard back and forward links with list of all pages. When clicked on page number, it will be passed with query parameters and initialized in Tcl variable page. Subsequent calls to ossweb::db::multipage with the same SQL statements and different page number will use cached list of keys and execute only second statement with CURRENT_PAGE_SET substituted with list of keys for given page.
  
  in .adp template we can show all pages using paginator

  <multipage name=users> <UL> <multirow name=users> <LI> @users.user_id@ @users.user_name@ </multirow> </OL> <multipage name=users>

  
  
  
• ossweb::db::foreach sql script
  
  This call will execute SQL statment and will call given Tcl script for every retrieved record. All column values for each iteration will be assigned to local Tcl variables with the same names.

  ossweb::db::foreach "SELECT user_id,user_name FROM ossweb_users" { ns_log notice $user_id $user_name }

  
  
  
• ossweb::db::exec sql
  
  This call executes DDL statements like UPDATE, INSERT, DELETE and etc. It returns 0 if successful or -1 in case of error.

  if { [ossweb::db::exec "DELETE FROM ossweb_users WHERE user_id=1"] } { error "Unable to delete the record" }

  
  
  
• ossweb::db::insert table args
• ossweb::db::update table keys args
• ossweb::db::delete table keys args
• ossweb::db::read table keys args
• ossweb::db::select table keys args
  
  These calls will execute SQL Insert,Update and Delete commands respectifully. Columns is list of field definitoons in the same format as in ossweb::db::insert_values command. key parameter can be a Tcl list in which case Where condition in update/delete calls will use all specified fields. -columns can be omitted, OSSWEB will read column definitions from the database.

  set msg_name Test set description "Test message" ossweb::db::insert ossweb_msgs # Update record with msg_name=Test with new description Test2 ossweb::db::update ossweb_msgs -columns { description "" Test2 } msg_name Test # Delete record by msg_name=Test and description=Test2 ossweb::db::delete ossweb_msgs msg_name Test description Test2 # Retrieve all records with msg_name=Test set recs [ossweb::db::select ossweb_msgs msg_name Test] # Same as above but store columns in local Tcl variables, # this is equivalent of "SELECT * FROM ossweb_msgs WHERE msg_name='Test'" ossweb::db::read ossweb_msgs msg_name Test

  
  
  
• ossweb::db::begin
• ossweb::db::commit
• ossweb::db::rollback
  
  These calls are used to define transactions. Nested calls are allowed, it will count nesting level and only first begin and last commit/rolback will be actually executed.
  
  
• ossweb::db::rowcount This call returns number of rows processed by last UPDATE or DELETE commands.
  
  
• ossweb::db::filter options
  
  This call is used to construct SQL conditions based on input Tcl variables. This is mostly useful in SELECT statemets that used for searching record based on varibale input from user or other sources.

  ossweb::sql::filter \ { user_id ilist "" user_name Text "" user_email text "" }

  Previous example will return empty string if none of user_id,user_name or user_email variables exists.
  
  Let's say we assign variable user_id with value 1. Now ossweb::sql::filter will return "user_id IN (1)". If we assign Tcl variable user_name with john then we will get the following SQL:
  
  "user_id IN (1) AND user_name ILIKE '%john%'".
  
  If we define user_email with a, then the whole result will be
  
  "user_id IN (1) AND user_name ILIKE '%john%' AND user_email ILIKE 'a%'"
  
  
• ossweb::db::insert_values options
• ossweb::db::update_values options
  
  These calls are used to build SQL statemenst for INSERT and UPDATE commands. They accept list of columns and then check local Tcl variables with same names for values. Columns list tells how any particular value should be encoded in SQL. This is very flexible way of dynamically build SQL statements based on variable input.

  ossweb::db::exec "INSERT INTO ossweb_users [ossweb::sql::insert_values -full t \ { user_id int "" user_name "" "" user_email "" "" status "" active }]" ossweb::db::exec "UPDATE ossweb_users SET [ossweb::sql::update_values -skip_null t \ { user_id int "" user_name "" "" user_email "" "" status "" active }]"

  Previous example will add new user record using local Tcl variables as values. status column if not defined will be assigned with default value of "active". When updating, -skip_null tells that empty or non-existent columns should not be used in UPDATE statement, thus allowing to update only changed columns.

SQL Query Abstraction

Sometimes application may do similar tasks or similar database actions in different places. Duplicating the same SQL statements and in case of minor change going through all source code may be not fun to do. OSSWEB offers flexible solution, it is called SQL query abstraction.

In every place where SQL statement is expected, mostly in database API calls, instead of pure SQL code it is possible to use SQL ids. Those ids are uniquely identify SQL statements and used similar to procedure or API calls. It is stored in .xql files using very simple XML format with given query id, then applications can refer to that id and execute SQL statement as they are given them directly. But, one feature that makes it even more flexible and usefull, those stored statements can containt Tcl code and refer to Tcl variables, before passing to database for execution, that XQL definition will be processed by Tcl or better say to executed by Tcl and the resulting SQL statement will be passed to the database for execution.

Let's see this in example, we will use SQL statements from previous section. We create users.xql file and put there all our SQL statements.

<query name="ossweb.user.list"> <description> List of all users </description> <sql> SELECT user_id,user_name,user_email FROM ossweb_users </sql> </query>

Now we take previos example they will look like this:

ossweb::db::multirow users sql:ossweb.user.list set users [ossweb::db::list sql:ossweb.user.list] foreach user $users { foreach { user_id user_name } $user {} ns_log notice User: $user_id $user_name } ossweb::db::foreach sql:ossweb.user.list { ns_log notice $user_id $user_name }

Also it is worth to mention that if i need to change that SQL and make it globally that users with status 'disabled' should not appear anywhere i just go and change one particular XQL file and query.

<query name="ossweb.user.list"> <description> List of all users </description> <sql> SELECT user_id,user_name,user_email FROM ossweb_users WHERE status <> 'disabled' </sql> </query>

Another area where .xql files are useful is to make conditional SQL statements. Let's assume that we want to use only this SQL statement to all access to ossweb_users table. But we have search page which may take input of how somebody wants to locate particular user, let's say by user_name or/and by user_email. XQL definition allows to embed Tcl directly into SQL query and also allows to define required Tcl variables with default values.

<query name="ossweb.user.list"> <description> List of all users </description> <sql> SELECT user_id,user_name,user_email FROM ossweb_users WHERE status <> 'disabled' [ossweb::sql::filter \ { user_id ilist "" user_name Text "" user_email Text "" } \ -before AND] </sql> </query>

Installing OSSWEB

PostgresQL Installation

PostgreSQL should be installed and running before you do OSSWEB installation. If it is not installed, before installing OSSWEB you need to perform PostgreSQL setup;

make pgsql

OSSWEB Installation

To prepare the environment just download OSSWEB from ftp://ftp.crystalballinc.com/pub/vlad/ossweb.tar.gz.

wget ftp://ftp.crystalballinc.com/pub/vlad/ossweb.tar.gz tar -xzf ossweb.tar.gz cd ossweb

If PostgreSQL was installed manually and is running with your privileges and not as user postgres then:

make world dbuser=`whoami`

make world

/usr/local/ns/bin/nsd -f

Typing http://localhost:8080/ossweb/ will bring OSSWEB login screen, just enter username admin with password admin. It will bring initial OSSWEB admin pages with menu on the left with installed applications.

Development Mode

By default OSSWEB config file enables development mode in which there is no need to restart the server even in case library files are changed. OSSWEB will detect changes to Tcl files and will reload them automatically.

The following parameters define development mode:

1. ns_param server:development t Enable development mode. Also the server searches local direcotory where current page is being served for .xql files. In production mode all .xql files should be put into /usr/local/ns/xql directory but in develpment mode modules can be developed initially in their local folders.
   
   
2. ns_param server:debug t This parameter enables global debug output for incoming requests, nsd.log will contain the complete trace of what is called during every request which makes debugging and tracing much easier.

Tutorial: First Application

To show the whole process how to build applications for OSSWEB, let's create photo album application, from the beginning to complete web site. The application will not be feature complete but pretty functional and useful.

Database Model

We will have 2 tables, albums and photos. albums table will hold list of albums with name and creator, photos will be for keeping list of photes for each album.

CREATE SEQUENCE album_seq; CREATE TABLE album ( album_id INTEGER NOT NULL DEFAULT NEXTVAL('album_seq'), album_name VARCHAR NOT NULL, album_descr VARCHAR NULL, user_id INTEGER NOT NULL DEFAULT 0 REFERENCES ossweb_users(user_id), create_date TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), PRIMARY KEY(album_id) ); CREATE TABLE photo ( album_id INTEGER NOT NULL REFERENCES album(album_id), photo_name VARCHAR NOT NULL, photo_size INTEGER NOT NULL, create_date TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), PRIMARY KEY(album_id,photo_name) );

/usr/bin/psql -U postgres ossweb or /usr/local/pgsql/bin/psql ossweb

For the sake of explanation what we are doing this tutorial will show how to create applications manually.

Albums List

After we created SQL tables we want to create new albums and be able to list, modify and delete them. Let's call our application photo.

mkdir -p /usr/local/ns/pages/photo cd /usr/local/ns/pages/photo

ossweb::conn::callback view {} { ossweb::db::multirow albums "SELECT *,ossweb_user_name(user_id) AS user_name FROM album ORDER BY 1" } ossweb::conn::process \ -default view

<ossweb:header> <BODY> <CENTER><ossweb:msg></CENTER><BR> <ossweb:title>Photo Albums</ossweb:title> <CENTER> <ossweb:link -text "Create New Album" cmd edit> </CENTER> <border style=white> <TR><TH>Album Name</TH><TH>Created</TH><TH>Owner</TH></TR> <multirow name=albums> <TR><TD>@albums.album_name@</TD> <TD>@albums.create_date@</TD> <TD>@albums.user_name@</TD> </TR> </multirow> </border> </BODY> <ossweb:footer>

In album.adp we show datasource albums using <multirow> tag, parameter name specifies which named datasource to use. This tag repeats HTML block for every row in the datasource. Inside that tag, columns refered by their names. Other OSSWEB predefined tags are:

• <ossweb:header> - renders all required javascript, CSS and other necessary files and information.
  
  
• <ossweb:msg> - if during execution error message was set, this tag will show it
  
  
• <ossweb:title> Formats HTML title
  
  
• <border> - creates HTML table with style white, there are more styles for border tag. Page Generator can be used to preview all border formats.
  
  
• <ossweb:footer> - render other internal OSSWEB information which needs to be kept on the page, ussualy header and footer tags are required for proper template rendering, otherwise a lot of things will need to be done manually like including .js and .css files and hidden <div> tags.

Now we can point our browser to http://localhost:8080/photo/album.oss.

Creating Albums

To create new album we need to define form with fields and 2 callbacks, one will be called on form invokation and another on form submittion.

# Retrieve all albums ossweb::conn::callback view {} { ossweb::db::multirow albums "SELECT *,ossweb_user_name(user_id) AS user_name FROM album ORDER BY 1" } # Create new album, fire error on SQL error ossweb::conn::callback create {} { ossweb::db::insert album \ -error t ossweb::conn::set_msg "Album has been created" ossweb::conn::next cmd view } # Nothing yet ossweb::conn::callback edit {} { } # Declare form for album details ossweb::conn::callback create_form_album {} { ossweb::form form_album -title "Album Details" ossweb::widget form_album.album_name -label Name ossweb::widget form_album.album_descr -type textarea -label Description \ -resize \ -cols 50 \ -rows 2 \ -optional ossweb::widget form_album.cmd -type submit -label Create ossweb::widget form_album.back -type button -label Back \ -url "cmd view" } # Request controller, declare Tcl variable album_id, create form form_album # and perform request routing ossweb::conn::process \ -columns { album_id int "" } \ -forms form_album \ -default view

Second argument is a Tcl list with column definitions, for now we have album name and user_id. Column definitions is a list with triples, column name, column type and default value. For each column name ossweb::db::insert will try to see if Tcl variable with such name exists and if so, its value will be used in construction SQL insert statement. Type "" means that column is VARCHAR, so it will be properly quotes and escaped. Next column is user_id, type userid means that value will be assigned with current session's user id. Once SQL statement is built it will be executed and we will return message about successful operation.

-error t flag tells ossweb::db::insert to raise exception in case any SQL runtime error, in this case transaction will be aborted if any and OSSWEB will stop processing callback and by default convention will re-route to command error. In our example we do not handle error command so control will be passed to view command which will show existing album list and <ossweb:msg> tag will render current error condition. Another defaut convention, in case of any form validation error, for example widget album_descr is described as optional but widget album_name is not, which means it is required. If you try to submit form with empty album_name, error condition will happen because form will not be validated, in this case control will be re-routed to command edit.

Callback edit will be called on clicking Create New Album link. Because we do not provide album_id we just show empty form. -forms form_albums clause in ossweb::conn::process tells OSSWEB that we need to prepare form named form_album. By convention, OSSWEB will call create_form_album callabck which should create the form. In out form we create 2 input widgets, name and textarea for description and 2 buttons, one for submit and another for returning back to the list.

Once the form filled, hit the Create button, new album should be created. But before that, we need to update album.adp file as well. Currently it does not know how to handle edit command.

<ossweb:header> <BODY> <CENTER><ossweb:msg></CENTER><BR> <if @ossweb:cmd@ eq edit> <formtemplate id=form_album></formtemplate> <else> <ossweb:title>Photo Albums</ossweb:title> <CENTER> <ossweb:link -text "Create New Album" cmd edit> </CENTER> <border style=white> <TR><TH>Album Name</TH><TH>Created</TH><TH>Owner</TH></TR> <multirow name=albums> <TR><TD>@albums.album_name@</TD> <TD>@albums.create_date@</TD> <TD>@albums.user_name@</TD> </TR> </multirow> </border> </if> </BODY> <ossweb:footer>

Updating Albums

For updating albums we need to be able to click on the existing album, update albums fields and save it back into the database. album.adp template will not change because we do not chnage the layout. New features will be added in the album.tcl.

# Show all albums ossweb::conn::callback view {} { ossweb::db::multirow albums "SELECT *,ossweb_user_name(user_id) AS user_name FROM album ORDER BY 1" -eval { # Convert album_name field into link which points to album edit page set row(album_name) [ossweb::html::link -text $row(album_name) -title $row(album_descr) cmd edit album_id $row(album_id)] } } # Create new album record ossweb::conn::callback create {} { ossweb::db::insert album \ -error t ossweb::conn::set_msg "Album has been created" ossweb::conn::next cmd view } # Update existing album record by album_id ossweb::conn::callback update {} { ossweb::db::update album \ -error t \ album_id $album_id \ user_id $user_id ossweb::conn::set_msg "Album has been updated" ossweb::conn::next cmd view } # Delete existng album record by album_id and user_id ossweb::conn::callback delete {} { ossweb::db::delete album \ -error t \ album_id $album_id \ user_id $user_id ossweb::conn::set_msg "Album has been deleted" ossweb::conn::next cmd view } # Album record details ossweb::conn::callback edit {} { # New record, do nothing if { $album_id == "" } { return } # Read record by album_id if { [ossweb::db::read album album_id] } { error "OSSWEB: Invalid album id $album_id" } # Convert Create label into update command ossweb::widget form_album.cmd -label Update # Add delete button if this is our album if { $user_id == [ossweb::conn user_id] } { ossweb::widget form_album.delete -type button -label Delete \ -confirmtext "Album will be deleted, continue?" \ -url "cmd delete album_id $album_id" } # Update form with values fromTcl variables ossweb::form form_album set_values } # Definition of form for album ossweb::conn::callback create_form_album {} { ossweb::form form_album -title "Album Details" ossweb::widget form_album.album_id -type hidden \ -datatype int \ -optional ossweb::widget form_album.album_name -label Name ossweb::widget form_album.album_descr -type textarea -label Description \ -resize \ -cols 50 \ -rows 2 \ -optional ossweb::widget form_album.cmd -type submit -label Create ossweb::widget form_album.back -type button -label Back \ -url "cmd view" } # Controller that perform rquest processing and routing ossweb::conn::process \ -columns { album_id int "" user_id userid 0 } \ -forms form_album \ -default view

Callback update is similar to create, we just update given record with modified fields. user_id now just integer column, we assign user_id Tcl variable at the beginning with current user id or 0 if not logged in.

Delete callback will delete album by album_id and user_id, that means that i can delete only created by me albums

Callback edit is what handles edit command. If album_id is provided we will try to read the record. In case of wrong id we just fire error message which will be shown on the page using <ossweb:msg> tag. If we was able to locate the record, ossweb::db::read will create local Tcl variables with the same names as column names. In our case we will have album_id, album_name, album_descr, user_id, create_date variables.

Also widget cmd is changed with new label Update, on submit, it will make the command to be update (cmd and ctx parameters always converted into lowercase because they are reserved word and commands are lowercase only). New widget delete is added which will provide ability to delete existing album.

In the form definition we added new hidden widget album_id with datatype integer, this will have the form validate album_id on submitions and will guard against SQL-injection attacks.

The last change worth mentioning is -columns parameter for ossweb::conn::process. It now has 2 items, we added user_id which is described as const. That means it will be assigned once on page invocation. In case if in the url user_id=something will be sent, it will be ignored. [ossweb::conn user_id 0] means return current user id if logged in or 0 as default if no user session currently exists.

Uploading Photos

Now we are ready to upload some pictures into our albums. There are different ways to do this but we will choose simple way with some additional features to show what OSSWEB can do. The GUI will have tabs on top of the album form, default will be album details, then Upload and Photos. In Upload section we will provide several upload buttons to be able to send more than one picture, in the Photos section we will format all photos as thumbnails.

In album.adp file we added tabbed buttons using tag <formtab> and 2 new sections in edit mode. Tcl variable tab will be used for switching between different tabs. When we show photos, we use table with 3 pictures in each row.

We refer to @photos:rowcount@ which is predefined variable created automatically for each multirow datasource. It hods number of records in the record set. If no uploaded pictures, we show message, otherwise HTML table with 3 pictures in the row. For each row, <multirow> tag automatically assigned Tcl variable @photos:rownum@ with current row sequential number starting with 1.

<ossweb:header> <BODY> <CENTER><ossweb:msg></CENTER><BR> <if @ossweb:cmd@ eq edit> <formtab id=form_tab> <case> <when @tab@ eq upload> <formtemplate id=form_upload></formtemplate> <when @tab@ eq photos> <if @photos:rowcount@ nil or @photos:rowcount@ eq 0> There are no uploaded pictures in this album yet. <else> <TABLE BORDER=0 WIDTH=100% > <TR> <multirow name=photos> <TD>@photos.photo_url@<BR> @photos.photo_name@: @photos.photo_size@ </TD> <if @photos:rownum@ not mod 4> </TR><TR> </if> </multirow> </TR> </TABLE> </if> <else> <formtemplate id=form_album></formtemplate> </case> <else> <ossweb:title>Photo Albums</ossweb:title> <CENTER> <ossweb:link -text "Create New Album" cmd edit> </CENTER> <border style=white> <TR><TH>Album Name</TH><TH>Created</TH><TH>Owner</TH></TR> <multirow name=albums> <TR><TD>@albums.album_name@</TD> <TD>@albums.create_date@</TD> <TD>@albums.user_name@</TD> </TR> </multirow> </border> </if> </BODY> <ossweb:footer>

# Read all album records ossweb::conn::callback view {} { ossweb::db::multirow albums "SELECT *,ossweb_user_name(user_id) AS user_name FROM album ORDER BY 1" -eval { # Convert album_name into link that points to album edit page set row(album_name) [ossweb::html::link -text $row(album_name) -title $row(album_descr) cmd edit album_id $row(album_id)] } } # Create new album record, if successfull return to view mode ossweb::conn::callback create {} { ossweb::db::insert album \ -error t ossweb::conn::set_msg "Album has been created" ossweb::conn::next cmd view } # Update existing album record by album_id, if successfull return to view mode ossweb::conn::callback update {} { ossweb::db::update album \ -error t \ album_id $album_id \ user_id $user_id ossweb::conn::set_msg "Album has been updated" ossweb::conn::next cmd view } # Delete existing album by album_id and user_id ossweb::conn::callback delete {} { ossweb::db::delete album \ -error t \ album_id $album_id \ user_id $user_id ossweb::conn::set_msg "Album has been deleted" ossweb::conn::next cmd view } # Save uploaded pictures ossweb::conn::callback upload {} { # Root path where we store images set path [ns_info pageroot]/photo # For all 2 pictire input fields for { set i 1 } { $i <= 5 } { incr i } { # Store uploaded image into our directory set photo_name [ossweb::file::upload file$i -path $path -mode path] # Check if image exists if { $photo_name == "" || ![file exists $path/$photo_name] } { continue } # Save image file size set photo_size [file size $path/$photo_name] # Create new record in photo table ossweb::db::insert photo \ -error t } ossweb::conn::set_msg "Pictures have been uploaded" ossweb::conn::next cmd edit tab upload } # Album details callback ossweb::conn::callback edit {} { # New album, do nothing if { $album_id == "" } { return } # Read album record by album_id if { [ossweb::db::read album album_id] } { error "OSSWEB: Invalid album id $album_id" } # Perform tab-specific actions switch -- $tab { photos { # Retrieve all pictures for given album ossweb::db::read photos -type "multirow photos" album_id $album_id -eval { # Make file size human readable set row(photo_size) [ossweb::util::size $row(photo_size)] # Assign with link to open new window with full picture set row(photo_url) [ossweb::html::link -image /photo/$row(photo_name) -url $row(photo_name) \ -width 150 \ -height 150 \ -window Photo] } } default { # Update album mode, change command to update ossweb::widget form_album.cmd -label Update # If out album, define delete button if { $user_id == [ossweb::conn user_id] } { ossweb::widget form_album.delete -type button -label Delete \ -confirmtext "Album will be deleted, continue?" \ -url "cmd delete album_id $album_id" } # Update form with values fromTcl variables ossweb::form form_album set_values } } } # Form definition for album ossweb::conn::callback create_form_album {} { ossweb::form form_album -title "Album Details" ossweb::widget form_album.album_id -type hidden \ -datatype int \ -optional ossweb::widget form_album.album_name -label Name ossweb::widget form_album.album_descr -type textarea -label Description \ -resize \ -cols 50 \ -rows 2 \ -optional ossweb::widget form_album.cmd -type submit -label Create ossweb::widget form_album.back -type button -label Back \ -url "cmd view" } # Form definition for uploading pictures ossweb::conn::callback create_form_upload {} { ossweb::form form_upload -title "Upload Pictures" ossweb::widget form_upload.album_id -type hidden -datatype int ossweb::widget form_upload.file1 -type file -label Picture1 ossweb::widget form_upload.file2 -type file -label Picture2 \ -optional ossweb::widget form_upload.file3 -type file -label Picture3 \ -optional ossweb::widget form_upload.file4 -type file -label Picture4 \ -optional ossweb::widget form_upload.file5 -type file -label Picture5 \ -optional ossweb::widget form_upload.cmd -type submit -label Upload } # Form definition for tabs ossweb::conn::callback create_form_tab {} { ossweb::form form_tab # For new albums do not show tabs if { $album_id == "" } { return } set url "cmd edit album_id $album_id" ossweb::form form_tab -widgets { { details -type link -label Details -url $url } { upload -type link -label Upload -url $url } { photos -type link -label Photos -url $url } } } # Call request controller, create specified forms, declare variables # and perform request routing depending on command ossweb::conn::process \ -columns { album_id int "" tab "" "" user_id userid 0 } \ -forms { form_album form_tab form_upload } \ -default view

form_tab for is used for generating tabs, there are different styles of tabs in the OSSWEB, for this example we will use default. To try and see how it look, try to set <formtab id=form_tab style=blue> or any other styles from the list: text ebay square oval oval2.

Another form is form_upload, we will use it for uploading puctures into our album. We defined 5 inputs, first one is required but other are optional. When this form is submitted, it will use upload command as defined by Upload button.

Callback edit has been changed as well, now we have to handle different tabs, so we use switch on Tcl variable tab to produce different data for different parts of ADP template. When tab photos was chosen, we retrieve all pictures for the selected album into multirow datasource or recordset.

photo_size field is updated with human readable format of the image size. We assign every image with link to popup separate window whcih will show image in full size. In the page we scale them to 150x150, some images will be distored but in this application we will not perform smart scaling using ImageMagick or with other conversion tool.

New callback upload has been created as well, it will handle upload command: save pictures and create records in photo table for each uploaded picture. Pictures will be saved in the same directory where our pages reside. There is another mechanism to save picturs out of web server root so it cannot be accessed directly. For public albums this is not very useful and a little bit more complicated. When we save picture name in the table we will get the size of the image file and store it in the table, just for convenience for not checking file size on every view.

OSSWEB API

Namespace Hierarchy

OSSWEB API logically split into different Tcl namespace which provides clean way of separation and allows keeping related function close to each other instead of spreading the login across the whole system.

The hierachy tree looks like this:

• ossweb
  • admin - Administrative procs
    
    
  • control - Controlling/extending and customization hadlers
    
    
    • user - Extending users modifications
      
      
    • prefs - Extending user preferences
      
      
    • login - Customize user login process
      
      
    • logout - Customize user logout process
      
      
    • nosession - Customize redirection for not logged in users
      
      
    • noaccess - Customize redirection for access denied situation
    
    
    
  • tag - Custom templating tags
    
    
  • html - HTML generation procs
    
    
    • menu - Different navigation menus
      
      
    • toolbar - Support for modules toolbar
    
    
    
  • cache - local cache procs
    
    
  • datatype - data type validation
    
    
  • cluster - multi server cluster support
    
    
  • adp - templating engine
    
    
  • schedule - background scheduling
    
    
    • hourly - All Tcl procs in this namespace will be run every hour
      
      
    • daily - All Tcl procs in this namespace will be run every day
      
      
    • weekly - All Tcl procs in this namespace will be run every week
      
      
    • monthly - All Tcl procs in this namespace will be run every month
    
    
    
  • conn - Current connection/session support
    
    
  • tsearch - Full text search support
    
    
  • tracker - Update tracker support
    
    
  • sql - SQL generation support
    
    
  • db - Database API procs
    
    
  • util - Misc utilities
    
    
  • convert - Convertion between different types
    
    
  • form - Form validation/support
    
    
  • widget - Widget support, form generation
    
    
  • file - File storage support
    
    
  • resource - Resource sharing and locking
    
    
  • lookup - Lookup/search support

Core Procs

• ossweb::register_init name
  
  
• ossweb::random
  
  
• ossweb::random_range ?range 100?
  
  
• ossweb::version ?-module? ?-rev f?
  
  
• ossweb::config param ?default?
  
  
• ossweb::set_config name ?value? ?db 0?
  
  
• ossweb::list_config pattern
  
  
• ossweb::reset_config ?-cluster f?
  
  
• ossweb::exists name
  
  
• ossweb::lexists list value
  
  
• ossweb::image_name name
  
  
• ossweb::image_exists id ?path? ?root?
  
  
• ossweb::decode value ?args?
  
  
• ossweb::iftrue if then ?else?
  
  
• ossweb::nvl value ?default?
  
  
• ossweb::true value ?null 0?
  
  
• ossweb::coalesce val1 ?val2? ?valN...?
  
  
• ossweb::message type
  
  
• ossweb::hexify data
  
  
• ossweb::dehexify data
  
  
• ossweb::pad0 string size
  
  
• ossweb::trim0 value
  
  
• ossweb::dirname path
  
  
• ossweb::negative value
  
  
• ossweb::file_list path match
  
  
• ossweb::number_list last ?first 0?
  
  
• ossweb::option_list first last ?step 1? ?size 0?
  
  
• ossweb::read_file path
  
  
• ossweb::write_file path data ?-empty t? ?-mode w?
  
  
• ossweb::oproc nm proc params ?default?
  
  
• ossweb::ovar nm var ?default?
  
  
• ossweb::template name ?-level?
  
  
• ossweb::encrypt str ?-secret? ?-token?
  
  
• ossweb::decrypt str ?-secret? ?-token? ?-crc?
  
  
• ossweb::crc32 instr
  
  
• ossweb::acl acl
  
  
• ossweb::date command
  
  
• ossweb::sendmail rcpt_to mail_from subject body ?-headers? ?-domain? ?-files? ?-direct? ?-bcc? ?-cc? ?-error? ?-message_type? ?-content_type? ?-filedir?
  
  
• ossweb::multirow cmd
  
  
• ossweb::project name ?default?
  
  
• ossweb::tsearch cmd type

Cache Procs

• ossweb::cache command key
  
  
• ossweb::cache::create cache ?-params? ?-expires? ?-size 0? ?-timeout? ?-maxentry?
  
  
• ossweb::cache::exists cache key
  
  
• ossweb::cache::put cache key val ?-params? ?-expires? ?-timeout?
  
  
• ossweb::cache::run cache key script ?-force? ?-params? ?-expires? ?-timeout?
  
  
• ossweb::cache::get cache key ?-params? ?-default? ?-timeout?
  
  
• ossweb::cache::incr cache key ?-params? ?-incr 1? ?-expires? ?-timeout?
  
  
• ossweb::cache::append cache key val ?-params? ?-expires? ?-timeout?
  
  
• ossweb::cache::lappend cache key val ?-params? ?-expires? ?-timeout?
  
  
• ossweb::cache::flush cache
  
  
• ossweb::cache::keys cache ?pattern?
  
  
• ossweb::cache::names

Type Validation Procs

• ossweb::datatype::validate name type ?-code? ?-errmsg? ?-level? ?-required 1?
  
  
• ossweb::datatype::value name type ?-default? ?-level 1?
  
  
• ossweb::datatype::integer value
  
  
• ossweb::datatype::int value
  
  
• ossweb::datatype::ilist value
  
  
• ossweb::datatype::text value
  
  
• ossweb::datatype::textarea value
  
  
• ossweb::datatype::url value
  
  
• ossweb::datatype::name value
  
  
• ossweb::datatype::file value
  
  
• ossweb::datatype::email value
  
  
• ossweb::datatype::float value
  
  
• ossweb::datatype::money value
  
  
• ossweb::datatype::macaddr value
  
  
• ossweb::datatype::ipaddr value
  
  
• ossweb::datatype::phone value
  
  
• ossweb::datatype::boolean value

Conversion Procs

• ossweb::convert::string_to_list str ?-skip? ?-separator " "?
  
  
• ossweb::convert::set_to_list id ?-skip? ?-values f? ?-names f? ?-filter? ?-lowercase f?
  
  
• ossweb::convert::set_to_attributes ?-skip? ?-quotes? ?-filter?
  
  
• ossweb::convert::set_to_vars id ?-skip? ?-level 1?
  
  
• ossweb::convert::set_to_array id name ?-skip? ?-filter?
  
  
• ossweb::convert::list_to_query list
  
  
• ossweb::convert::list_to_attributes list ?-skip? ?-quote """? ?-delim " "?
  
  
• ossweb::convert::list_to_array list name
  
  
• ossweb::convert::list_to_vars list ?-null t? ?-level 1? ?-skip?
  
  
• ossweb::convert::vars_to_list vars ?-null t? ?-level 1? ?-skip?
  
  
• ossweb::convert::array_to_set array ?-persist f? ?-name?
  
  
• ossweb::convert::array_to_list array ?-skip? ?-filter?
  
  
• ossweb::convert::array_to_string array ?-delimiter ","? ?-escape f? ?-quote f?
  
  
• ossweb::convert::array_to_js array
  
  
• ossweb::convert::plain_list name
  
  
• ossweb::convert::query_to_vars str
  
  
• ossweb::convert::query_to_value value ?type?
  
  
• ossweb::convert::value_to_query value ?type?

Connection Procs

• ossweb::conn name ?args?
  
  
• ossweb::conn::log type name ?args?
  
  
• ossweb::conn::init_vars ?-level? ?-force f? ?-skip? ?-array? columns
  
  
• ossweb::conn::init_reftable ?-page_name? ?-app_name?
  
  
• ossweb::conn::export_form ?-form? ?-include? ?-skip? ?-format?
  
  
• ossweb::conn::get_property name ?-global f? ?-cache t? ?-default? ?-columns? ?-array? ?-skip? ?-db t? ?-debug f? ?-timeout? ?-encrypt f? ?-decrypt f? ?-user_id?
  
  
• ossweb::conn::set_property name value ?-global f? ?-cache t? ?-columns? ?-array? ?-vars? ?-forms? ?-skip? ?-db t? ?-debug f? ?-append f? ?-lappend f? ?-timeout? ?-encrypt f? ?-decrypt f? ?-user_id?
  
  
• ossweb::conn::clear_property name ?-global f? ?-cache f? ?-db t? ?-user_id?
  
  
• ossweb::conn::sessionvars ?-level? ?-global f? ?-clear f? ?-query t? ?-debug f? ?args?
  
  
• ossweb::conn::query ?-quote f? ?-level? ?-return f? ?-regexp? ?-match? ?-columns? ?-form? ?-validate t? ?-plain f? ?-array? ?-debug f?
  
  
• ossweb::conn::callback name body
  
  
• ossweb::conn::response ?data? ?type text/html?
  
  
• ossweb::conn::next ?-project_name? ?-app_name? ?-page_name? ?-cmd_name view? ?-ctx_name? ?-app? ?-page? ?-cmd? ?-ctx? ?-exit ?? ?-javascript? ?-errormsg? ?-target? ?-return f? ?-url? ?-debug f? ?-none f? ?args?
  
  
• ossweb::conn::process ?-columns? ?-columns2? ?-sessionvars? ?-sessionvars_clear f? ?-sessionvars_global f? ?-next? ?-next_template? ?-on_error_set_msg "Application was unable to process the request"? ?-on_error_set_cmd edit? ?-on_error {-cmd error}? ?-on_error_set_template? ?-on_error_eval? ?-transaction f? ?-validate? ?-sql_stmt? ?-forms? ?-form_error f? ?-form_validate? ?-form_create? ?-form_recreate f? ?-form_tracking f? ?-form_tracking_clear f? ?-query f? ?-queryarray? ?-exec? ?-debug f? ?-final? ?-default? ?-eval?
  
  
• ossweb::conn::set_user_id ?-domain? ?-cookie? ?-max_age -1? ?-path /? ?-secure f? ?-clear f? ?-user_id?
  
  
• ossweb::conn::set_session_id ?-max_age? ?-domain? ?-cookie? ?-secure f? ?-path /? ?-new f? ?-clear f? ?-data? ?-session? ?-user_id?
  
  
• ossweb::conn::redirect url ?-exit t? ?-log f?
  
  
• ossweb::conn::redirect_for_login ?-url? ?-redirect t? ?-callbacks t?
  
  
• ossweb::conn::redirect_access_denied ?-msg accessdenied?
  
  
• ossweb::conn::sign ?-max_age? value
  
  
• ossweb::conn::signed_cookie ?-set_expires f? name
  
  
• ossweb::conn::sign_cookie ?-secure 0? ?-max_age? ?-domain? ?-path? name value
  
  
• ossweb::conn::parse_url
  
  
• ossweb::conn::parse_user ?cookie?
  
  
• ossweb::conn::parse_session user_id ?-cookie? ?-check_ip?
  
  
• ossweb::conn::parse_request
  
  
• ossweb::conn::read_user user_id ?-user_name? ?-user_email? ?-check_password? ?-cache? ?-refresh f? ?-timeout 900?
  
  
• ossweb::conn::read_acl obj_id
  
  
• ossweb::conn::check_acl ?-acl? ?-project_name? ?-app_name? ?-page_name? ?-cmd_name? ?-ctx_name? ?-query N? ?-handlers N? ?-params? ?-unknown unknown? ?-debug f?
  
  
• ossweb::conn::create_acl obj_id ?-project_name? ?-app_name *? ?-page_name *? ?-cmd_name *? ?-ctx_name *? ?-value Y? ?-query? ?-handlers? ?-precedence? ?-obj_type U?
  
  
• ossweb::conn::shared_secret
  
  
• ossweb::conn::secret seed
  
  
• ossweb::conn::set_msg ?-color? ?-standard f? ?-new f? msg
  
  
• ossweb::conn::header name
  
  
• ossweb::conn::hostname ?proto "http://"?
  
  
• ossweb::conn::localnetwork ?ipaddr?

Database Procs

• ossweb::db::xql data ?level? ?vars? ?varray?
  
  
• ossweb::db::columns table_name ?attnum 0?
  
  
• ossweb::db::tables ?-tables?
  
  
• ossweb::db::value sql ?-level? ?-db? ?-release f? ?-default? ?-refresh f? ?-cache? ?-cache:auto f? ?-cache:flush? ?-timeout? ?-debug f? ?-vars? ?-vars:array? ?-colname? ?-colindex 0? ?-map? ?-acl?
  
  
• ossweb::db::list sql ?-level? ?-db? ?-refresh f? ?-debug f? ?-cache? ?-cache:auto f? ?-cache:flush? ?-colindex 0? ?-colname? ?-timeout? ?-release f? ?-maxrows? ?-unique f? ?-all f? ?-map? ?-vars? ?-vars:array? ?-acl?
  
  
• ossweb::db::multilist sql ?-level? ?-db? ?-refresh f? ?-debug f? ?-cache? ?-cache:auto f? ?-cache:flush? ?-timeout? ?-release f? ?-vars? ?-vars:array? ?-array f? ?-plain f? ?-acl? ?-map? ?-unique? ?-maxrows? ?-arrayvars? ?-colcount? ?-colindex? ?-colname?
  
  
• ossweb::db::multivalue sql ?-level? ?-db? ?-prefix? ?-refresh f? ?-error f? ?-array? ?-cache? ?-cache:auto f? ?-cache:flush? ?-timeout? ?-release f? ?-debug f? ?-local t? ?-map? ?-vars? ?-vars:array? ?-arrayvars? ?-acl?
  
  
• ossweb::db::multirow name sql ?-level? ?-db? ?-eval? ?-eval2? ?-local f? ?-replace_null? ?-set_null? ?-refresh f? ?-debug f? ?-cache? ?-cache:auto f? ?-cache:flush? ?-cache:global t? ?-norows f? ?-nocolumns f? ?-maxrows 1000? ?-timeout? ?-error f? ?-release f? ?-map? ?-vars? ?-vars:array? ?-arrayvars? ?-acl?
  
  
• ossweb::db::multipage id query1 query2 ?-level? ?-db? ?-debug f? ?-eval? ?-cache? ?-refresh f? ?-eval2? ?-query? ?-url? ?-eval_single? ?-replace_null? ?-set_null? ?-pagesize 25? ?-timeout 600? ?-page 1? ?-local f? ?-force f? ?-cmd cmd? ?-cmd_name view? ?-error f? ?-datatype int? ?-release f? ?-vars? ?-vars:array? ?-map? ?-arrayvars? ?-norows f? ?-user_id? ?-acl?
  
  
• ossweb::db::foreach sql ?-eval}? ?-level? ?-db? ?-release f? ?-prefix? ?-columns? ?-on_empty? ?-error f? ?-debug f? ?-refresh f? ?-vars? ?-vars:array? ?-cache? ?-cache:auto f? ?-cache:flush? ?-arrayvars? ?-array? ?-map? ?-timeout? ?-acl?
  
  
• ossweb::db::exec sql ?-level? ?-db? ?-error f? ?-debug f? ?-vars? ?-vars:array? ?-cmd? ?-msg f? ?-acl?
  
  
• ossweb::db::insert table ?-insertargs? ?-skip_null t? ?-skip? ?-columns? ?args?
  
  
• ossweb::db::update table ?-where? ?-dbargs? ?-updateargs? ?-skip_null f? ?-skip? ?-columns? ?args?
  
  
• ossweb::db::delete table ?-where? ?-dbargs? ?args?
  
  
• ossweb::db::read table ?-where? ?-dbargs? ?-type multivalue? ?-columns *? ?-filter? ?-filterargs? ?-orderby? ?-limit? ?args?
  
  
• ossweb::db::select table ?-where? ?-dbargs? ?-type multilist? ?-columns *? ?-filter? ?-filterargs? ?-orderby? ?-limit? ?args?
  
  
• ossweb::db::block sql_list ?-level? ?-db? ?-release f? ?-vars? ?-vars:array? ?-debug f?