Создание панели свойств Qlik Sense Extension

Введение в свойства расширения. Что такое панель свойств?

Перед тем, как перейти к разработке Qlik Sense Visualization Extensions, необходимо понять основные принципы определения и использования свойств в Qlik Sense расширениях.

Основная идея свойств состоит в том, чтобы предложить пользователям способ настройки поведения расширений визуализации таким же образом, как они будут управлять собственными объектами Qlik Sense. Поэтому разработчик расширения может использовать программный интерфейс для определения свойств, которые затем отображаются на правой панели свойств.

Определение панели свойств

Свойства структурированы иерархически (есть еще такой термин, как аккордеон панели свойств):

A – Sections
B – Header
C – Items

Есть еще одна иллюстрация (с сайта http://qliksite.io/tutorials/qliksense-visualization-extensions/part-01/06-Introduction-to-Using-Properties/):

Accordion

• Accordion sections
  • Section headers
    • Property items

Свойства добавляются путем их определения в свойстве definition в файле JavaScript. 

Есть два способа определения свойств:

• Повторное использование существующих встроенных свойств (Reusing existing, built-in, properties)
• Создать настраиваемые свойства (custom properties)

Reusable Properties:

• Dimensions
• Measures
• Sorting
• Appearance
• Add-Ons

Повторное использование существующих свойств

Вот некоторые типичные свойства, используемые для наиболее распространенных встроенных визуализаций Qlik Sense:

• Все собственные визуализации имеют раздел Внешний вид с заголовком раздела Общие .
• Большинство встроенных визуализаций позволяют определять измерения и меры .

Определение свойств

Если вы создаете расширение визуализации без defining a properties panel, Qlik Sense по умолчанию будет включать раздел “Внешний вид“ или “Appearance section”.

Тот же результат будет достигнут при повторном использовании раздела настроек, который является внутренним именем раздела Внешний вид.

define( [
        'jquery'
    ],
    function ( $ ) {
        'use strict';

        return {

            // Define what the properties panel looks like
            definition: {
                type: "items",
                component: "accordion",
                items: {
                    appearance: {
                        uses: "settings",
                    }
                }
            },
            // Paint/Rendering logic
            paint: function ( $element /*, layout*/ ) {

                $element.empty();
                var $msg = $( document.createElement( 'div' ) );
                $msg.html( 'Just demonstrating default behavior of the property panel"' );
                $element.append( $msg );

            }
        };

    } );

На основе приведенного выше кода вы теперь можете расширить definition для повторного использования других встроенных разделов. В этом примере мы также повторно будем использовать разделы измерений, мер и сортировки.

// Define what the properties panel looks like
definition: {
    type: "items",
    component: "accordion",
    items: {
        dimensions: {
            uses: "dimensions"
        },
        measures: {
            uses: "measures"
        },
        sorting: {
            uses: "sorting"
        },
        appearance: {
            uses: "settings",
        }
    }
},

В результате мы получим следующую панель свойств:

Ссылка на свойства

Параметр макета (layout) передается в метод paint, и он включает текущую область расширения визуализации вместе с определенными свойствами.

// Paint/Rendering logic
paint: function ( $element, layout ) {

    console.info('paint >> layout >> ', layout);

}

Если вы посмотрите на вывод консоли, например, в Chrome DevTools, вы найдете то, что ищете.

С этой информацией теперь вы можете начать выводить некоторые значения в метод paint.

// Paint/Rendering logic
paint: function ( $element, layout ) {

    //output values from the property panel
    $element.empty();
    
    //output container
    var $msg = $( document.createElement( 'div' ) );
    
    //variable holding the output
    var html = '<b>Property values:</b><br/>';
    html += 'Title: ' + layout.title + '<br/>';
    html += 'Subtitle: ' + layout.subtitle + '<br/>';
    
    //assign the variable to the output container
    $msg.html( html );
    
    //add the output container to the current element
    $element.append( $msg );

}

Получим следующий результат:

Собственные свойства, которые можно использовать повторно

В этом разделе перечислены собственные свойства Qlik Sense, которые можно повторно использовать в определении панели свойств.

Dimensions

Когда вы повторно используете раздел Dimensions section, он включает в себя следующее:

• Add dimension

После добавления измерения у вас есть следующие свойства по умолчанию:

• Field
• Label
• Show null values
• Limitation
• Show others
• Others label

Пример: Add Dimensions section

В приведенном ниже примере показано, как добавить раздел “Dimensions” на панель свойств вашего расширения визуализации. Обратите внимание, что определено, что расширение визуализации должно иметь ровно одно измерение.

define( [], function ( ) {
    
    return {
        type: "items",
        component: "accordion",
        items: {
            dimensions: {
                uses: "dimensions",
                min: 1,
                max: 1
            }
        }
    };
 
});

Measures

Когда вы повторно используете раздел “Меры”, он включает в себя следующее:

• Add measure

Когда вы добавили меру, у вас появятся следующие свойства по умолчанию:

• Label
• Expression
• Number formatting

Пример: Add Measures section

В этом примере показано, как мы теперь добавили определение раздела «Меры» на панель свойств нашего расширения визуализации. Обратите внимание, что здесь мы также определяем, что расширение визуализации должно иметь ровно одну меру.

define( [], function ( ) {
    
    return {
        type: "items",
        component: "accordion",
        items: {
            dimensions: {
                uses: "dimensions",
                min: 1,
                max: 1
            },
            measures: {
                uses: "measures",
                min: 1,
                max: 1
            }
        }
    };
 
});

Sorting

Когда вы повторно используете раздел сортировки, он включает в себя следующее:

• Labels of the dimension and measure, используемые в расширении визуализации
• Sorting option (Auto or Custom)Опция Custom включает в себя следующее:
  • Sort by expression (only available for dimensions)
  • Sort numerically
  • Sort alphabetically
  • Sort by frequency (only available for filter panes)

Пример: Add Sorting section

В этом примере показано, как мы теперь добавили определение раздела «Сортировка» на панель свойств вашего расширения визуализации. Мы не вносили никаких изменений в раздел «Сортировка», предварительно определенный Qlik Sense.

define( [], function ( ) {
    
    return {
        type: "items",
        component: "accordion",
        items: {
            dimensions: {
                uses: "dimensions",
                min: 1,
                max: 1
            },
            measures: {
                uses: "measures",
                min: 1,
                max: 1
            },
            sorting: {
                uses: "sorting"
            }
        }
    };
 
});

Add-ons (Надстройки)

Когда вы повторно используете раздел надстроек (Add-ons), он включает в себя следующее:

• Data handling
• Reference lines

Пример: Add Add-ons section

В этом примере показано, как мы добавляем определение раздела «Надстройки» на панель свойств вашего расширения визуализации. Мы не вносили никаких изменений в раздел «Надстройки», предварительно определенный Qlik Sense.

define( [], function ( ) {
    
    return {
        type: "items",
        component: "accordion",
        items: {
            dimensions: {
                uses: "dimensions",
                min: 1,
                max: 1
            },
            measures: {
                uses: "measures",
                min: 1,
                max: 1
            },
            sorting: {
                uses: "sorting"
            },
            addons: {
                uses: "addons"
            }
        }
    };
 
});

Appearance (settings) – Внешний вид

Appearance section называется settings в коде.

Когда вы повторно используете раздел «Внешний вид», он включает в себя следующее:

• General – ОбщийВключает настройки для заголовка, подзаголовка и сноски
• Presentation – Презентация (доступна только для визуализаций с более чем одним измерением)
• Colors and legend – Цвета и легенда (доступно только в некоторых типах визуализаций)
• X-axis – Ось X (доступна только в некоторых типах визуализаций)
• Y-axis – Ось Y (доступна только в некоторых типах визуализаций)

Пример: Add Appearance section

В этом примере показано, как мы добавляем определение раздела «Внешний вид» на панель свойств вашего расширения визуализации. Мы не вносили никаких изменений в раздел «Надстройки», предварительно определенный Qlik Sense.

define( [], function ( ) {
    
    return {
        type: "items",
        component: "accordion",
        items: {
            dimensions: {
                uses: "dimensions",
                min: 1,
                max: 1
            },
            measures: {
                uses: "measures",
                min: 1,
                max: 1
            },
            sorting: {
                uses: "sorting"
            },
            addons: {
                uses: "addons"
            },
            settings: {
                uses: "settings"
            }
        }
    };
 
});

Добавление дополнительных свойств (custom properties)

Вы можете задать custom properties для visualization extension. Qlik Sense автоматически добавляет их на панель свойств и заботится о сохранении. Затем вы найдете выбранные значения в параметре layout.

Для каждого свойства вы задаете объект JavaScript с разными полями в зависимости от того, какой тип настраиваемого свойства вы определяете.

Следующие компоненты пользовательского интерфейса могут использоваться для отображения ваших custom properties на панели свойств:

• Button – Кнопка
• Button group – Группа кнопок
• Check box – Флажок
• Color-picker – выбор цвета
• Drop down list – Выпадающий список
• Input box / text box – Поле ввода / текстовое поле
• Link – Ссылка
• Media
• Radio button – Переключатель
• Range slider – Ползунок для выбора диапазона
• Slider
• Switch – Переключатель
• Text – Текст
• Text area – Текстовая область

Их можно сгруппировать в разделы и заголовки на панели свойств. Каждый из них предоставляет различные параметры конфигурации для управления их поведением.

Совет: Как улучшить управляемость скриптом Javascript при разработке Extension?

Если у вас есть много разных свойств, определенных в основном файле JavaScript, вы скоро поймете, что размер файла js может стать довольно большим, и его будет трудно читать и поддерживать. Для облегчения работы с js есть разные подходы:

• Разделите раздел definition на несколько переменных JavaScript.
• Создайте отдельный файл JavaScript для определения ваших свойств и загрузите этот файл в основной файл сценария расширения визуализации.

Определение свойств в отдельном файле JavaScript

В этом разделе показано, как определить ваши свойства в отдельном файле JavaScript. Мы начинаем со следующего кода, определенного в вашем основном файле сценария.

define( [
        'jquery'
    ],
    function ( $ ) {
        'use strict';

        return {

            // Define what the properties panel looks like
            definition: {
                type: "items",
                component: "accordion",
                items: {
                    dimensions: {
                        uses: "dimensions"
                    },
                    measures: {
                        uses: "measures"
                    },
                    appearance: {
                        uses: "settings",
                    }
                }
            },
            // Paint/Rendering logic
            paint: function ( $element, layout ) {
            // Main rendering logic goes here
            }
        };
    } );

Создайте файл и назовите его properties.js. Сохраните его в той же папке, где находятся ваши основные файлы расширения визуализации. Новый файл properties.js должен выглядеть так:

define( [], function () {
    'use strict';
    // *****************************************************************************
    // Dimensions & Measures
    // *****************************************************************************
    var dimensions = {
        uses: "dimensions",
        min: 0,
        max: 1
    };
    var measures = {
        uses: "measures",
        min: 0,
        max: 1
    };
    // *****************************************************************************
    // Appearance section
    // *****************************************************************************
    var appearanceSection = {
        uses: "settings"
    };
    // *****************************************************************************
    // Main properties panel definition
    // Only what is defined here is returned from properties.js
    // *****************************************************************************
    return {
        type: "items",
        component: "accordion",
        items: {
            dimensions: dimensions,
            measures: measures,
            appearance: appearanceSection
        }
    };
});

Затем вам нужно загрузить внешнее определение свойств в ваш основной файл сценария и назначить definition.

define( [
        // Load properties.js using requireJS
        // Note: if you load .js files, omit the file extension
        // otherwise requireJS will not load it correctly
        './properties'
    ],
    function ( props ) {
        'use strict';
        return {
            definition: props,
            // Paint/Rendering logic
            paint: function ( $element, layout ) {
            // Main rendering logic goes here
            }
        };
    } );

Добавление basic custom property

В этом разделе мы определим самый простой, но один из наиболее распространенных компонентов – текстовое поле.

// Text box definition
var myTextBox = {
    ref: "props.myTextBox",
    label: "My text box",
    type: "string"
};

В определении всех компонентов пользовательского интерфейса есть общие свойства, которые можно установить.

type

Используется для всех определений типов настраиваемых свойств. Может быть string, integer, number или boolean.

ref

Имя или идентификатор, используемый для ссылки на свойство.

label

Используется для определения метки, отображаемой на панели свойств.

component

Используется для определения того, как свойство отображается на панели свойств.

В приведенном выше примере component не определен. Qlik Sense автоматически по умолчанию использует текстовое поле, если component не определен для элементов, type которых является string или integer.

Добавление определения компонента на панель свойств

В этом разделе мы добавим вновь созданное текстовое поле на основе строки в раздел Внешний вид.

Перед:

// Appearance section
var appearanceSection = {
    uses: "settings"
};
// Main properties panel definition
// Only what is defined here is returned from properties.js
return {
    type: "items",
    component: "accordion",
    items: {
        appearance: appearanceSection
    }
};

После:

var myTextBox = {
    ref: "props.myTextBox",
    label: "My text box",
    type: "string"
};

// Appearance section
var appearanceSection = {
    uses: "settings",
    items: {
        myTextBox: myTextBox
    }
};

// Main properties panel definition
// Only what is defined here is returned from properties.js
return {
    type: "items",
    component: "accordion",
    items: {
        appearance: appearanceSection
    }
};

Результат:

Добавление собственного заголовка раздела

В предыдущем примере вы добавили текстовое поле в новый раздел. В заголовке раздела автоматически повторно использовалась метка компонента. В этом разделе вы добавите собственный заголовок раздела. Для этого вы создаете новый заголовок ( myNewHeader в примере ниже) в существующем разделе «Внешний вид», а затем добавляете туда элементы:

var appearanceSection = {
    uses: "settings",
    items: {
        // Definition of the custom section header
        myNewHeader: {
            type: "items",
            label: "My header, containing text box",
            items: {
                myTextBox: myTextBox
            }
        }
    }
};

// NOTHING CHANGED HERE ...
// Return overall definition of the property accordion
return {
    type: "items",
    component: "accordion",
    items: {
        appearance: appearanceSection
    }
};

Результат:

Добавление настраиваемого раздела

Вы также можете создавать совершенно новые разделы аккордеона.

// Some components
var header1_item1 = {
    ref: "props.section1.item1",
    label: "Section 1 / Item 1",
    type: "string",
    expression: "optional"
};

...
...

// Define a custom section
myCustomSection = {
    // not necessary to define the type, component "expandable-items" will automatically
    // default to "items"
    // type: "items"
    component: "expandable-items",
    label: "My Accordion Section",
    items: {
        header1: {
            type: "items",
            label: "Header 1",
            items: {
                header1_item1: header1_item1,
                header1_item2: header1_item2
            }
        },
        header2: {
            type: "items",
            label: "Header 2",
            items: {
                header2_item1: header2_item1,
                header2_item2: header2_item2
            }
        }

    }
}

Ключ в приведенном выше коде заключается в том, что вы добавляете expandable-items компонента . Остальной код работает как в предыдущих примерах.

return {
    type: "items",
    component: "accordion",
    items: {
        appearance: appearanceSection,
        customSection: myCustomSection
    	 }
    };
});

