PolyList Widget – in the Spotlight

I’m excited to write about this widget! I’ve really enjoyed playing with it over the last few weeks and challenging it to discover the styles of lists that I can produce with it. I can say confidently, any style of vertical scrolling list I have tried to build with it, I’ve been successful with. Let’s jump in.

PolyList – it’s a new LiveCode widget that allows you to display your data in a custom list view. You can build single or multi column lists that can contain text, images, SVGs and color fills, and you have full control over the style and position of everything. Take a look at this short video to get a sense of the incredibly cool lists you can build in LiveCode with PolyList.

Let’s walk through one of the list styles that I built in this demo video which will give you insight to just how useful this widget can be.

This multi column list contains

• Title Text
• Document Type with corresponding background color
• Checkbox (SVG)
• Last Modified title text
• Last Modified timeline text
• View icon (SVG)
• Download icon (SVG)

You may have also noticed in the video that this list had two different views, the one above is a multi column block style view and the one below is a standard single column view. It’s the same list, we are just changing the layout.

So how did I put this together? Was it easy? Can you do it? The answers are, I’ll show you, pretty easy, and yes you can. First, let’s look at styling your list. Once you have dragged out the PolyList Widget onto your card you want to open up its property inspector.

On the first tab of the property inspector you will see various properties that will help you get your list setup the way you want. You will see a treeview on this tab, this is your data content and we will come back to this in just a moment, lets focus on getting the look right first. Below the tree view in the above screenshot you can set the height and width of the individual list item and you can set the number of columns and the margins between each individual list item.

Now that we have added these properties we can get stuck into constructing all of the elements we need for our list. To do that we head to the next tab to find a custom style editor for PolyList.

The above is a screenshot of the PolyList column editor for the block style list screenshot shown earlier in this blog post. Let’s walk through it.

First you start to add the parts needed for your list. In the example above we needed a Title, and we needed that title to display across multiple lines, I needed it to be approx 200px wide, 120px high, and 25px from the left, I set the text size to 18, aligned it left and set the text style to bold. Changing any of these values will change how my title element appears on my list. This is creating your dataLayout and dataLayout is created as an Array. Note – In general when using this widget you don’t have to care about the dataLayout array, you simply set what you want in the property inspector. However you will need to know this if you want to change list style like I am doing in this particular demo. Here is a look the dataLayout array in a readable format for the block style list.

1 = 
	name = title
	left = 25px
	text-size = 18
	color = 73,73,73,255
	width = 200px
	align = left
	content-type = text-multiline
	height = 120px
	text-style = bold
	top = 0px
2 = 
	name = pillbg
	fill-type = rounded-rectangle
	height = 26px
	width = 55px
	align = left
	content-type = color
	fill = true
	text-style = 
	left = 25px
	top = 100px
	fill-cornerRadius = 5
3 = 
	color = 255,255,255,255
	top = 101px
	left = 27px
	align = center
	margin = 0
	width = 50px
	content-type = text
	text-size = 13
	height = 25px
	padding = 5
	text-style = bold
	name = pill
4 = 
	name = check
	right = 5px
	width = 50px
	height = 50px
	align = left
	content-type = icon
	color = 224,224,224,255
	text-style = 
	margin = 14
	top = 15px
5 = 
	name = mod
	left = 25px
	text-size = 14
	height = 200px
	width = 200px
	align = left
	content-type = text
	color = 194,194,194,255
	text-style = bold
	top = 90px
6 = 
	name = time
	left = 25px
	text-size = 14
	height = 200px
	width = 200px
	align = left
	content-type = text
	color = 132,132,132,255
	text-style = bold
	top = 110px
7 = 
	color = 124,124,124,255
	Bottom = 0px
	fill-type = circle
	top = 160px
	align = left
	margin = 1
	width = 30px
	content-type = icon
	fill-color = 229,229,229,255
	right = 60px
	height = 30px
	padding = 5
	text-style = 
	fill = true
	name = view
8 = 
	color = 124,124,124,255
	Bottom = px
	fill-type = circle
	top = 185px
	left = 
	align = left
	margin = 1
	width = 30px
	content-type = icon
	fill-color = 229,229,229,255
	right = 20px
	height = 30px
	padding = 7
	text-style = 
	fill = true
	name = download

Now that I have my list styled how I want, we can add our data. I said earlier in the blog post that we would come back to the treeview shown on the default tab of the property inspector. This is displaying the dataContent property and this is where we will add our data. We have the option to add our data manually into here, but, for anything other than a short list, that is probably not the most effective way of doing it. Let’s look at what is involved in adding data manually.

