|Home | WebSiphon | Learning Resources||WebSiphon Developer Central|
by Nathan Nunn
What are Built-in Variables?
Built-in variables are special runtime instance variables which are created automatically by WebSiphon each time a page request is received. These variables describe the user's web browser (the user agent), the HTTP request, and other special runtime information used for things like error handling.
Using these valuable built-in variables customized HTML output can be produced depending on conditions of your choosing. This type of conditional logic-based HTML output is called a dynamic publishing system.
These same built-in variables form the basis for more complex, session-based web systems that offer a much more interactive user experience not unlike traditional software applications. As such, these types of systems are named web applications.
Though pre-defined by WebSiphon, built-in variables are not constant. These values are mutable as with any other SiphonScript variable. Note however there are few scenarios where it would be advisable to modify these values and it is not advised, as doing so would deviate from the default WebSiphon environment and potentially confuse others who use your server.
Classes of Built-in Variables
The sections below offer a description of the different types of built-in variables defined by WebSiphon, each organized into the class of data each variable represents. The scripting examples found at the end of each class below include actual values generated when this template was served - in other words, this article was dynamically published on-demand and served to you.
When working with WebSiphon the term template is used to describe a file which contains both blocks of SiphonScript and HTML output. A script is an arbitrary block of SiphonScript statements, which may or may not be associated with a physical file on disk.
- File Paths and Template Info
- This class of built-in variables describe the currently executing template, or script.
- Direct CGI Parameters and the HTTP Request
- This class of built-in variables describe the HTTP request that triggered the current runtime execution and are vital for most methods of session management and other user-centric, specialized services. Some of these variables are provided by the web server daemon process when it calls on WebSiphon to execute a template or script.
- The WebSiphon Environment
- This class of built-in variables describe the WebSiphon environment itself. They are useful when you need to build a reliable file path outside of a web request, or access internal runtime engine settings. Also helpful if you are writing reusable frameworks or other libraries which require a specific add-on or feature to operate correctly.
- Error Handling
- These variables are created when a runtime error occurs. These built-in values used in conjunction with try/catch statements enable scripts to react when an error condition occurs, rather than display a frightening error message to the user.
For further information on the different types of SiphonScript variables and their usage, see the WebSiphon User Guide.
File Paths and Template Info
Built-in Name Description template_name the currently running template's file name template_path the full path to running template this_template the template's complete file path (concatenated template_path and template_name) site_path the full path to web site root template_uri the URI portion of the HTTP request (URI path to this template) template_mod_date the template's modification date template_mod_date_secs the template's modification date, as seconds since Jan 1, 1904
Scripting Examples print template_name; print template_uri; → builtinvars.ws /websiphon/learn/builtinvars.ws print template_path; print site_path; → Saraswati:www-prime:vhosts:purity.com:html-www:websiphon:learn: Saraswati:www-prime:vhosts:purity.com:html-www: print template_mod_date; print template_mod_date_secs; → 9/12/03 0:26:33 3.14617e+09
CGI Parameters and the HTTP Request
Built-in Name Description action_name web server action name for CGI process action_path web server CGI action path cgi_connection_id unique ID used by web server to identify the TCP/IP connection cgi_host_name HTTP host as defined in client request client_accept accept as defined in HTTP request client_accept_language accept language as defined in HTTP request client_accept_encoding accept encoding as defined in HTTP request client_address reverse-lookup Internet name of remote client (if enabled on web server) connection_type connection type as defined in HTTP request content_type MIME type associated with POST arguments, if there are any client_ip_address machine IP address of remote client full_client_request the entire HTTP request as sent by the client web browser (example shows only excerpt, too long to display in full) http_method the HTTP method (GET, POST, etc.) http_version HTTP version specified by the client web browser password HTTP authenticated password, provided only if user has logged into a realm using the client web browser path_arguments URL arguments following a $ character post_arguments POST data resulting from an HTML form submission referer the URL that referenced this request (where page was linked from) script_name URI name for executing script user_agent identification string sent by the client web browser user_agent_cpu client CPU type as sent by the client web browser (not always supplied or available) user_agent_os client OS as sent by the client web browser (not always supplied or available) search_arguments URL arguments following a ? character server_name Internet host name or IP address of web server server_port TCP/IP port number being used for current request username HTTP authenticated username, provided only if user has logged into a realm using the client web browser
Scripting Examples print client_ip_address; → 184.108.40.206 print referer; → print user_agent; → CCBot/2.0 print server_name & ":" & server_port; → burlyhouse.net:80
The WebSiphon Environment
Built-in Name Description siphon_os operating system version string siphon_version WebSiphon version string siphon_sapi WebSiphon API version string siphon_prefs_index_file default index filename, when requests point to a directory siphon_prefs_error_file default error filename, served when request not found (404) siphon_prefs_no_access_file default noaccess filename, served when HTTP authentication fails siphon_data_path full path to the WebSiphon Data folder siphon_templates_path full path to the Templates folder siphon_startup_path full path to the Startup folder siphon_libraries_path full path to the Libraries folder siphon_lib_data_path full path to the Library Data folder
Scripting Examples print siphon_os ", " siphon_version; → Mac OS, 2.0.9 print siphon_prefs_index_file; → index.ws
Error HandlingSome values may not be set depending on conditions surrounding the runtime error.
Built-in Name Description siphon_error_message textual error string (if available) siphon_error_number error number siphon_error_source_file the SiphonScript file which produced the error siphon_error_file_path the full path to file which produced the error siphon_error_line_number approximate line number where error occurred siphon_error_uri the URI which produced the error siphon_error_full_request full headers from request which produced the error
Copyright © 1995-2013 Purity Software. All rights reserved worldwide.
Pure code for pure minds; live to love and learn.