User Manual

Import/Export

Import

Interface enables the wholesale import of any arbitrary number of content items, if it is structured in the right way. If you are using a package that was Exported using Interface, it can be Imported directly without any additional formatting. If you are trying to import data that was created in another program, you will have to convert it into the supported formats.

Import from CSV
If you are using a spreadsheet program that can export to CSV (comma-separated value) the process is very simple, but requires attention to detail. Even the slightest typo or error in formatting can cause the Import to fail. You can format a spreadsheet per these instructions and then export it to CSV.

Some specifics:

  • The CSV file you want to import must be named after a Model in your Interface system. For example, “Photograph.csv” for a Model called “Photographs.”
  • Spreadsheets are comprised of columns going left to right (usually designated by letters, starting with A) and rows (labeled by numbers from top to bottom, starting with 1). Any columns with content must have the first row contain labels that correspond to Content fields from your Model.
  • All labels for column names (including for associated content) need to be in lower case, precisely transcribed as it is in the Model/Content field.
  • You can include formatting marks (including textile) in your import document.
  • If you have a large block of text and wish to have hard returns between paragraphs, you need to include the text 
     \n
    in the place you wish to have the hard return.
  • When exporting a spreadsheet to CSV for importing into Interface, you should export it as Unicod (UTF-8).

For example, if you have a Model named “Photographs,” which has the fields “name,” “date” and “location,” then a corresponding spreadsheet could look like:

/assets/0000/0364/Photograph.jpg

The exported “Photographs.csv” file would then be:

name,date,location
Experiments,3/4/2009,Greenwich
Visualization,1/22/2009,Death Valley
Holiday,2/2/2009,Sydney
...

Notice that the first row is the name of the fields in the “Photographs” Model, and every subsequent row is a new “Photographs” Content item that will be imported into the system. If one of the listed entries has a comma inside it, put double quotation marks around the entire string:

Granular,5/5/2010,"Holden Station, the Moon"

This is a signal to the importer that the commas contained in the quotes should not be used to split the line into entries like the other commas. If you are exporting to CSV from a spreadsheet program (such as Excel), this is done for you automatically.

If an entry has a comma AND double quotes, you need to escape them with a slash (\) prior to each quotation mark, such as:

Circus,6/19/2009,"The \"Bearded Lady\", Ringleader, and me"

If this Model has a “belongs_to” Association to another Model and you want to associate items created on Import, there is a simple custom addition that allows you to make this association explicit in the spreadsheet/CSV file. Take the name of the belongs_to Association and create a new column in your file with the Association name and “.{{display field}}” appended to it. So, if a Photograph belongs to a Gallery, the Association being named “gallery,” you can make a new column “gallery.title” in the spreadsheet/CSV:

name,date,client_name,gallery.title
Snoopy,11/11/1901,Gridplane,Recent Clients

This item will be then associated to the Gallery with the title “Recent Clientes” when it is imported. Note: at this time, it is not possible to bulk import attachments, such as image (JPG or PNG) or document files, along with content in a CSV file.

If you are importing content to a Location column in a Model, you need to create a separate CSV to import that content. You will need to have imported (or created) the main content first so that you have the entry with which to connect this additional data.

The CSV needs to be named Location.csv and would look like:

address,city,state,country,zip,column_name,target_type,target_id
123 Main Street,New York,NY,USA,20012,address,Store,173
1221 5th Avenue,Portland,OR,USA,97205,address,Store,694
510 Market St.,San Fransisco,CA,94212,address,Store,111

The three required items in the list are “column_name”, “target_type” and “target_id” (the other items should correspond to whatever fields for which you have content).

*The “column_name” is whatever you named the Location column in your particular Interface (be it “address” or “location” or something else). This should be the same for all entries in this file.
*The “target_type” must be the name of the target model, in this case “Store”, or in the case of the previous example it would be “Gallery” (note the upper case of those target model names).

  • Query the API to find out the target_id of the corresponding data to which you want this content added in order add it to each entry.

Import of Previously Exported Content and Structure
In addition to importing content from CSV, you can also import packages that were exported by Interface from another site or at another time. You do not need to do any formatting or editing to previously exported content. These packages have a .tar.gz extension and contain a structure.yaml file and a directory of associated image assets. Since yaml is a nestable format, these files are more complex than the simple CSV examples. In addition to enabling the import of many types of content at once, the yaml format also allows for the importation of Models, Users and Roles, Pages, and Images.

Export

In general, all of your data is managed by Interface. This is helpful, but there are cases where you may want to use some or all of this data elsewhere, or you wish to import sections of it into another site. This is where export comes in.

In the export screen, you will be allowed to choose exactly what part of the data is exported. There are three sections: Admin, Models, and Content. Admin includes Pages, Users and Roles, and Site Properties. Models refers to the custom Models you have created, and Content is all of the content you have created based on these various Models. Choose whatever combination of Models and Content you wish to export, but keep in mind if content is being imported into another instance of Interface, the corresponding Model must already exist OR have been exported along with the content from that Model, otherwise there is no context when the content is imported.

Once all of your selections have been made, hit the “Export” button, and save the resulting .tar.gz file to your computer. This file can later be used to Import the selected areas of your site, or decompressed to extract the corresponding structure.yaml file and associated images.