About this plugin
This plugin allow you to open, write and perform other operations on PKZIP-compatible files. You can add files, extract files, and make other operations on one or more zip files at a time. And with all the control with the plugin provided events.
The plugin is intended to allow you to compress and decompress zip files from your publication in an easy way, offer actions to open, save, close, add, extract, abort operations, and more. And also provide a lot of subroutine events for every zip operations needs.
Thirparty
This plugin are imposible without the aid of this people:
Thanks a lot!
This action creates a new instance of an Zips object. The result variable store the ID of the new Zips object. You can use this ID with other plugin actions.
This action destruct a previously created Zips object instance. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Open a Zips object instance zip file or create it if not exists. This action prepare a zip file in order to add or extract files of them, for example. Even the zip file is open for your publication cannot be removed: only when you close the file (see npZipsClose) or your publication exit.
You need to open a zip file before call other plugin actions, like to add or extract files. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Updates a Zips object instance zip file on disk. This action save the contents on disk of a previosly opened zip file (see npZipsOpen). Note that various plugin events are fired if needed. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Close (and save to disk if needed) a Zips object instance previously open zip file. See also npZipsOpen. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Add one or more files to the open zip file of an Zips object instance. This action can be combinated with npZipsBaseDir. You can add files using file mask and fully qualified dir paths, but, if you use the Zip Base Directory, then you can add files using relative paths to the Zip Base Directory. For example:
. This action add TXT files from C:\MyDir\ npZipsAdd "[ZipsID]" "C:\MyDir\*.txt" "" "[Result]" . Now we use a Base Directory npZipsBaseDir "[ZipsID]" "C:\MyDir" "[Result]" . This action also add TXT files from C:\MyDir\ npZipsAdd "[ZipsID]" "*.txt" "" "[Result]" . And this add BMP files from C:\MyDir\ too npZipsAdd "[ZipsID]" "*.bmp" "" "[Result]"
This action also allow you to exclude files using file masks. So we can write something like this:
. Use a Base Directory npZipsBaseDir "[ZipsID]" "C:\MyDir" "[Result]" . This action add TXT files but not BMP files from C:\MyDir npZipsAdd "[ZipsID]" "*.txt" "*.bmp" "[Result]"
Also note that when you add files to a opened zip file, this are not save to the disk before you call npZipsSave or npZipsClose. Finally the result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Extract one or more files from an open zip file of an Zips object instance. This action must be be combinated with npZipsBaseDir. In fact, the extracted files are put into the Zip Base Directory and subdirectories. If the directory not exists the plugin try to create it. You can extract one or more files at a time using file masks. For example:
. Extract the files to C:\MyDir npZipsBaseDir "[ZipsID]" "C:\MyDir" "[Result]" . Extract TXT files npZipsExtract "[ZipsID]" "*.txt" "" "[Result]" . Or just extract all files npZipsExtract "[ZipsID]" "*.*" "" "[Result]"
Also you can exclude files to be extracted using file masks, for example:
. Extract the files to C:\MyDir npZipsBaseDir "[ZipsID]" "C:\MyDir" "[Result]" . Extract TXT files and exclude BMP files npZipsExtract "[ZipsID]" "*.txt" "*.bmp" "[Result]"
Finally the result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Extract an item from a Zips object instance zip file specifying the item index or the file name of the item. You can specify an item index or an item file name to be extracted. As the new name you can specify a full path or an empty string: in this case the plugin store the file with using their name on the "Zip Base Directory". The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Please, note that this action can take some time if executing over zip files with thousands of files.
Delete one or more files from an open zip file of an Zips object instance. You can provide a file mask to delete the files, and another to exclude files to be deleted. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Delete one file from an open zip file of an Zips object instance. You can provide the index of the file (obtained for example with npZipsFindFile action) or a file name. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Find for files on a Zips object instance zip file. The result variable store the zip item file index or "-1" if not found. You can use this item index along with some other plugin actions, like npZipsExtractAt and npZipsItemInfo. Also the [LastError] variable can contain information about some possible error.
Get information of one item stored on a Zips object instance zip file, based on their index or file name. The result variable store an array with information about the zip item, or "False" in some error occur. The [LastError] variable contain information about the error.
Here is the items that you can found on the result variable when success:
(1) The compression method can be one of the following values: cmStored, cmShrunk, cmReduced1, cmReduced2, cmReduced3, cmReduced4, cmImploded, cmTokenized, cmDeflated, cmEnhancedDeflated, cmDCLImploded, cmBzip2, cmLZMA, cmIBMTerse, cmLZ77, cmJPEG, cmWavPack, cmPPMd.
(2) The deflation option can be one of the following values: doFast, doNormal, doInvalid, doMaximum, doSuperFast, doUnknow.
(3) The dictionary size can be one of the following values: ds4K, ds8K, dsInvalid.
Retrieve a list with the items file names inside a Zips object zip file. The file list variable store a zero indexed NeoBook array with the zip file items file names. The files count variable store the number of items on the file list variable. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Please, note that this action can take some time if executing over zip files with thousands of files.
Retrieve a list with the items information inside a Zips object zip file. The file list variable store a zero indexed NeoBook "array of array" with the zip file items information. The files count variable store the number of items on the file list variable. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
See the npZipsItemInfo action for more details: every item on the file list variable contain an array with the information that you can get using the refered npZipsItemInfo action.
Please, note that this action can take some time if executing over zip files with thousands of files.
Get the comment from an Zip object instance zip file. Specify the ID of a Zips object instance previosly created an opened. The result variable store the comment of the Zip file, if exists, or an empty string if not. The result variable also can store "False" if an error occur. The [LastError] variable contain information about the error.
Set the comment of a Zip object instance zip file. Specify the ID of a Zips object instance previosly created an opened and the comment you wanted to set for the zip file. The result variable store "True" if everything is OK, or "False" if an error occur. The [LastError] variable contain information about the error.
Set the compression method and deflation option to use on a Zips object instance when add/store files. The below list show the available compression methods that you can use when compress a zip file:
When you use "smDeflated" or "smBestMethod" you can also use one of the following deflate options:
The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set the base directory of a Zips object for add/store, extract and other Zip file operations. For more information see npZipsAdd and npZipsExtract actions. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set the password and password retries options to an Zips object instance. You can use this action both when add and when extract files to or from a zip file. If you determine a password when adding files, then the zip file is encrypted using the provided password. If you determine a password when extract files, then the plugin try to decrypt the zip file using the provided password.
This action allow you to set the password retries number when the plugin try to extract an encrypted zip file. In this case also a "Need Password event" is fired, and you can provide the needed password here, just the number of times that retries number allows. See the npOnZipsNeedPassword action for more information.
The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Specify the add/store options on a Zips object instance. You can set the following add/store options:
The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Specify the extract options on a Zips object instance. If you use "eoCreateDirs", directories (including multiple levels of subdirectories) are created as needed to extract files. If use "eoRestorePath", path information stored in the archive is retained when files are extracted.
The extracted file is placed in the appropriate subdirectory relative to the current Zip Base Directory, see npZipsBaseDir. The following list shows the possible values that can be used:The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed when a Zips object instance zip file contents are loaded. You can use this event to display the name of the current zip file or to update a most-recently- used zip archive list. The instance ID variable contain the ID of the Zips object that fire the event.
The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed when a Zips object instance zip file are saved. This event can be used along with the npOnZipsItemProgress to display status information for the user. For example, in the npOnZipsItemProgress event subroutine, the status could be set to "change pending", and in the "OnZipsSave" event subroutine, set the status to "saved".
The instance ID variable contain the ID of the Zips object that fire the event. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed when a Zips object instance zip file operation is aborted by the user. You can allow the user to abort certain zip file operation (see the below plugin events), well, this subroutine event is called when the user abort a zip operation.
The instance ID variable contain the ID of the Zips object that fire the event. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed when a Zips object instance zip file contents are changed. "OnZipsChange" is called when the contents of a zip file change (immediately after an add files and other operations) or when a property of an item in the archive changes. The "OnZipsChange" event can be used to update any components that display the contents of the archive or information relating to the archive (e.g., the number of files in the archive).
The instance ID variable contain the ID of the Zips object that fire the event. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed when a Zips object instance process steps through the archive. "OnZipsProgress" is fired during the extract files, save zip file and other operations. This event can be used to display the progress of the operation, or even to abort the operation. The Progress variable store a number from 0 to 100, wich indicate the progress percentage of the operation. The zip file name variable contain the path of the current zip file (if any). You can abort the operation setting to "True" the Abort variable into the subroutine. See also npOnZipsAbort.
The instance ID variable contain the ID of the Zips object that fire the event. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed when a Zips object instance make long operations on a single archive item. "OnZipsProgress" is fired by add, extract and other operations on an zip file item. You can use it to display the progress of the operation, or even to abort the operation. The Progress variable store a number from 0 to 100, wich indicate the progress percentage of the operation. The zip item file name variable contain the path of the current zip file item in process. You can abort the operation setting to "True" the Abort variable into the subroutine. See also npOnZipsAbort.
The instance ID variable contain the ID of the Zips object that fire the event. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed when a Zips object instance need a password to decrypting a zip file. The "OnZipsNeedPassword" is called when the plugin need a password to decrypt a zip file. If you know the zip password you can use npZipsPassword. Buy if you dont know the password you can use this event to provide one. Simply set the Password variable with the zip apropiate password and the plugin try to decrypt the file using it.
The instance ID variable contain the ID of the Zips object that fire the event. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed before a Zips object instance save a zip file. If you dont provide a subroutine to this event, the plugin confirm the zip file save. So this event subroutine is optional and can be used to allow the user to close an archive without saving changes, for example. You can confirm the save operation setting the Confirm variable to "True" (or "1", or "Checked") into the subroutine. If you provide a subroutine for this event and dont set the Confirm variable to "True", then the operation is aborted.
The instance ID variable contain the ID of the Zips object that fire the event. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed when a Zips object instance output file for an extract operation already exists. This event is fired when a extract operation found an item to extract that already exists. If you dont provide a subroutine for this event, the plugin overwrite the file without warning. The item file name variable store the name of the item that can be overwritten. You can provide a new name for the file on the New File Name variable and set the Confirm variable to "True" (or "1", or "Checked") in order to continue extracting files. If you provide a subroutine for this event and dont set the Confirm variable to "True", then the operation is aborted.
The instance ID variable contain the ID of the Zips object that fire the event. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
Set a publication subroutine to be executed before a Zips object instance output process is performed on each item in the zip file. This event is fired once for each item in an add files, extract files and other zip operations. The Zip item file name contain the file name of the item to process. The Operation variable can store of the following values:
If you dont provide a subroutine for this event, the plugin confim the item proccess without warning. You can confirm the operation setting the Confirm variable tu "True" (or "1", or "Checked"). If you provide a subroutine for this event and dont set the Confirm variable to "True", then the operation is aborted.
The instance ID variable contain the ID of the Zips object that fire the event. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error.
All the NeoPlugins deal with errors in the same way that NeoBook does: when the plugin found an action error the [LastError] variable store information about the error, so you can take care about this variable when execute an action.
But all the NeoPlugins also incorporate an advanced way to deal with possible action errors. You can define a subroutine named OnNeoPluginActionError in order to be executed when some action error are found and you can use this variables inside:
Note that this error handling subroutine are shared for all the NeoPlugins, so you no need to specify a subroutine for every plugin you use in your publication because the same subroutine are recognized and automagically used by every NeoPlugin. Below you can view a sample of this subroutine code:
:OnNeoPluginActionError AlertBox "NeoPlugin Error" "Error [LastError] in plugin: [PluginName]" Return
Also note that the use of this NeoPlugins error handling subroutine is completelly optional. You can continue using the [LastError] variable as usual and even use the both methods at the same time.