Difference between revisions of "Ns adp include"

From AOLserver Wiki
Jump to navigation Jump to search
(formatting tweaks, fix example)
Line 3: Line 3:
 
'''NAME'''
 
'''NAME'''
  
: ns_adp_include - Parse an ADP file and return its output
+
: ns_adp_include - Parse an ADP file with the generated output written to the adp buffer
  
 
'''SYNOPSIS'''
 
'''SYNOPSIS'''
  
: '''ns_adp_include''' ''file ?args ...?''
+
: '''ns_adp_include''' ''?-cache seconds? ?-nocache? file ?arg arg ...?''
  
 
'''DESCRIPTION'''
 
'''DESCRIPTION'''
  
: This command reads ''file'' and parses its contents as an ADP and returns the output to the caller.  ''file'' is relative to the caller's directory unless an absolute pathname is used. Optional ''args'' can be passed which are accessed using [[ns_adp_argc]], [[ns_adp_argv]] and [[ns_adp_bind_args]] commands in the callee.
+
: This command reads ''file'' and parses its contents as an ADP with the generated output written to the adp buffer and returns the ''adp return value'' (i.e. from return, ns_adp_return or the last tcl command in the adp) to the caller.  ''file'' is relative to the caller's directory unless an absolute pathname is used. Tcl commands in the ADP are evaluated in a new scope one level below the caller just like when calling a proc. Optional arguments can be passed which are accessed using [[ns_adp_argc]], [[ns_adp_argv]] and [[ns_adp_bind_args]] commands in the callee.
  
: Note that ADP streaming cannot be turned on using [[ns_adp_stream]] from within an ADP executed with the '''ns_adp_include''' command.  Tcl commands in the ADP will be evaluated in a new scope.
+
: The optional ''-cache seconds'' argument specifies the time to cache the results of execution (i.e. the output written to the adp buffer).  Output generated by any scripts and included ADPs is saved for subsequent requests except ns_adp_included blocks that specify the -nocache switch as part of the ns_adp_include command.  The use of ''-cache'' and ''-nocache''can be used to increase performance of ADP used to generated a mix of personalized, non-cacheable, content and shared content which changes more slowly.  Under high load, the performance improvement can be substaintial, especially in cases where the cached content is the result of accessing a slow databases or web services.  See the EXAMPLES section for an example of using cached output.
 +
 
 +
: Note that ADP streaming cannot be turned on using [[ns_adp_stream]] from within an ADP executed with the '''ns_adp_include''' command.
  
 
: ADPs can be nested by including each other up to the maximum of 256 levels deep.
 
: ADPs can be nested by including each other up to the maximum of 256 levels deep.
  
: This command is only available from an ADP.  Use [[ns_adp_parse]] to parse ADPs from outside the context of an ADP.
+
: This command is only available from an ADP page or script.  Use [[ns_adp_parse]] to parse ADPs from outside the context of an ADP.
  
 
'''EXAMPLES'''
 
'''EXAMPLES'''
Line 23: Line 25:
 
<pre>
 
<pre>
 
     ###
 
     ###
     ### Example #1: Callee outputs directly to ADP output buffer.
+
     ### Example #1: Callee writes the output directly to ADP output buffer, also using passed arguments.
 
     ###
 
     ###
  
 
     # In a.adp:
 
     # In a.adp:
     <% ns_adp_include b.adp %>
+
     <% ns_adp_include b.adp Bob%>
  
 
     # In b.adp:
 
     # In b.adp:
     <% ns_adp_puts "Hello, world!" %>
+
     <% ns_adp_puts "Hello, [ns_adp_argv 1 world]!" %>
  
 
     ###
 
     ###
     ### Example #2: Caller outputs to ADP buffer.
+
     ### Example #2: Caller writes the adp return value to ADP buffer.
 
     ###
 
     ###
  
Line 40: Line 42:
  
 
     # In b.adp:
 
     # In b.adp:
     <% return "Hello, world!" %>
