Action: File

By

May 14, 2009

 

 
 

 


The ability to manipulate files, store files within the system, receive incoming files, and handle more advanced conceptual tasks of transforming a file like Images and CSV  files within OWS makes its capability advance far beyond all other tools on the market. Within the OWS environment you can take an incoming file and store it directly within your system, either within the DNN context, or external to that, additionally you can take a file which resides outside the DNN environment and return it directly to the client browser, making file storage and handling much better. Image files can be automatically scaled through manipulation and CSV files can be imported directly from your CSV file to a target SQL structure or advanced execution seamlessly and in real-time, without the adverse worries of request timeouts.
Additionally, the actions presented as children of the Action:File message action will execute upon the completion of the Action:File tag parent. This means, if you need to execute a query, or send an email or perform other threaded tasks after the completion of the File CSV import, you can do that easily. Just add a few actions as children of the file, and check out the possibilities.

 

 

Attributes


The interface provides the following structures, and possible attributes:

Source Type


The source of the file will be one of three possible sources:

Directory / File Path


The source will be coming from the server directly via a path, this path may be either a relative path “~/images/file.gif” for instance, or a fixed path like “C:\wwwroot\images\file.gif”.

Runtime Value


The source will be received via a runtime variable, retrieved from the selection of the Variable Type (ie. Form) 

SQL Query


The source will be retrieved by consuming an SQL Query. This option changes the attributes to provide a Source Query, rather than a Variable Type. The provided SQL Query will allow for either a conversion from SQL to CSV. This can be used also to conduct a transition of data from one SQL statement to another using both SQL as the Source and SQL as the target. Most frequently, however, the SQL provides a row which contains the file data and information. To automatically map the File Information ([FileName,FILE] [ContentType,FILE]) from the columns you MUST set the transformation to FILE COPY. That way you can copy the file from the source (SQL) to the Destination (PATH OR RESPONSE). Automatic mapping is handled through the following Column Names:

 

1. Data,Filecontent, Content, Image and Source are processed as the binary data column automatically (when not present, the first unmatching column is used).

2. Name and Filename are used as the [FILENAME,FILE] value.

3. ContentType, Mime, Type and MimeType are used for the [CONTENTTYPE,FILE] value.

4. Ext and Extension are used for the [EXTENSION,FILE] value.

 

Variable Type

Indicates the textual name, path, or query of the source, depending on the requirements from the Source Type.

  • QueryString – Tthe incoming QueryString contains text that will be used as a file source. This means that you can handle files sent via encoded query variables, and work with them as files directly. The source will map to the name of the variable.
  • Cookie - The incoming Cookie contains text that will be used as a file source. This means that you can handle files sent via encoded Cookie variables, and work with them as files directly. The source will map to the name of the variable.
  • Form - Identifies that the incoming Form contains the physical file. This is handled by submitting a file (via Form Submit) through an Input element of type "File". 

    NOTE: AJAX requests (ows.Fetch for example) CANNOT be used to submit a file to the server. This is because the XMLHttpObject does NOT support binary data, and therefore, the File will be absent from the form submit. Uploading files can only be supported using a Form Submit. Alternatively, the jQuery File Upload plugin has been found to work perfectly within OWS.
  • Session – the Session contains a text value that will be used as a file, or that the Session contains a binary file specifically. The source will map to the name of the session variable.
  • View State – The View State contains a text value that will be used as a file, or that the View State contains a complete binary file specifically. The Source will map to the name of the View State variable.
  • Action – Indicates that the Action array, a temporary array of variables used only by the OWS instance and evaporating after rendering completes for any specific request, contains a variable which is either a text value, or a complete binary file that will be the source of the file action. The Source will map to the name as the Action variable.
  • Custom – Identifies that the source of the variable is convoluted, and will need to be achieved through rendering of a complex OWS tag structure. This may mean that either the source can switch between two variable types or that the Source name is too difficult to manage within the simple drop down. 

Destination Type


