File Management How To's

From Pengower
Jump to: navigation, search

Learn how to create, edit, store, upload, etc different files in your application.

This functionality is implemented as a set of ‘Do Script Actions’ but because of the significance of the functionality they have been collected together and described here in a separate section.

How to create a file

From version 4.0 of the script engine, it is possible to create, delete and modify files that are stored as attachments on objects. It is also possible to convert these files between different file types.

This functionality is implemented as a set of ‘Do Script Actions’ (see above) but because of the significance of the functionality they have been collected together and described here in a separate section.

There exists a file script variable type which is a wrapper around a file saved onto the hard disk of the server where the Pengower Platform is implemented. The association between the file variable and the physical file is masked from the developer and they need not concern themselves with the exact physical representation of the file – they manipulate the file through a sequence of Do Actions incorporating the file variable as a parameter. The first key exercise is to be able to create a file. The syntax for file creation is as follows:

Set file = Do Create File Params Name = "[file name]", Type = "[type]"

where [file name] represents the name that you wish to give to the file (i.e. the name of the physical file on disk) – this should not include any path information but should include any file type suffix e.g. .csv; and [type] is the type of file to be created. The supported types are:

TXT - basic text file including csv type files HTM - html files RTF - files conforming to rtf (rich text format) specification DOC - files for use with MS Word PDF - file for use with Adobe Acrobat XML - xml based files BIN - binary files including images (gif, jpeg etc.)

Example:

Set file = Do Create File Params Name = "people.csv", Type = "TXT"


How to write to a file

From version 4.0 of the script engine it is possible to create, delete and modify files that are stored as attachments on objects. It is also possible to convert these files between different file types.

This functionality is implemented as a set of ‘Do Script Actions’ (see above) but because of the significance of the functionality, they have been collected together and described here in a separate section.

There are 2 commands that permit the writing of data into a file – Write and Write Line. Note, only files that have been created through the Create File command can be written to – files accessed off existing items (i.e. existing attachments) cannot be modified, nor can files created through conversion be modified. In cases where you wish to append data – create a new file – read contents from old file (see below) – write the contents into new file – write additional contents into new file.

The Write command will write the contents of a string variable into a file. The syntax is:

Do Write Params File = [file var], Content = {[string var] | "[string]"}

where [file var] is a file variable created with the ‘Create File’ Do Action and, ‘Content’ is either a string variable or a literal string.

Example:

Set file = Do Create File Params Name = "people.csv", Type = "TXT"
Set str = "This is a string"
Do Write Params File = file, Content = str
Do Write Params File = file, Content = "more content"

Note you are only able to write to files of type; TXT, HTM, RTF and XML.


How to add a file into an Object

From version 4.0 of the script engine it is possible to create, delete and modify files that are stored as attachments on objects. It is also possible to convert these files between different file types.

This functionality is implemented as a set of ‘Do Script Actions’ (see above) but because of the significance of the functionality they have been collected together and described here in a separate section.

Once a file has been created and populated with content the next thing to do is give it a permanent home (if appropriate) by adding it to and Attachment element on an existing item. This is completed through use of the ‘Add File’ command. The syntax for the ‘Add File’ command is:

Do Add File Params Object = [object var], Element = "[element name]", File = {[file var]|[array var]}

where parameter ‘Object’ is the item to which the file should be added and should be an object variable; parameter ‘Element’ is the name of the meta structure element to which the file should be added and can be a string literal or a string variable and; parameter ‘File’ is the file variable that is to be added as an attachment to the Element of the Object.

Example:

Set file = Do Create File Params Name = "people.csv", Type = "TXT"
Set str = "This is a string"
Do Write Params File = file, Content = str
Do Write Params File = file, Content = "more content"
 
Set perArr = Get "Person" Where Name = "Andrew"
Set per = perArr[1]
Do Add File Params Object = per, Element = "Docs", File = file
Do Store Item Params Item = per
 
Output = per
Return_Ok


How to remove file attachments

From version 4.0 of the script engine it is possible to create, delete and modify files that are stored as attachments on objects. It is also possible to convert these files between different file types.

This functionality is implemented as a set of ‘Do Script Actions’ (see above) but because of the significance of the functionality they have been collected together and described here in a separate section.

Attachments can also be removed from an object should that be called for. They are removed using the Do Action ‘Remove File’. The syntax for ‘Remove File’ is:

Do Remove File Params Object = [object var], Element = "[element name]", File = "{[file name>|All]}"

where parameter ‘Object’ is the item from which to remove the file, parameter ‘Element’ is the name of the element from which to remove the file and can be a string literal or a string variable and; parameter ‘File’ is either the name of the file to be removed (including any file type extension) in the form of a literal string or string variable or the word "All" which will remove all attached files.

Example:

