Module Quick Start Guide

This module provides an ability to read and/or execute external files and embed their output results in any MIVA Merchant template controlled page. See the External Files section on suggestions for incorporating the External File features into various MIVA Merchant pages. Checkout Great New Module Features available in v5.02.

Available Render Tokens
• readscript	• readdata	• run	• function
• call	• mvreadscript	• mvreaddata	• mvrun
• mvfunction	• mvcall	• mvassign	• mveval

Module does not provide any Administrator Configured options. All external file specifications are passed in a Parameter using the Render Tokens describe below:

• Module automatically installs and configures the required item.
• You must assign the "ads-extfile" item to the page(s) where you would like to use it.
• You must insert an appropriate item Render Token in any page related template(s) to utilize module features. Render Tokens can be used in Page Templates, Product List Layouts, Messages, Headers, Footers, etc..
• Module includes twelve Render Tokens in order to provide various methods for embedding and/or executing the external files, scripts and built-in MivaScript functions. Depending on a type of Token, additional information such as Parameters may also be included.
  • "readscript" Token provides a way to read and render an external file located in the script directory on the same server as Merchant installation.
    
    "readscript" Example
    Read and Render an external HTML File located in server script directory "/mm5/extfiles/exf1.html".
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="readscript|/mm5/extfiles/exf1.html" />
    Item param field contains the action "readscript" to be performed and the file path, relative to the server root. A pipe "|" character is used to separate individual fields within item param field. The HTML file inserted must contain only the body of HTML document or you will get duplicate HEAD and BODY tags, unless you are rendering an external file in a Merchant Page that does not contain its own HEAD and BODY tags. If you are rendering an external TEXT file and would like to retain the TEXT file alignment, wrap the item above in a set of <PRE></PRE> tags.
    
    
  • "readdata" Token provides a way to read and render an external file located in the data directory on the same server as Merchant installation. Since an external file is located in the Data directory, it would normally not be accessible by the public. You can use this functionality to display content not directly available. You can also use this feature with Merchant Availability Groups to insert specific content only available to that Availability Group.
    
    "readdata" Example
    Read and Render an external HTML File located in server data directory "/merchant5/extfiles/exf2.html". Since an external file is located in the Data directory, it would normally not be directly accessible by the public. You can use this functionality to display content not directly available. You can also use this feature with Merchant Availability Groups to insert specific content only available to that Availability Group.
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="readdata|/merchant5/extfiles/exf2.html" />
    Item param field contains the action "readdata" to be performed and the file path, relative to the server root. A pipe "|" character is used to separate individual fields within item param field. The HTML file inserted must contain only the body of HTML document or you will get duplicate HEAD and BODY tags, unless you are rendering an external file in a Merchant Page that does not contain its own HEAD and BODY tags. If you are rendering an external TEXT file and would like to retain the TEXT file alignment, wrap the item above in a set of <PRE></PRE> tags.
    
    
  • "run" Token provides a way to execute an external, compiled, MivaScript file located in the script directory on the same server as Merchant installation. No specific Function requirements. Only Global Merchant variables will be available.
    
    "run" Example
    Execute an external, compiled MIVA Script File located in server script directory "/mm5/extfiles/exf3.mvc".
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="run|/mm5/extfiles/exf3.mvc" />
    Item param field contains the action "run" to be performed and the file path, relative to the server root. A pipe "|" character is used to separate individual fields within item param field.
    
    
  • "function" Token provides a way to execute an external, compiled, MivaScript file located in the script directory on the same server as Merchant installation. A Specific Function with parameters is required. Merchant Global, All_Settings, Settings, Module, Item and additional Parameter variables will be available to this function.
    
    "function" Example
    Execute an external, compiled MIVA Script File located in server script directory "/mm5/extfiles/exf4.mvc". This file must contain a Function "ADS_External_File" with a set of parameters. An uncomiled MIVA Script file containing an example Function was included with the Module distribution. This function also contains an example Breadcrumb Navigation script that can be used on your Category and Product Pages.
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="function|/mm5/extfiles/exf4.mvc|breadcrumbs" />
    Item param field contains the action "function" to be performed, and the file path, relative to the server root, and the parameter, which is passed to the Function. A pipe "|" character is used to separate individual fields within item param field. Parameter passed to the Function can be used to determine what needs to be done.
    
    Here is an example Function included in the distribution:
    <MvFUNCTION NAME = "ADS_External_File" PARAMETERS = "module var, item, all_settings var, settings var, fparam" STANDARDOUTPUTLEVEL = "text, html, compresswhitespace">
    <MvCOMMENT>Example Function For Generating Breadcrumb Navigation on Category and Product Pages</MvCOMMENT>
    <MvIF EXPR = "{ l.fparam EQ 'breadcrumbs' }">
    <MvASSIGN NAME = "l.ADS_BC_line" VALUE = "{ '<A HREF="' $ g.sessionurl $ 'Screen=CTGY&Store_Code=' $ encodeattribute( g.Store:code ) $ '&Category_Code=' $ encodeattribute( l.all_settings:category:code ) $ '">' $ l.all_settings:category:name $ '</A>' }">
    <MvIF EXPR = "{ l.all_settings:category:parent_id }">
    <MvASSIGN NAME = "l.parent_id" VALUE = "{ l.all_settings:category:parent_id }">
    <MvWHILE EXPR = "{ l.parent_id }">
    <MvIF EXPR = "{ NOT [ g.Module_Library_DB ].Runtime_Category_Load_ID( l.parent_id, l.category ) }">
    <MvWHILESTOP>
    </MvIF>
    <MvASSIGN NAME = "l.ADS_BC_line" VALUE = "{ '<A HREF="' $ g.sessionurl $ 'Screen=CTGY&Store_Code=' $ encodeattribute( g.Store:code ) $ '&Category_Code=' $ encodeattribute( l.category:code ) $ '">' $ '' $ l.category:name $ '' $ '</A>' $ ' > ' $ l.ADS_BC_line }">
    <MvASSIGN NAME = "l.parent_id" VALUE = "{ l.category:parent_id }">
    </MvWHILE>
    </MvIF>
    <A HREF="{ g.sessionurl $ 'Screen=SFNT&Store_Code=' $ encodeattribute( g.Store:code ) }">Home</A><MvEVAL EXPR="{ ' > '$l.ADS_BC_line }">
    <MvIF EXPR = "{ l.all_settings:product:name }">
    <MvEVAL EXPR="{ ' > ' $ l.all_settings:product:name }">
    </MvIF>
    </MvIF>
    </MvFUNCTION>
    
    
  • "call" Token provides a way to call(read/execute) and render an external file located on any server, accessible through an HTTP call. You can also use this functionality to execute external script files. These files can be MIVA, PHP, ASP, Perl, JAVA, CFM, etc..
    
    "call" Example
    Call an external HTML File located on another server "http://www.anydomain.com/exf5.html", accessible through an HTTP call.
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="call|http://www.anydomain.com/exf5.html" />
    Item param field contains the action "call" to be performed and the complete URL containing "http://". Even if the file is called on the same server as the Merchant installation a complete URL must be used. A pipe "|" character is used to separate individual fields within item param field. The HTML file inserted must contain only the body of HTML document or you will get duplicate HEAD and BODY tags, unless you are rendering an external file in a Merchant Page that does not contain its own HEAD and BODY tags. If you are rendering an external TEXT file and would like to retain the TEXT file alignment, wrap the item above in a set of <PRE></PRE> tags.
    
    

  New in v5.02 - Expanded External File functionality with new MivaScript Parameter Functions(MvASSIGN & MvEVAL). These functions provide an ability to pass variables directly to external files, render external files based on Merchant variables, and evaluate or assign new variables, from any template, using built-in MivaScript functions, at template run time. This can be very useful in rendering external files based on merchant variables, creating short titles or descriptions, checking for existence of an image on the server, or making a quick discount calculation, all by executing built-in MivaScript functions at run time, right from the template. This is done by passing Merchant variables, by reference, and executing MivaScript expressions and build-in functions.
  

  • "mvreadscript" Token provides a way to read and render an external file located in the script directory on the same server as Merchant installation. File path can contain available Merchant variables, MivaScript expressions and built-in functions.
    
    "mvreadscript" Example
    Read and Render an external HTML File, named by the Product Code, located in server script directory "/mm5/extfiles/Product_Code.html".
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="mvreadscript|'/mm5/extfiles/' $ l.all_settings:product:code $ '.html'" />
    Item param field contains the action "readscript" to be performed and the file path, relative to the server root. A pipe "|" character is used to separate individual fields within item param field. The HTML file inserted must contain only the body of HTML document or you will get duplicate HEAD and BODY tags, unless you are rendering an external file in a Merchant Page that does not contain its own HEAD and BODY tags. If you are rendering an external TEXT file and would like to retain the TEXT file alignment, wrap the item above in a set of <PRE></PRE> tags.
    
    
  • "mvreaddata" Token provides a way to read and render an external file located in the data directory on the same server as Merchant installation. File path can contain available Merchant variables, MivaScript expressions and built-in functions. Since an external file is located in the Data directory, it would normally not be accessible by the public. You can use this functionality to display content not directly available. You can also use this feature with Merchant Availability Groups to insert specific content only available to customers in that Availability Group.
    
    "mvreaddata" Example
    Read and Render an external HTML File, named by the Product Code, located in server data directory "/merchant5/extfiles/Product_Code.html". Since an external file is located in the Data directory, it would normally not be directly accessible by the public. You can use this functionality to display content not directly available. You can also use this feature with Merchant Availability Groups to insert specific content only available to that Availability Group.
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="mvreaddata|'/merchant5/extfiles/' $ l.all_settings:product:code $ '.html'" />
    Item param field contains the action "readdata" to be performed and the file path, relative to the server root. A pipe "|" character is used to separate individual fields within item param field. The HTML file inserted must contain only the body of HTML document or you will get duplicate HEAD and BODY tags, unless you are rendering an external file in a Merchant Page that does not contain its own HEAD and BODY tags. If you are rendering an external TEXT file and would like to retain the TEXT file alignment, wrap the item above in a set of <PRE></PRE> tags.
    
    
  • "mvrun" Token provides a way to execute an external, compiled, Miva Script file, named by the Product Code, located in the script directory on the same server as Merchant installation. File path can contain available Merchant variables, MivaScript expressions and built-in functions. No specific Function requirements. Only Global Merchant variables will be available.
    
    "mvrun" Example
    Execute an external, compiled MIVA Script File, named by the Product Code, located in server script directory "/mm5/extfiles/Product_Code.mvc".
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="mvrun|'/mm5/extfiles/' $ l.all_settings:product:code $ '.mvc'" />
    Item param field contains the action "run" to be performed and the file path, relative to the server root. A pipe "|" character is used to separate individual fields within item param field.
    
    
  • "mvfunction" Token provides a way to execute an external, compiled, Miva Script file located in the script directory on the same server as Merchant installation. File path can contain available Merchant variables, MivaScript expressions and built-in functions. A Specific Function with parameters is required. Merchant Global, All_Settings, Settings, Module, Item and additional Parameter variables will be available to this function.
    
    "mvfunction" Example
    Execute an external, compiled Miva Script File located in server script directory "/mm5/extfiles/Product_Code.mvc". This file must contain a Function "ADS_External_File" with a set of parameters. An uncomiled MIVA Script file containing an example Function was included with the Module distribution. This function also contains an example Breadcrumb Navigation script that can be used on your Category and Product Pages.
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="mvfunction|'/mm5/extfiles/' $ l.all_settings:product:code $ '.mvc'|breadcrumbs" />
    Item param field contains the action "function" to be performed, and the file path, relative to the server root, and the parameter, which is passed to the Function. A pipe "|" character is used to separate individual fields within item param field. Parameter passed to the Function can be used to determine what needs to be done.
    
    Here is an example Function included in the distribution:
    <MvFUNCTION NAME = "ADS_External_File" PARAMETERS = "module var, item, all_settings var, settings var, fparam" STANDARDOUTPUTLEVEL = "text, html, compresswhitespace">
    <MvCOMMENT>Example Function For Generating Breadcrumb Navigation on Category and Product Pages</MvCOMMENT>
    <MvIF EXPR = "{ l.fparam EQ 'breadcrumbs' }">
    <MvASSIGN NAME = "l.ADS_BC_line" VALUE = "{ '<A HREF="' $ g.sessionurl $ 'Screen=CTGY&Store_Code=' $ encodeattribute( g.Store:code ) $ '&Category_Code=' $ encodeattribute( l.all_settings:category:code ) $ '">' $ l.all_settings:category:name $ '</A>' }">
    <MvIF EXPR = "{ l.all_settings:category:parent_id }">
    <MvASSIGN NAME = "l.parent_id" VALUE = "{ l.all_settings:category:parent_id }">
    <MvWHILE EXPR = "{ l.parent_id }">
    <MvIF EXPR = "{ NOT [ g.Module_Library_DB ].Runtime_Category_Load_ID( l.parent_id, l.category ) }">
    <MvWHILESTOP>
    </MvIF>
    <MvASSIGN NAME = "l.ADS_BC_line" VALUE = "{ '<A HREF="' $ g.sessionurl $ 'Screen=CTGY&Store_Code=' $ encodeattribute( g.Store:code ) $ '&Category_Code=' $ encodeattribute( l.category:code ) $ '">' $ '' $ l.category:name $ '' $ '</A>' $ ' > ' $ l.ADS_BC_line }">
    <MvASSIGN NAME = "l.parent_id" VALUE = "{ l.category:parent_id }">
    </MvWHILE>
    </MvIF>
    <A HREF="{ g.sessionurl $ 'Screen=SFNT&Store_Code=' $ encodeattribute( g.Store:code ) }">Home</A><MvEVAL EXPR="{ ' > '$l.ADS_BC_line }">
    <MvIF EXPR = "{ l.all_settings:product:name }">
    <MvEVAL EXPR="{ ' > ' $ l.all_settings:product:name }">
    </MvIF>
    </MvIF>
    </MvFUNCTION>
    
    
  • "mvcall" Token provides a way to call(read/execute) and render an external file located on any server, accessible through an HTTP call. You can also use this functionality to execute external script files and pass parameters. These files can be MIVA, PHP, ASP, Perl, JAVA, CFM, etc.. The called file path can use Merchant variables, MivaScript expressions and built-in functions
    
    "mvcall" Example
    Call an external HTML File, named by the Product Code, located on another server "http://www.anydomain.com/Product_Code.html", accessible through an HTTP call and pass store code, product code and product price as a parameters to the script.
    
    Here is an example Render Token to do this:
    <mvt:item name="ads-extfile" param="mvcall|'http:/www.anydomain.com/' $ l.all_settings:product:code $ '.html'|l.all_settings:store:name,l.all_settings:product:code,l.all_settings:product:price" />
    Item param field contains the action "mvcall" to be performed, the complete URL containing "http://", as a MivaScript expression and a list of Merchant variables that needs to be passed. Even if the file is called on the same server as the Merchant installation a complete URL must be used. A pipe "|" character is used to separate individual sub-parameter fields within item param field. The HTML file inserted must contain only the body of HTML document or you will get duplicate HEAD and BODY tags, unless you are rendering an external file in a Merchant Page that does not contain its own HEAD and BODY tags. If you are rendering an external TEXT file and would like to retain the TEXT file alignment, wrap the item above in a set of <PRE></PRE> tags.
    
    
  • "mvassign" Token provides a way to assign and use new variables at run-time right from your template. The variable assignment can utilize MivaScript expressions and built-in functions. Variable values can then be used as SMT entities for display or in the IF statements and FOR loops.
    
    "mvassign" Example
    Displaying additional product images if they exist on the server:
    <mvt:item name="ads-extfile" param="mvassign|l.all_settings:image1_exists|sexists('/mm5/graphics/00000001/' $ l.all_settings:product:code $ '_1.jpg')" />
    <mvt:if expr="l.settings:image1_exists">
         <IMG SRC="graphics/00000001/&mvt:product:code;_1.jpg">
    </mvt:if>
    

    You can use the same technique to create short titles, calculate percent discounts, create search friendly titles, etc...
    
    NOTE: Caution should be taken in using MivaScript parameter Functions, since they allow you to directly create and modify Merchant Variables, Arrays, and Execute Built-In functions, right from the template, at run time.
    
    

  • "mveval" Token provides a way to evaluate MivaScript expressions and built-in functions at run-time right from your template. It works just like the mvassign token, except the expression result is rendered, not assigned to a variable.
    
    "mveval" Example
    Displaying short product titles on category pages. This example also illustrates the use of "mveval" Parameter Function:
    <mvt:item name="ads-extfile" param="mvassign|l.all_settings:namelength|len(l.all_settings:product:name)" />
    <mvt:if expr="l.settings:namelength GE 25">
        <mvt:item name="ads-extfile" param="mveval|(substring(l.all_settings:product:name, 1, 25))$'...'" />
    <mvt:else>
         &mvt:product:name;
    </mvt:if>

More MivaScript API Documentation can be found here: http://smallbusiness.miva.com/support/docs/api/