+
     <% return "Hello, [ns_adp_argv 1 world]!" %>
 +
 
 +
    ###
 +
    ### Example #3: The following example demonstrates using the -cache and -nocache options to enhance
 +
    ###            performance through caching execution output.
 +
 
 +
    # In top.adp:
 +
    <% ns_adp_include -cache 60 cached.adp %>
 +
 
 +
    # In cached.adp:
 +
    <%
 +
      ns_adp_puts "Time at cache: [ns_time]"
 +
      ns_adp_include -nocache nocache.adp
 +
    %>
 +
 
 +
    # In nocache.adp:
 +
    <% ns_adp_puts "Time now: [ns_time]" %>
 +
 
 +
    # The output of cached.adp will only update once every 60 seconds except for the portion
 +
    # that is the output of nocache.adp, which  will be executed on each request,
 +
    # even though it's included within cached.adp.
 +
 
 
</pre>
 
</pre>
  

Revision as of 04:44, 14 June 2010

Man page: http://aolserver.com/man/4.0/tcl/ns_adp_include.html


NAME

ns_adp_include - Parse an ADP file with the generated output written to the adp buffer

SYNOPSIS

ns_adp_include ?-cache seconds? ?-nocache? file ?arg arg ...?

DESCRIPTION

This command reads file and parses its contents as an ADP with the generated output written to the adp buffer and returns the adp return value (i.e. from return, ns_adp_return or the last tcl command in the adp) to the caller. file is relative to the caller's directory unless an absolute pathname is used. Tcl commands in the ADP are evaluated in a new scope one level below the caller just like when calling a proc. Optional arguments can be passed which are accessed using ns_adp_argc, ns_adp_argv and ns_adp_bind_args commands in the callee.
The optional -cache seconds argument specifies the time to cache the results of execution (i.e. the output written to the adp buffer). Output generated by any scripts and included ADPs is saved for subsequent requests except ns_adp_included blocks that specify the -nocache switch as part of the ns_adp_include command. The use of -cache and -nocachecan be used to increase performance of ADP used to generated a mix of personalized, non-cacheable, content and shared content which changes more slowly. Under high load, the performance improvement can be substaintial, especially in cases where the cached content is the result of accessing a slow databases or web services. See the EXAMPLES section for an example of using cached output.
Note that ADP streaming cannot be turned on using ns_adp_stream from within an ADP executed with the ns_adp_include command.
ADPs can be nested by including each other up to the maximum of 256 levels deep.
This command is only available from an ADP page or script. Use ns_adp_parse to parse ADPs from outside the context of an ADP.

EXAMPLES

    ###
    ### Example #1: Callee writes the output directly to ADP output buffer, also using passed arguments.
    ###

    # In a.adp:
    <% ns_adp_include b.adp Bob%>

    # In b.adp:
    <% ns_adp_puts "Hello, [ns_adp_argv 1 world]!" %>

    ###
    ### Example #2: Caller writes the adp return value to ADP buffer.
    ###

    # In a.adp:
    <% ns_adp_puts [ns_adp_include b.adp] %>

    # In b.adp:
    <% return "Hello, [ns_adp_argv 1 world]!" %>

    ###
    ### Example #3: The following example demonstrates using the -cache and -nocache options to enhance
    ###             performance through caching execution output. 

    # In top.adp:
    <% ns_adp_include -cache 60 cached.adp %>

    # In cached.adp:
    <%
      ns_adp_puts "Time at cache: [ns_time]"
      ns_adp_include -nocache nocache.adp
    %>

    # In nocache.adp:
    <% ns_adp_puts "Time now: [ns_time]" %>

    # The output of cached.adp will only update once every 60 seconds except for the portion
    # that is the output of nocache.adp, which  will be executed on each request,
    # even though it's included within cached.adp.

SEE ALSO

ns_adp_abort, ns_adp_append, ns_adp_argc, ns_adp_argv, ns_adp_bind_args, ns_adp_break, ns_adp_debug, ns_adp_debuginit, ns_adp_dir, ns_adp_dump, ns_adp_eval, ns_adp_exception, ns_adp_mime, ns_adp_mimetype, ns_adp_parse, ns_adp_puts, ns_adp_registeradp, ns_adp_registerproc, ns_adp_registertag, ns_adp_return, ns_adp_safeeval, ns_adp_stats, ns_adp_stream, ns_adp_tell, ns_adp_trunc