Tutorial: Introducing the Quick Look plugin (iOS)

magnify
Share on Facebook0Share on Google+0Tweet about this on TwitterShare on LinkedIn0

For iOS users, Corona SDK now offers the Quick Look Plugin which allows your app to show various document files, including:

  • iWork documents
  • Microsoft Office documents (Office97™ and newer)
  • Rich Text Format (RTF) documents
  • PDF files
  • Images
  • Text files whose Uniform Type Identifier (UTI) conforms to the public.text type
  • Comma-separated value (csv) files

Setup

You can include this plugin in your project by adding the following to your build.settings file:

plugins = {
    ["CoronaProvider.native.popup.quickLook"] =
    {
        publisherId = "com.coronalabs",
        supportedPlatforms = { iphone = true },
    },
}

Inside the app, the Quick Look plugin is called via native.showPopup(). It’s good practice to test that the device can show the popup by calling native.canShowPopup() in advance.

-- Check if the Quick Look popup is available
local popupIsAvailable = native.canShowPopup( "quickLook" )

Assuming the device is capable of showing it, just create a table of parameters and pass it to the native.showPopup() API:

if ( popupIsAvailable ) then

    local popupOptions = 
    {
        files =  -- Files you wish to load into the quick look preview
        { 
            { filename="sampleFiles/PDF_File.pdf", baseDir=system.ResourceDirectory },
            { filename="sampleFiles/Image_File.jpg", baseDir=system.ResourceDirectory },
            { filename="sampleFiles/HTML_File.html", baseDir=system.ResourceDirectory },
            { filename="sampleFiles/Text_File.txt", baseDir=system.ResourceDirectory }
        },
        startIndex = 1,  -- The file you wish to start the preview at; default is 1
        listener = quickLookListener  -- Callback listener
    }

    -- Show the quick look popup
    native.showPopup( "quickLook", popupOptions )
end

As you can see, the files table within the popupOptions table contains a list of files. This example illustrates how to show files in a sub-directory — in this case, files in the system.ResourceDirectory. If you are downloading files, or creating them yourself, you would likely access them in system.DocumentsDirectory or system.CachesDirectory.

In some cases, you will only need to show one file, but the plugin gives you the option of showing several files. It defaults to the first file in the list, but you can specify an alternate file by setting the startIndex parameter.

Callback listener

The Quick Look plugin also features an optional callback parameter which lets you know when the user is done viewing the document and what document was viewed last. Just specify your listener function as the listener parameter and handle the results as you see fit. For example:

local function quickLookListener( event )
    print( "name: ", event.name )
    print( "action: ", event.action )
    print( "type: ", event.type )

    -- event.file, filename and baseDir of the last file previewed
    if ( "table" == type( event.file ) ) then
        print( "event.file: {" )
        for k, v in pairs( event.file ) do
            print( k, ":", v )
            -- KEYS/VALS
            -- k = filename
            -- v = value
        end
        print( "}" )
    end
end

Share on Facebook0Share on Google+0Tweet about this on TwitterShare on LinkedIn0
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.

