Lab 2

Providing an empty state

When you dropped the card list widget onto the page using the designer it was nothing more than a box with an outline. Even editing the instance options only slightly revealed what the widget does. When practical, your widgets should provide an empty state and tip users off about how to proceed and what it will look like when it has data.

Using the Demo data field on a widget is good for previewing a widget in the widget editor but won’t work in the designer. This is because the demo data is overwritten as soon as there is an instance record. Here are a couple of ways you can provide an empty state for a good experience in the designer.

Show a default title

1. From STUDIO, Open the Card List widget.
2. ADD the following code to the Client Script code block, below line 2:

function isConfigured() { 
    if (!c.options) { 
        return false; 
    }  
    if (typeof c.options.title === "undefined") 
        return false;  
    return true; 
} 

3. Now you can use that function to set an example title right in the Client Script. Find the lines:

if (c.data && c.data.cardFields) { 
    c.cardFields = getCardFields(c.data.cardFields, c.data.primaryField); 
}

and replace it with this code:

if (!isConfigured()) { 
    c.options.title = "My active incidents"; 
} else if (c.data && c.data.cardFields) { 
    c.cardFields = getCardFields(c.data.cardFields, c.data.primaryField); 
} 

Add some demo data

1. If you want to go for a richer experience, replace it with this code instead:

if (!isConfigured()) { 
    // Provide demo data if options.title is empty 
    c.options.title = "My active incidents"; 
    c.options.priority_field = "priority"; 
    c.options.display_field = "short_description"; 
    c.data = { 
        "primaryField": "number", 
        "cardFields": "category", 
        "rows": [{"sys_id":"1", 
                  "number":"INC0000002",
                  "short_description":"Network file shares access issue",                 
                  "category":"Network",
                  "priority":"1 - Critical"}, 
                  {"sys_id":"2", 
                   "number":"INC0000003",
                   "short_description":"I need a mouse",
                   "category":"Hardware",
                   "priority":"4 - Low"}] 
            } 
} else if (c.data && c.data.cardFields) { 
    c.cardFields = getCardFields(c.data.cardFields, c.data.primaryField); 
} 

Try it out

We are going to delete the widget instance from the page and add it again to see the changes.

1. Open the designer in a new tab [instance]/$spd.do

2. Find the Incident Workspace page and click to edit.

3. Delete the Card List widget from the left column by clicking on the delete button when hovering over the widget. When it asks you to confirm, click Yes

4. Find the Card List from the widgets list. Drag the widget to the left column.

5. Now you will see a much better example of the card list before it’s even configured:

6. Use the edit button (pencil) add the widget options again:

   Title: My Active Incidents

   Table: Incident

   View: Mobile

   Filter: active=true

   Display Field: short description

   Priority Field: priority