Description

Your Intuiface experience can write to and import data from a Microsoft Excel spreadsheet - stored in the .xlsx format - thanks to the Excel Interface Asset (IA). Each tab in a workbook - i.e. each spreadsheet - is represented by a unique Excel IA. See the image below.

The default visual representation of each Excel row is a horizontally oriented Group collection filled with either an Image or Text asset for each column. These Group collections are placed within a vertical Asset Grid collection to vertically represent all rows in the spreadsheet.

This feature is available on all Player-supported platforms. It is not necessary for Microsoft Excel to be installed on devices running Player. As for Windows PCs running Composer, it is only necessary to install Microsoft Excel if you need to directly edit the contents of worksheets in an Excel workbook.

Video demo

Have a look at the video below to see how the Excel interface asset works and how you can change the data template used to display the contents of each row.

How to create an Excel spreadsheet for use within Intuiface

Here are the rules to respect when creating a spreadsheet within Microsoft Excel:

• Each spreadsheet must represent a single data table. If you have multiple data tables to represent, use one spreadsheet per table.
• The first row of each spreadsheet must contain the column names of your data structure. These names will appear as properties and action parameters associated with your worksheet in Intuiface. Each column name must be unique; no repeats. The column title shouldn't be a number only.
  • The value in the second row - i.e. in the first row of data - indicates which type of data the column has. If blank, Intuiface will consider the data as text. For example, a numeric value will tell Intuiface that the rest of the column will contain numbers. This is particularly helpful when using "Update cell" to compute formulas.
• Every row other than the first must represent one item in your data table. There should be no blank rows in the middle of your list.
• The name of the spreadsheet must contain at least one character. A spreadsheet with a name comprised only of numbers will not import successfully.

Here are the spreadsheets used in our webinar "Connect Your Intuiface Experiences To External Data Using Excel and API Explorer". You can reuse / enhance / modify them.

• Gallery Photos: Create a Gallery-Photos folder next to your Excel workbook. In that folder, put images referenced within the workbook.
• Product Catalog Template: Create an Images folder next to your Excel workbook. In that folder, put images referenced within the workbook.
• User form: Add as many columns as you need to create your form fields.

How to import an Excel spreadsheet

To import an Excel spreadsheet, you can either:

• From the Interface Assets panel, click the Add an Interface Asset button, click Excel, then browse your PC's file system to select your Excel workbook. This will create an interface asset for each spreadsheet in the workbook.
  OR
• Drag-and-drop the Excel workbook from File Explorer into Composer.
  • A drag & drop on any of the Composer panels will create Excel interface assets for each spreadsheet within the workbook.
  • A drag & drop on the scene will both create Excel interface assets for each spreadsheet and will create a default visual representation - a [data template[(/kb/interface-assets/data-template-for-collections-populated-by-interface-assets) - for each spreadsheet.

If your Excel spreadsheet references graphic media stored locally, such as images placed in a folder located next to the Excel workbook, drag & drop the Excel workbook and the folder containing your media files at the same time. Everything will be imported correctly into your Intuiface project. See this section below for a detailed discussion about referencing external media from within an Excel spreadsheet.

How to update an already imported Excel spreadsheet

For Composer

When importing an Excel spreadsheet into Composer, the corresponding Excel workbook is copied into a sub-folder of your Intuiface project. You can easily locate your Excel file or even edit it in Excel using the context menu of the Excel interface asset in Composer. Right-click any Excel interface asset in the Interface Assets panel and select either Edit in Excel or Open file location.

Note:

• The Excel interface asset - and associated data templates - will update within five seconds after the Excel workbook is saved and closed in Excel.
• Microsoft Excel must be preinstalled in order to edit Excel spreadsheets. Intuiface does not include a workbook editor.

When your Excel workbook is opened in Microsoft Excel, perform any changes described below. In all cases, you need to close the file in MS Excel for the changes to be recognized by Composer.

• add or remove rows: all existing bindings will be preserved.
• add or remove a column: New properties corresponding to new columns will appear. Bindings to removed columns will be lost.
• add a new sheet: a new Interface Asset corresponding to this sheet will be created.
• rename a column or a sheet: all existing bindings on modified columns / sheets will be lost.
• remove a sheet: all existing bindings for the removed sheet will be lost.

For Player on Windows

You can find the Excel files within the Intuiface project in the subfolder Files\InterfaceAssets\[ExcelFileName]_xlsx. You can open the Excel file and add or remove rows but you should not change the structure (column / sheets) of the Excel file for the Experience to remain working properly.

You can also replace the Excel file with a new one, provided they have the same structure (column / sheet names).

The modified spreadsheet must be both saved and closed for changes to be taken into account by Intuiface. Changes are recognized by Intuiface approximately five seconds after closing the workbook.

NOTE: Exclusive to Composer and Player on Windows, there are a variety of ways to manage the Excel spreadsheet and associated media outside of an experience. With this approach, you can update a single instance of Excel and have those changes mirrored in all deployed instances of your project.

For Player on all platforms other than Windows

The ability to directly update an Excel spreadsheet on iPad, Android, BrighSign, Chrome, and Samsung SSP devices is not supported. To update the spreadsheet for these Players, make the changes using Composer - see the previous section - and then redeploy the experience.

Properties, Triggers & Actions

Referencing Media Files

You can reference a Web-hosted or local image, video, PDF document, 3D model, or audio file in an Excel spreadsheet cell.

• For a Web-based file: simply enter the media URL in the Excel cell. You can see this approach in the video at the top of this article. An example URL: http://content7.flixster.com/movie/11/16/93/11169357_pro.jpg
• For a local file: you should use a relative path, such as image/MyImage.png, with the in-project location of your Excel file as the starting reference point. See this note below for more information about where the spreadsheet is stored in your experience.
  Although you can use an absolute path like c:/temp/myImage.png, this is not ideal because 1) each absolute path must exist on all PCs running the Player, which can be hard to enforce, and 2) absolute paths are not supported in Player for Tablets or Player for Kiosks.