This entry has 19 replies

  1. Lerg says:

    Can we copy files to/from the app with iTunes? Like FileHub app and others.
    Such ability would make much sense with such plugin.

    • Rob Miracle says:

      I doubt the plugin provides this feature. I’ll ask engineering and see what I can find.

      Rob

    • Rob Miracle says:

      Have you tried adding:

      UIFileSharingEnabled = true

      To your iphone plist setting in build.settings?

      • Lerg says:

        Oh, it is that easy. Thanks!

  2. JCH_APPLE says:

    I ran a quick test (based on Rob’s sample) with 4 PDF files.
    The plugin has it’s own top navigation bar with options for printing, sharing by email and copying.
    You can also display the list of the filenames in “files =”.
    The position of the PDFs inside the viewer changes from one PDF to other (despite my pages have all the same size)
    The listener seems never been invoked.
    The rendering of PDFs is slow but the quality is very good.
    Same type of plugin allowing PDFs to be displayed as PNGs or JPEGs would be wonderful, especially for business apps.
    Plugin is announced in beta, no doubt that it will improve, it’s already a simple and efficient way to display high quality files with few lines of code.

    • Danny says:

      Hey JCH_APPLE.

      Can you elaborate more on “the listener seems never been invoked” ?
      Under what circumstances?
      Using the provided sample code?
      etc

      Thanks!

  3. Leo says:

    Hi,

    Is there a way to pass on a variable, which is generated outside of popupOptions as a part of folder/ file name ?

    What I’m trying to do is, basically there is a tableView list that contains categories, and when a user selects a row (category), it opens the Quick Look plugin, and open all the files that are contained within the selected category.
    Currently the plugin requires us to specify the folder/ file name within double quotation marks. This suggests it only accepts strings, but not variables.
    But I would like to specify the folder name dynamically based on the choice that user made prior to this screen.

    ————
    WORKS:
    ————
    local popupOptions =
    {
    files =

    {
    { filename=”Data/Dinner/item 01.pdf”, baseDir=system.ResourceDirectory },
    { filename=”Data/Dinner/item 02.pdf”, baseDir=system.ResourceDirectory },
    { filename=”Data/Lunch/item 01.pdf”, baseDir=system.ResourceDirectory },
    { filename=”Data/Lunch/item 02.pdf”, baseDir=system.ResourceDirectory },
    { filename=”Data/Breakfast/item 01.pdf”, baseDir=system.ResourceDirectory },
    { filename=”Data/Breakfast/item 02.pdf”, baseDir=system.ResourceDirectory },
    },
    startIndex = 1,
    }
    ————————-
    DOES NOT WORK:
    ————————-
    local popupOptions =
    {
    files =
    {
    { filename=”Data/” .. selectedFolderName .. “/item 01.pdf”, baseDir=system.ResourceDirectory },
    { filename=”Data/” .. selectedFolderName .. “/item 02.pdf”, baseDir=system.ResourceDirectory },

    },
    startIndex = 1,
    }

    Eventually I would like to apply a similar operation to file names as well, but here I only modified folder names for simplicity.

    Thanks!

    • Rob Miracle says:

      That should work. Have you tried printing out the values of selectedFolderName and make sure it’s what you expect and you don’t have extra characters like extra slashes? The filename is a string like you suspect.

      Rob

      • Leo says:

        It works now! Thank you very much, Rob. It was not extra spaces/ slashes etc. However, it’s started to work when I put all the variable names within quotation marks as if they are actual strings.

        BEFORE ( Wrong ) –folder name (variable) is not quoted.
        { filename=”Data/” .. selectedFolderName .. “/item 01.pdf”, baseDir=system.ResourceDirectory },

        NOW ( Correct ) –folder name (variable) is now in double quotation marks.
        { filename=”Data/” .. “selectedFolderName” .. “/item 01.pdf”, baseDir=system.ResourceDirectory },

        Leo

      • Leo says:

        Sorry, one more question; Just to make sure I understand correctly;

        >>>>The filename is a string like you suspect.>>>>

        So, it means I can’t apply a similar operation (pass on a string from variable elsewhere) to a file name.
        In other words, file names need to be hard coded actual texts, never a variable.
        Is my understanding correct?
        -Leo

      • Leo says:

        It looks like I spoke too soon there. Actually, it’s still not working, whether I include the variable within quotation marks.
        I’ve printed and double checked the variable name is spelled correctly.
        –If I do NOT include variable in quotation marks –> Stack traceback error at Corona Simulator
        –If I include the variable in quotation mark –> No error at Simulator –> when I test it on iPad, the file in question is not found and the next available item (all hard coded, no variable) is displayed. When I press on preview button, application closes itself.

  4. Rob Miracle says:

    This: filename=”Data/” .. “selectedFolderName” .. “/item 01.pdf” is going to produce the string “Data/selectedFolderName/item 01.pdf”. This is not what you want. Your original version is the correct way to do this. However, the values in the variable selectedFolderName have to be valid values.

    • Leo says:

      It turns out the problem was that of scoping. The variable and the value it self was fine but variable was not picked up at the location I wanted it to be. I played around with the forward reference and location within the code ( The section in question is now placed immediately after where the variable is defined ) a bit and it’s fixed now.

  5. gispub says:

    Hi,

    Thx for this great plugin.

    I found a bug on PDF when you are in fullscreen mode et go back to normal mode, there is a problem with statusbar.

    Furthermore, in my app status bar is hidden and appears all the same…

    Best regards.

    • Rob Miracle says:

      Can you produce a small sample app that demos the problem and then file a bug report using the Report a Link button above? The project should be complete with a config.lua and build.settings. Engineering needs this to diagnose the bug.

      Thanks
      Rob

  6. gispub says:

    Hi,

    I’ve send a bug report the january 15, 2014 and the bug doesn’t fixed.

    Thanks.

    • gispub says:

      Hi,

      Any answer for 2 month in spite of several asks by email… Could simply you tell me if you think of making anything or not?

      Best Regards.

      • Rob Miracle says:

        Do you have the bug ID #?

  7. gispub says:

    Case 30919
    Case 30848

Leave a reply

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>