Set perArr = Get "Person" Where Name = "Andrew"
Set per = perArr[1]
Set fname = "cv.doc"
Do Remove File Params Object = per, Element = "Docs", File = fname
Do Remove File Params Object = per, Element = "Docs", File = "All"


How to access attached files

From version 4.0 of the script engine it is possible to create, delete and modify files that are stored as attachments on objects. It is also possible to convert these files between different file types.

This functionality is implemented as a set of ‘Do Script Actions’ (see above) but because of the significance of the functionality they have been collected together and described here in a separate section.

A key aspect of script file management is access to existing attachments. This is completed with standard action script syntax and variable assignment. The attachment element of an object is assigned to a vary creating an ARRAY of file variables (even if only one attachment exists an array will be returned as in the case of relationships). The syntax is:

Set [arrary var] = [object var]{"<element name]"}

Example:

Set cvArr = per["Documents"]
Set cv1 = cvArr[1]


How to identify file attachments

From version 4.0 of the script engine it is possible to create, delete and modify files that are stored as attachments on objects. It is also possible to convert these files between different file types.

This functionality is implemented as a set of ‘Do Script Actions’ (see above) but because of the significance of the functionality they have been collected together and described here in a separate section.

To make other actions such as file removal and file access possible it is important to be able to identify the names of the physical files associated with the file variables. This task is completed through the ‘File Name’ Do Action. The syntax for the ‘File Name’ action is:

Set [string variable] = Do File Name Params File = [file var]

where parameter ‘File’ is the file variable whose name is required.

Example:

Set fArr = per["Documents"]
Set f1 = fArr[1]
Set fName = Do File Name Params File = f1
 
Output = fName
Return_Ok


How to read data from files

From version 4.0 of the script engine it is possible to create, delete and modify files that are stored as attachments on objects. It is also possible to convert these files between different file types.

This functionality is implemented as a set of ‘Do Script Actions’ (see above) but because of the significance of the functionality they have been collected together and described here in a separate section.

In addition to accessing attachments on objects it is possible to read the content of these files in the case where they conform to one of the following types of file:

TXT RTF XML HTM

The reading of data from file can be completed via the Do Actions ‘Read’ or ‘Read Line’. The syntax for the ‘Read’ action is:

Set [string var] = Do Read Params File = [file var]

where parameter ‘File’ is the file variable form which the contents are to be read. ‘Read’ reads all the data from within the file from the current position within the file to the end (see read line for further details of partial reading). Note, ‘Read’ should be used with care as attempting to use ‘Read’ on incorrect file types or very large files may cause problems.

Example:

Set fArr = per["Documents"]
Set f1 = fArr[1]
Set outStr = Do Read Params File = f1
 
Output = outStr
Return_Ok

The ‘Read Line’ command operates in a similar way to the ‘Read’ command except that it reads the next line from the file – i.e. from the current position to the next carriage-return. The syntax for the ‘Read Line’ command is:

Set [string var] = Do Read Line Params File = [file var]

where parameter ‘File’ is the file variable form which the contents are to be read. ‘Read’ reads from the current position within the file to the next carriage-return.

Example:

Set fArr = per["Documents"]
Set f1 = fArr[1]
Set outStr = Do Read Line Params File = f1
 
Output = outStr
Return_Ok


How to convert files

The final aspect of script file management allows for the conversion of physical files associated with a file variable to a different type of file, e.g. turning an html file into a pdf file. The process creates a new file variable that maps to the converted physical file. The physical file will be of the same name as the original file but with the extension modified.

This functionality can be used in conjunction with the content editor, custom forms and mail merge type functionality to create word documents or pdfs which can subsequently be downloaded or emailed.

The following table shows the range of permissible conversions:

    TO            
    BIN DOC HTM PDF RTF TXT XML
FROM BIN              
  DOC     Yes Yes Yes Yes  
  HTM   Yes   Yes Yes Yes  
  PDF              
  RTF   Yes Yes Yes   Yes  
  TXT   Yes Yes Yes Yes    
  XML              

Thus if the start type is DOC you can convert it to HTM, PDF, RTF or TXT.

The conversion is executed through the ‘Convert File’ Do Action. The syntax for the ‘Convert File’ command is:

Set [file var] = Do Convert File Params File = [file var], Type = "[type]"

Where parameter ‘File’ is the existing files variable mapping to the file you wish to convert and; parameter ‘Type’ is a string variable or string literal indicating the type to which you wish to convert it. The command will return a new file variable mapping to the converted physical file. This in turn can then be added to an item or form an attachment for an email.

Example:

Set perArr = Get "Person" Where Name = "Andrew"
Set per = perArr[1]
Set cvs = per["Documents"]
Set cv = cvs[1]
Set pdfCv = Do Convert File Params File = cv, Type = "PDF"
 
Do Email Params To = to, From = from, Subject = "CV for Andrew", Body = "CV", Attachments = pdfCv
Return_Ok