The destination of the file, either a path, or other variable context will be used here. The following types of destination are provided:

  • Directory / File Path - Indicates that the destination will be on the server directly via a path, this path may be either a relative path “~/images/file.gif” for instance, or a fixed path like “C:\wwwroot\images\file.gif”. A full filename does need to be included in the path. If the name can vary depending on the actual filename chosen for upload, the path can be included as "~/images/[frmFile.Name,Form]"
  • Runtime Value - Indicates that the destination will be assigned via a runtime variable type
  • Variable Type
    • Session – The file will be placed in the user's Session Array
    • View State – The View State will be the target repository of the outgoing file.
    • Action – The file will be stored in the Action array, a temporary array of variables used only by the OWS instance.  Tha Action array evaporates after rendering completes for any specific request.
    • Cookie - The File should be placed in the cookie directly. This is an uncommon practice, but useful if you are attempting to store comment text content into the browser cookie.
  • SQL Query - The target of the File Action is storing the physical file n the database. Refer to "SQL Destination" below.
  • Outgoing Response – Indicates that the Source file will be sent directly to the awaiting client browser. This allows you to handle a file Download aspect of your site, and lets you provide an online file management scenario quite easily. 
    • Response Type – The response type of the outgoing data – you can choose to use a general response type of application/octet-stream, or a specific value – (See MIME Types).

      If you would like the file to return within the same window, rather than opening a new window or providing the “Save As..” prompt, add “-noattach” to the Response Type value, for example: text/plain-noattach
  • Email Attachment - To attach files to an outgoing email action, you must first create your Email action, then make the File action a child of the Email action. Finally – set Email Attachment as the Destination Type. For more complex types of scenario, for instance when you need to send multiple files based on a Query result – you may set an Execute Action as the child of your Email Action, and then a File Action as the Child of the Execute Action, attaching a file per record in your Query to the outgoing Email.

Destination


Misnamed, the Destination attributes is used to identify the physical Name of the destination, ie. the filename of the outgoing file on the response.

 

SQL Destination


This is the essence of CSV importing at its greatest. The SQL destination identifies that the SOURCE is an incoming CSV formatted file. If it is not – this will not work as planned. You then have a number of options to pick through for the CSV file, its destination, and the mapping to utilize.
First Row Contains column names – check this box if the file contains the headings at the top, used to skip the first row, but allow the developer to map the records columns by name

Run as a Process


This is a combination of two values, and for full understanding, you will want to review Demonstration Four : CSV Imports. Essentially – if you are inserting a large number of records, the standard CSV import routines would probably take longer than the allotted time for the request and you would end up with an ugly timeout error. If you check this box, the import process spins off a separate thread and runs the import from there, keeping track of the status in an action variable which you can pull from in an automatic fashion. The demonstration does this with a friendly status bar and record count in real time – so a very good review. In general you have three options with the Name at runtime. 

  • Name -  The name of the variable to use in order to gain access to the current runtime status of the import – these can be accessed in the following ways.
    • [Name.Complete,Action] – Returns a true or false indicator that the action has completed. You must always check this before checking the percentage and status. If the task has completed, and you already popped the status and percentage off the stack, the complete will return false.
    • [Name.Status,Action] – Returns the number of records processed thus far in the CSV file.
    • [Name.Percent,Action] – Identifies the percentage of completion for the process. The sample demonstrates a real-time progress bar for this.
    • [Name.isSuccessful, Action] - returns True or False. Indicates if the import was performed successfully.

If you set Process Name, then it executes on a separate thread.  You’d then setup a 2nd OWS for the progress bar, and refresh automatically and report on [<ImportName>.Percentage,ACTION]

Column Mapping


The SQL Column mappings allows you to control how the CSV Columns map to variables consumed within the Destination SQL Query. IT MUST BE UNDERSTOOD that these placeholders within the destination query are replaced by standard SQL values, with formatting depending on the outgoing data type specified here. For instance, a Number will be replaced directly, but a Text value will be encased in single quotes. Additionaly, the convention of naming the variables is completely up to the developer, and does not need to following any standard syntax – it’s a simple find and replace methodology.

