The custom list is a fundamental building block of your guide. It is a menu item that houses content for your users. You can add as many custom lists as you need in order to provide information to your users.
Each custom list will have a name and an icon. Your custom lists can be placed on the main menu itself, or they can live inside a folder if you have a lot of content to keep organized.
Here are some examples of custom lists you might include in your guide:
- Speakers or Presenters
- Award Winners
- Staff Members
- Departments on Campus
- Nearby Restaurants or Attractions
- Glossary of Terms
- Presentation Materials or Abstracts
Once you have added a custom list to your guide, you can change the name of the list or the icon associated to it via The Settings Tab.
Displaying Custom List Items
Inside a custom list, you add list items. Each list item is a page of content. This is a great place for a couple of paragraphs of text.
In the list's settings tab, you can choose to display your list items in a traditional stacked list view or in a grid view, to show off the thumbnail images. This works well for lists of speakers when you have included headshots of the person, exhibitors to show off their logos, or if you want to give a more engaging and visual display of your content.
If you would like to display a single list item on the navigation menu, create a one-tap menu item.
Manually Adding List Items
It is quick and easy to add content to your custom lists in Builder. The manual process is great for lists with just a few list items or for a handful of edits to existing list items.
To add a list item manually, click on the list to open it. Then click the blue New button.
Name: Enter the name of your list item. This is required.
Label/Subtitle: Use this field to provide additional information complementing the name.
Location: You can add navigational locations or interactive locations.
Description: This field is perfect for a paragraph or two of text.You can use the formatting tools to modify the formatting and input links, or switch to the HTML editor by clicking the code button, which is represented by two angle brackets.
Image: Include a header image to make your list item pop. You can upload a JPG or PNG file that is 640 pixels wide and 240 pixels tall. This image will appear in the list item details page along the top of the users' device.
Thumbnail: This is a great place for a logo or a picture of a speaker. You can upload a square JPG or PNG that is 240 pixels tall and 240 pixels wide.
Manually Editing List Items
To edit an existing list item, click on the name of the list item. You’ll see the list Item details that you added previously, as well as some tabs for additional tools.
Links: Use this tab to link to other sessions, list items, URLs, or PDFs.
Collaborate: Use this tab to invite people to edit the content of this particular item. Anyone you invite to edit a list item via the collaborate tab does not need a Builder account and will not have access to any other content in your guide.
Quick Info: Manually add quick info information to list items from this tab.
Adding List Items to Multiple Custom Lists (One-to-Many)
The One-to-Many feature allows you to add one list item to multiple custom lists, without having to duplicate any work. For example, you may want to include Exhibitors and Sponsors in your guide. Some of your Sponsors, however, may also have booths in the Exhibit Hall. Instead of having two separate lists where you have to maintain updated content in two different places, use the One-to-Many feature.
This can be useful as when you edit an item, all instances of the information get updated at once.
Adding an item to a second custom list is easy, first create two custom lists in your guide and name them. In this example: List A is Food & Drink and List B is Sponsors.
Add all of your Food & Drink information to List A. When it comes to List B, open your Sponsors list, click New and select attach an existing item from another list under the Name field.
In the search bar that appears, start typing in the name of an existing list item that also needs to appear in this Sponsors list. Select that item.
If you edit a list item, those changes will be reflected in all instances of that list item. So if you change something in List A, it will also be changed in List B.
If you need to delete an item, click the gear icon to the right and select Delete. You'll be given the option to Remove from this list or Delete from all lists.
Adding Custom List Items using a Template
With a Custom List template, you can quickly add multiple list items to a list at one time. Download a copy of the list template at the bottom of this article, or download it from your guide in Builder. You'll use a template for each custom list in your guide if you choose to import your data.
Downloading the List Template
You can download a copy of the list template at the bottom of this article, or you can find it in your guide in Builder. You need to use the Guidebook template, as Builder will not be able to recognize another spreadsheet.
To find the template in Builder, click on any custom list menu item, and then click Import from file.
Near the top-right corner of this window, look for Templates. Click either Custom List Items (XLS) or Custom List Items (CSV) to download a template.
You can use Microsoft Excel, Apple Numbers, Apache OpenOffice, or LibreOffice to open the template files. Please keep in mind that Excel may not handle special characters (like accents) well. Excel cannot encode in UTF-8, which is the preferred text format that Guidebook uses. OpenOffice and LibreOffice are free to download from the links above.
Adding List Item Data to the List Template
Now that you have a Custom List template, it's time to put your list item information into the spreadsheet.
Do not change Row 1 in the template spreadsheet. If the column headers are changed, Builder will give you an error as it will not be able to read the spreadsheet properly.
If you have images you'd like to include with your custom list, you can import images along with your list template, or you can use the template to import the text, and manually add your images from Builder.
Begin by deleting the sample data in the exported template, and start adding your data. The Name field is the only required field, though we recommend adding information to the other fields as well to create a robust, content-filled guide.
For instance, if you are creating a list of speakers, you can add their name to the Name column, their job title to the Sub-Title column, and their bio to the description field. If you'd like to include contact information, you can also include that in the description using HTML.
As a second example, if you'd like to include a list of Nearby Restaurants, you would put the name of the restaurant in the Name field, the cuisine type in the Sub-Title field, the address in the Location field, and hours, contact information, and extra information in the description field.
What you add to various columns is up to you! If you have data that you aren't sure how to fit into our template, feel free to reach out to us at email@example.com and we're happy to offer suggestions.
Uploading a List Template into Builder
After you've added your data to the spreadsheet, you're ready to import the template into Builder.
In your guide in Builder, click on the custom list menu item you're working on. Then click on the Import from file button.
Then, click Start Import on the left side of the screen, under the “Import list items” heading.
This will open a file browser; please select the list template you were working on. Then click Import data.
You will receive an email that says Success or Whoops! Make sure to check your Spam folder if you don't receive this email. Refresh your Builder page to see your data if it imported correctly.
If you see a Whoops! message, please make note of the error message details provided and check the below section to see what you need to correct. If the error message is not in the below list, reach out to us at firstname.lastname@example.org for assistance.
Custom List Template Errors
We know how it feels to get a "Whoops" email from Builder! Below we've listed common error messages you might receive when trying to import your custom list template spreadsheets.
Please review the information below, make the appropriate changes, and re-import your spreadsheet.
Invalid Column Name. It appears you have renamed the template columns, or you are using an old template. Please correct.
This error indicates you may be using the incorrect template. The easiest way to troubleshoot this is to download a fresh copy of the import template and copy your data over, without modifying any of the column headers in Row 1. See above for custom list template information.
There are special characters that we cannot recognize. Take these out, then try reimporting your file.
If you are using Excel to create your file, please save it as a .xls file. Do not use the .csv filetype. This will ensure that characters are encoded in the appropriate format. If you are using LibreOffice or Apache OpenOffice, please ensure that you save your document as a .csv in the UTF-8 encoded format.
Either a .xls or .csv file is required.
Builder can only read .csv or .xls versions of the template spreadsheets. If you are using another filetype, please Save as either .csv or .xls. If you are using .xls and still receive this error we recommend switching to .csv to be on the safe side. Some versions of Microsoft Excel save certain items (typically dates) in a format that Builder has trouble reading.
Error: we could not find the specific image.
If you are importing images along with your Custom List template, please review the instructions for importing images. Builder will look for a filename of an image that exactly matches the filename you type in the spreadsheet. This means capitalization and filetype must match perfectly. Also be sure you import a zip file of pictures, not a zip file of a folder.
We could not read your file due to an encoding issue.
This error typically occurs when an .xls file was downloaded from Builder, but it's saved as a .csv. To troubleshoot, try saving the file as a .xls instead, or re-download a blank .csv template from Builder and copy your data into the template, saving the template as a .csv.
When I try to open my CSV file, a window pops up asking me to select punctuation, such as "tab", "semicolon" or "comma". What should I click?
Deselect all options except for comma, and then press OK.
When I convert my Excel file into a CSV file and open it again, there are strange marks in the text (i.e. white question marks on black diamonds). What do I do?
This is probably a side effect of using non-standard characters in your text fields. Many characters that appear when typing in Microsoft Word/Excel, such as the n-dash or curly quotation marks, are proprietary and non-standard. When transported into a CSV file or a UTF-8 encoded file, they fail to render properly. We recommend uploading this file in .xls format to avoid this encoding issue or by editing using either of these free spreadsheet editors: Libre Office or Apache Open Office.
I have uploaded list items, but now I want to make changes and/or add more list items. How do I do that?
We recommend exporting your custom list so you have one spreadsheet with all of those list's items in one place. Make changes to your data there and/or add new list items to that spreadsheet, then re-import it into Builder. You'll notice the exported data will have List Item IDs; Builder generates these for you so it can keep track of your list items without duplication or loss of data.
My list data doesn't fit into these columns. How do I add the list data I want?
If you change the column headers or add your own columns to this spreadsheet, Builder will not be able to read your data. Use the Description field to contain as much information as possible about your list item. You can use concatenation to combine cells to put data in one cell, and HTML for things like phone numbers and email addresses. Some information may be best included via linking.