The dataContent property is an array and the treeview is displaying that array and also allowing us to add or edit the data. In the screenshot below there are 3 entries and I am adding data for our title section that we created in the Data Layout tab. The important thing to understand here is that they key matches the same value that you gave for the Data Layout item. So if we called it “title” in the layout section we must refer to it as “title” in the content section. As you add your data in here you will see it start to appear on your PolyList widget, this is a good opportunity to tweak any styling or layout issues. Indeed, it’s actually useful to have one section of data complete so you can get your layout and styling just right.

For anything more than a few entries, entering them manually is probably not the approach you will want to take. The dataContent property requires an array and for the list in our video that would look something like this.

1 = 
	mod = Last Updated
	pill = DOC
	download = arrow down
	title = Historical weather & Weather forecast by postal/ZIP code
	time = 1 month ago
	view = eye open
	pillbg = 89,206,123
	check = check empty
2 = 
	mod = Last Updated
	pill = DOC
	download = arrow down
	title = International holidays & events, workweek calendar
	time = 10 days ago
	view = eye open
	pillbg = 89,206,123
	check = check empty
3 = 
	mod = Last Updated
	pill = PDF
	download = arrow down
	title = Consumer Confidence index
	time = 3 months ago
	view = eye open
	pillbg = 134,119,221
	check = check empty

First let me talk through a some of the items in our dataContent array. The items download, view and check relate to the icon content type we set out earlier in our dataLayout, this expects an SVG icon name. The easiest way I know to find out the name of the SVG icon in LiveCode is to drag out the SVG widget, browse through the list and take note of the icon name. Another item in our list worth pointing our is pillbg, in our list we are using the color content type to provide a background for our document type, this is what makes DOC green and PDF purple in our list.

There are a few ways we can add our data to our list. The first would be by setting the dataContent of our widget to our constructed array. That would look something like this…

set the dataContent of widget "PolyList" to MyArray

We also have the tsvData and csvData property, these properties are incredibly useful for importing TSV or CSV data directly into our list’s dataContent. Especially If like me in this example you have your data in a TSV or a CSV file. You simply have to tell the widget to set it’s data to your TSV or CSV data. In our example I pasted my TSV data into a field called “tsv” and added the following code to a button.

set the tsvData of widget "PolyList" to field "tsv"

This line put my tsv data into the dataContent for the widget. You could do the same with csvData.

So we’ve looked at creating our layout and adding our content and really that is the bulk of what you need to know to go ahead and start creating some really cool lists. Some other neat things to know about this widget are that touch scrolling works out of the box and your list will look the same on all platforms.

Going back to our demo list, you will have seen in the video that I am changing the layout of the list and I think it’s worth touching on that as it may be useful to know in certain scenarios. On my stack I have two hidden fields, each field contains a readable array that has the layout properties for each of the list styles (I got this readable format by creating my list style, and putting this into the message box revPutArray the dataContent of widget "PolyList" , I then pasted the results of this into a field). I added two SVG widgets to act as controls for switching between the list styles. Here is an example of the code added to one of the SVG buttons to control the list style switching

function getDataArray
     local tIndex, tArray
     set the itemdelimiter to "="
     repeat for each line tLine in field 2
          if char 1 of tLine is a number then
               add 1 to tIndex
               next repeat
          end if
          put char 2 to -1 of item 2 of tLine into tArray[tIndex][char 2 to -2 of item 1 of tLine]   end repeat
          return tArray
     end getDataArray

on mouseUp
     lock screen
     set the dataLayout of widget "PolyList" to getDataArray()
     set the itemheight of widget "PolyList" to 150
     set the numberofColumns of widget "PolyList" to 1
     unlock screen
end mouseUp

Just to quickly talk through what you see there; we have our function that takes our readable array data and turns it into a LiveCode array. Then we have our mouseUp data that sets the dataLayout to that array. We are also changing the height of the widget to go from block style to list style and changing the number of columns from 3 to 1. Note – you only really need to care about this if you want to do something similar to my example. If you just want to build beautiful lists you can do so with the controls available in the property inspector.

Talking of beautiful lists, here are a few other beauties that I’ve created as part of putting PolyList in the spotlight.

I’d like to round off this blog post by saying after spending a bit of time with this widget, it might be my new favourite. I love where it is today and I love where it can go. I’m not a professional developer but I’ve been able to build professional lists with the PolyList widget that I have struggled to make before without it. As always I would love to know what your thoughts are on what you have seen in this blog post, and if you have any questions on things I did or didn’t cover then leave a comment below and I will get back to you.

Note for the eagle eyed LiveCoder. PolyList was not a widget that was included in the Summer MegaBundle. PolyList is what was originally called DataView, we decided to change the name due to a conflict with another LiveCode extension. I encourage everyone who has already purchased the MegaBundle to make sure you are using the latest version as we have made a number of updates recently. For those that don’t have their hands on it yet, PolyList is available in the Extensions Store.