LiveCode LessonsLiveCode Data Grid Data Grid FundamentalsHow Do I Customize A Table's Columns? Part 2

How Do I Customize A Table's Columns? Part 2

A column template is nothing more than a LiveCode control that is named after a column in your table. This control is located in the row template group for your data grid. This lesson will discuss how to create templates for columns in a data grid table.

In this lesson we will see how to customize 3 columns in a DataGrid table.

Create the DataGrid Table

Create a new stack and add a DataGrid to the stack. Add 3 columns to the DataGrid

  • Genre
  • Time
  • Rating

Select a column to customize

We are going to customize each column, we will start with the Genre column which will allow the user to select a genre from a dropdown list.

In the Property Inspector, select the Genre column(1) and click the "+" button next to the Column Behavior at the bottom of the pane to create a  new column behavior (2).

Edit the Column Group

Edit the Row Template Group

In order to customize the look we need to edit the contents of the template group. Each column has its own template group in the Row Template.

  1. Ensure you have "Select Grouped" turned off
  2. Select the "Row Template" group
  3. Click "Edit Group" in the LiveCode Toolbar.
  4. Select the "Genre" group
  5. Click "Edit Group" in the LiveCode Toolbar

Edit the Column Group

Edit Column Group

To customise the "Genre" column template we want to add an Option Menu.

  1. Delete the default field in the column template group
  2. Add an Option Menu to the column template group
  3. Name it "Genre"
  4. Add some genre options

Close and save the DataGrid Templates stack.

The Column Behavior

Now we need to update the column behavior of the Genre column to use the customize column template.

  • Open the Property Inspector for the DataGrid
  • Go the the Columns pane
  • Select the Genre column
  • Click the "Column Behavior" button

This will open the behavior script for the column.

The FillInData command

First we need to update the FillInData command to refer to the button we added and not a field.

on FillInData pData
    -- This message is sent when the Data Grid needs to populate
    -- this template with the column data. pData is the value to be displayed.
    
    -- Example:
    set the label of button "Genre" of me to pData
end FillInData

The LayoutControl and ResetData commands

Next we update the LayoutControl and ReserData commands.

on LayoutControl pControlRect    
    -- This message is sent when you should layout your template's controls if your template is a group.
    -- If your template is not a group then there is no work to do here.
    -- You can use items 1 through 4 of pControlRect as boundaries for laying out your controls.
    
    -- Example:    
    set the rect of button "Genre" of me to pControlRect
end LayoutControl

on ResetData
    -- Sent when column data is being emptied because the control is no longer being used to display data
    set the label of button "Genre" of me to empty
end ResetData

Apply and close the behavior script.

Testing the DataGrid

Now we can test the DataGrid.

Open the Property Inspector for the DataGrid and add some tab separated data in the Contents pane.

You will see that the Genre column displays as a dropdown list the user can select from, and the initial label is set to the value in the Genre column.

The Rating Column

Now we will customize the Rating column to use 5 stars to show the rating for a track.

  1. Select the Rating column in the Columns pane of the Property Inspector
  2. Create a new Column Behavior using the "+" button
  3. Edit the "Rating" group of the Row Template
  1. Delete the default field
  2. Add 5 small star SVG widgets named "Star1","Star2","Star3","Star4" and "Star5".
  3. Save and close the Row Template stack.

Customize the Row Behavior

Open the Row Behavior for the "Rating" column from the Property Inspector and update the FillInData, LayoutControl and ResetData handlers to refer to the new controls.

on FillInData pData
   -- This message is sent when the Data Grid needs to populate
   -- this template with the column data. pData is the value to be displayed.
   
   -- Example:
   set the visible of widget "Star1" of me to pData >=20
   set the visible of widget "Star2" of me to pData >=40
   set the visible of widget "Star3" of me to pData >=60
   set the visible of widget "Star4" of me to pData >=80
   set the visible of widget "Star5" of me to pData >=100
end FillInData

on LayoutControl pControlRect    
   -- This message is sent when you should layout your template's controls if your template is a group.
   -- If your template is not a group then there is no work to do here.
   -- You can use items 1 through 4 of pControlRect as boundaries for laying out your controls.
   
   -- Example:    --
   --set the rect of field 1 of me to pControlRect
   set the topLeft of widget "Star1" of me to (item 1 of pControlRect+3, item 2 of pControlRect+3)
   set the topLeft of widget "Star2" of me to the topRight of widget "Star1" of me
   set the topLeft of widget "Star3" of me to the topRight of widget "Star2" of me
   set the topLeft of widget "Star4" of me to the topRight of widget "Star3" of me
   set the topLeft of widget "Star5" of me to the topRight of widget "Star4" of me
end LayoutControl

on ResetData
    -- Sent when column data is being emptied because the control is no longer being used to display data
end ResetData

In the FillInData handler pData contains the value of the "Rating" column for the row being displayed. We use that value to determine how many stars to display.

Test the DataGrid

Test the Rating display by setting a value in the Rating column of the DataGrid.

The table found controls named "Genre" and "Rating" in the row template group so those were used to render the data for those three columns.

The Structure in LiveCode

Here is what those controls look like in the Project Browser. Notice how all of the controls are located in the "Row Template" group(1).

The column templates each have behaviors associated with them. The buttons containing these behaviors can be found on the same card as the "Row Template" group(2).

0 Comments

Add your comment

E-Mail me when someone replies to this comment