Результат:

Отображение и сохранение custom (настраиваемых) свойств

После того как вы определили custom properties, Qlik Sense позаботится обо всем остальном, а именно:

• Отображение custom properties вместе со встроенными свойствами
• Сохранение значений свойств. Если значение свойства изменяется, вам не нужно заботиться о сохранении, то есть о сохранении и загрузке значения свойства.

Ссылка на значения настраиваемых свойств

Ссылка на значения custom properties аналогична ссылке на значения из встроенных свойств, но с одним исключением. Используя ref, вы можете определить, как значения свойств отображаются в дереве объектов. Этот принцип применяется ко всем элементам настраиваемых свойств.

Примеры:

Определяем текстовое поле:

var myTextBox = {
    ref: "myTextBox",
    ...
};

На это значение можно ссылаться в вашем скрипте:

console.log( layout.myTextBox );

В то время как:

var myTextBox = {
    ref: "prop.myTextBox",
    ...
};

Будет вызываться с использованием:

console.log( layout.prop.myTextBox );

Добавление префиксов к вашим свойствам, как показано в последних примерах выше, позволяет легко перебирать все настраиваемые свойства. Это также гарантирует отсутствие конфликтов именования стандартных объектов Qlik Sense.

Определение настраиваемых свойств

Custom string properties

todo

Custom integer properties

todo

Custom number properties

todo

Custom array properties

todo

Custom button properties

todo

Custom button group properties

todo

Custom check box properties

todo

Custom color-picker properties

todo

Custom drop down list properties

todo

Custom link properties

todo

Custom media properties

todo

Custom radio button properties

todo

Custom slider properties

todo

Custom range-slider properties

todo

Custom switch properties

todo

Custom text properties

todo

Custom textarea properties

todo