We highly recommend using relative paths to make your experiences easier to deploy across multiple devices. A best practice is to create a media folder next to your Excel file located in {Project_Folder}\Files\InterfaceAssets\{YourExcelName_xslx}. Give this folder any name you wish. For example, "image". You can then enter the following path in your Excel cells to reference an image: image/MyImage.png.

For most Player-supported platforms, path references are case-sensitive. Record the path/folder names exactly as they appear in your project.

The following image illustrates how to reference an image file in an Excel spreadsheet.
(click to enlarge)

Important Notes

1. What Composer refers to as Row #1 in your spreadsheet is actually the 2nd row. This is because the first row contains column names.
2. When selecting an Excel workbook while creating an Excel Interface Asset, the corresponding .xlsx file is copied and placed into your project at the following location: C:\[Project_Path]\[Project_Name]\Files\InterfaceAssets\[Excel_Filename]_xlsx
   As a result, all modifications performed by third-party services must be applied to this local copy. (The Add row action also operates on this local copy.) The original file is not monitored by Composer or Player.
3. When modifying the local copy of your Excel workbook - either manually or via an external service - the workbook must be both saved and closed before changes are taken into account by Intuiface. Changes are recognized by Intuiface approximately five seconds after closing the workbook.
4. .xlsx files output by other spreadsheet software, such as LibreOffice, are not supported. You must use Microsoft Excel 2007 or later.
5. Do not use "State" or "Row" as a column name. These are reserved words.
6. Only PDF documents can be read from an Excel reference. Intuiface will not read Office documents referenced in Excel.
7. The name of a spreadsheet must contain at least one character.
8. If you are using Excel formulas, please make sure to carefully read this "how to" article.
9. Avoid having any blank space or incorrect format in cells containing email addresses, as it will result in the error message "Excel file is already opened" when first opening the experience.
10. Use the correct cell format in your columns, especially when using the "Sort" action. Setting the format to General will work most of the time, though.
11. Always use/ instead of \ for file paths referenced in Excel when building experiences for Player on platforms other than Windows.
    For example: images/image01.png instead ofimages\image01.png. The latter may cause loading errors on non-Windows devices.

Experience Samples

If you want to rebuild the experience in the above video on your own, you can download the Excel file used in the video from here.

In Composer's Experiences panel, you will find - in the Samples tab - several examples using the Excel Interface Asset as a data source:

• DIY Shopping Catalog
• Restaurant Menu
• Endless Aisle
• Interactive Maps
• Photo Exhibition (designed for iPad and Android tablets)
• Local attractions (portrait mode)

Limitations

• No support for xlsx files generated using Google Sheets, OpenOffice, and LibreOffice. When trying to use such files, unrelated error messages might be displayed.
• Blank spaces in Excel spreadsheet names are not supported when using Excel formulas. Blank spaces in spreadsheet names also negatively impact bindings on cells that reference content in other spreadsheets.
• Saving an Excel directly after using Ctrl+Down Arrow (placing focus on the last possible row of the spreadsheet) will have a massive, negative performance impact when saving or opening the experience. This is because blank indexed cells (which are read by Intuiface) are generated after using this type of operation.
• Adding comments to imported Excel worksheets might cause errors after using an "Update cell" action.
• Avoid naming worksheet columns as "Name" as this can break the data feed for those columns.
• Column content will not be displayed on "Player for other devices than Windows" if the column's table head contains line breaks.
• If the first cell in a column is empty, the column will be interpreted as text not numbers.

Alternatives

If Excel doesn't really suit your needs, you may want to check out these alternatives:

• Intuiface Headless - CMS
• Airtable