Tutorial: Using the Zip Plugin

Tutorial: Using the Zip Plugin

The Zip plugin handles compression and un-compression of files using the popular zip algorithm. For anybody who’s unfamiliar with zip files, the most common usage is when you need to group several related files into a “package” so it’s easier to move them around and share them with others. For example, if you contract a set of artwork from a designer, he/she can compress them into a zip archive and send them via email, Dropbox, etc. All of the artwork will be contained in that one file with the .zip extension, and when you open it locally, the file will “unzip” and all of the files will be available to you, exactly as the designer intended. Another use of zip files is to compress one large file into a smaller overall .zip file. The format and type of the original file will dictate the amount of compression achieved, but in virtually every instance, you’ll save valuable storage space.

Why is this important to mobile app developers? For one, you gain the ability to expand your app’s contents. You can create a zip file containing expansion art and sounds, download it into your app, unzip it, and use those assets. Secondly, you can now produce zip files which you can upload to web servers for distribution.

In today’s tutorial, let’s examine how to download a zip file from a web server, unzip the contents, and show a list of the files within.

Including the Zip plugin

To use the Zip plugin, first add it to the plugins table within settings of the build.settings file:

Next, in your main project code, you must require the plugin, similar to how you’d require a core Corona library or external Lua module.

That’s it! Now you’re ready to use the Zip plugin.

Implementing the plugin

Like many API calls in Corona, a callback function is required so that you can determine when the process is complete and then take the appropriate action.

Now, let’s use use the network.download() API call to retrieve the zip file from a remote server and, in its callback listener, initiate the unzip process. The callback function will list all files that are successfully uncompressed.

Let’s follow through the process step by step:

  1. When network.download() finishes, the networkListener function is called.
  2. After checking for and catching possible error conditions, create a table of options to pass to the Zip plugin. The zipFile and zipBaseDir will be given to you in the network.download() “event” table. Optionally, you can specify whether to unzip all files or just some files — see the documentation for details.
  3. Provide the destination directory as dstBaseDir and the zipListener function that you wrote (above) will handle the rest!

In summary

As you can see, using the Zip plugin is simple… just include the plugin in your build.settings file, set up a basic callback function, and pass a table of options to the plugin. For full details and instructions on how to use the zip.compress() and zip.list() APIs, please review the Zip plugin documentation.

Finally, before we conclude today’s tutorial, there are just a few more important points:

  1. Compressed zip files may contain executable code which can be problematic. Please do not open zip files from unknown sources, and keep your virus scanning software up-to-date.
  2. On iOS, since you are downloading easily retrievable data, Apple expects those files to go into the system.CachesDirectory.
  3. On Android, remember to enable Internet access as detailed here.

Rob Miracle

Rob Miracle creates mobile apps for his own enjoyment and the amusement of others. He serves the Corona Community in the forums, on the blog, and at local events.

  • Christian
    Posted at 22:06h, 21 May

    Great news! Will it support password protected zip files?

  • Rob Miracle
    Posted at 13:54h, 22 May

    I’m told it will in a future release, but not as of now.

  • Marc C
    Posted at 10:32h, 23 May

    Oh my goodness, this is wonderful news. Just got my app set up using the TAR module, but this will be the much better tool to use. Thank you for this!

    +1 on password protecting zip files as well.

  • Marc C
    Posted at 10:40h, 23 May

    I have read that Apple expects downloadable content to be stored in the system.CachesDirectory. But in my case, my users will be downloading a chunk of new content for my app, it will be about 20mb big. I can’t have my users have to redownload the content each time they restart theri device and the cache is cleared.

    I can’t just put this content in the DocumentsDirectory?

  • Juan
    Posted at 10:46h, 23 May

    Very usefull for me … nice!

  • Opie
    Posted at 05:09h, 25 May

    So with this you can have an app bigger than 50mb with no problems?

  • Peter
    Posted at 08:59h, 25 May

    Does this mean it would be possible to create an epub reader now?

  • Brian
    Posted at 11:20h, 27 May

    @Peter, that’s what I’m hoping to accomplish with it! Hoping to make an eTextbook app using epub now that we have this plugin.

  • Marc C
    Posted at 23:24h, 18 June

    This still isn’t of much use because we can’t protect our zip files with passwords.

  • Terry
    Posted at 14:07h, 20 October

    The documentation should be updated to reflect the requirement to add something like this to your .lua file using the Zip plug-in:

    local zip = require( “plugin.zip” );