To begin, simply press the familiar footer button, Add Column Mapping – then assign the following values.

  • Position – Optional, either the Name or Position is required. This identifies the Index (zero based) of the column. So if you want to always use the first column (0), set that here. The value will be pulled from that index within the current row.
  • Name – Optional, either the Name or Position is required. This identifies the Name of the column to pull the value from. This can only be possible if the First Row contained column names, otherwise there is nothing to map against. If the third column is “TabType”, you can simply put “TabType” here and assign the mapping directly.
  • Target – the target text that will be replaced within the destination for instance, if the Target is specified as “@TabType” anywhere “@TabType” appears in the destination query – the actual value of the row will be replaced.
  • Type – identifies the type of incoming variable. This is a simplistic Type checking method, to avoid complications within CSV data scrubbing or errors on invalid formatting conversions from Text to Integer. Choose a simply type here: Number, Decimal, Text, Date, Time, DateTime and the action will automatically “correct” the value based on the Default setting.
  • Format – A specific format to use for formatting the Value. Use standard formatters supplied within OWS – Like {0:C} for currency. This is not used very often because in most cases, the Type suffices.
  • Default – The value to use whenever the Type verification fails. For instance, if I am trying to convert “ABC” to a number, the verification for Number will fail, and I will use the default value. In this case lets assume “0”.
  • Null – Each CSV format may vary on what represents a Null value for a column. For instance if you are importing a numeric value, and determine that -1 should be mapped to NULL and will therefore be NULL in the Destination statement.
    Destination – The destination is the query to execute “PER ROW” from the incoming CSV file, with the appropriate Target values in place. For example:

INSERT INTO myTable(MyID,MyName,MyDescription)
VALUES (@MyID,@MyName,@MyDescription)

Transformation


This controls additional transformations on the file, which is either Image  transformation or File manipulations:

Image


Image transformation allows you to control the scaling of the target image or drawing text as a target image.

Resize

Width/Height: Setting the Width or Height variables identify the actual size to use on either the Width or Height. When both are provided, the resulting image will be stretched to fit the dimensions, regardless of the aspect ration. However, when only ONE of the two are specified the other will automatically set to the correct ratio value. When the incoming image is smaller than the target image in both width and height, the resulting image will remain the same size, and no scaling will occur. Finally – you can specify either a fixed pixel size or a variable percentage size for the width and height values.

Quality: When dealing more specifically with Compression based algorithms, like JPEG, the Quality of the image identifies the percentage of quality. The higher the quality, the less the loss in the algorithm. In the above screenshot - 90% is the quality. The value can range from 1 through 100 percent.

Draw Text

Generating a file which contains the text image is provided in the samples attached to this article. The ability to generate a textual image on the fly can be useful.

Font Family: sets the choice of font to be used to generate the image. This font MUST reside on the server, and ANY font on the server can be used.

Font Size: the size of the image will be automatically calculated based on the Width of the String to be rendered and the Height of the image based on the Font Size

Fore Color: the color to use for the Pen writing the Text into the foreground of the image.

Background Color: the color to use to fill the background color of the image.

File


You may choose one of the following options for handling the Destination and Source files. This only works against files when both the Source and Destination are Paths.

  • Copy – Source to Destination
  • Move – Source to Destination
  • Delete – Deletes the Source file.
  • Compress - Compresses the Path into a file
  • Decompress - Decompresses the source into the directory

Interaction

When interacting with Form variables, please note that you can access the incoming information about the form variable through a few extended OWS tags. Assume that the name of the incoming form field is frmFile.

File Path


[frmFile.Path,Form] – returns the full directory name of the file that is received through the form, from the source machine.

File Full Name


[frmFile.Name,Form] – returns the full file name, including the extension of the file.

File Name


[frmFile.NameOnly,Form] – returns the name, without the extension for the file.

File Extension


[frmFile.Extension,Form] – returns the extensions of the file.

File Type


[frmFile.Type,Form] – returns the MIME type (discussed in the appendix)

File Length


[frmFile.Length,Form] – returns the physical byte length of the incoming file.

For Images Only

[frmFile.WIDTH,Form] (Image Width) 
[frmFile.HEIGHT,Form] (Image Height) 
[frmFile.RAWFORMAT,Form] (Image Format) 
[frmFile.PIXELFORMAT,Form] (Image Format) 
[frmFile.DIMENSIONS,Form] (Image WidthxHeight) 
[frmFile.VERTICALRESOLUTION,Form] (Image Vertical Resolution) 
[frmFile.HORIZONTALRESOLUTION,Form] (Image Horizontal Resolution)

Average (2 Ratings):
 
Want to help out?
 
 

New York, NY • Baltimore, MD • Vienna, VA • St. Louis, MO • Seattle, WA • 410.327.0007 • info@R2Integrated.com

Bookmark & Share Bookmark and Share