A package.json file contains configurations of a widget. This topic describes fields in a package.json file. You can configure these fields in the file to customize the style of a widget as needed.

Example of a package.json file in protocol version 2

Note The comments in the following example provide the details of fields in a package.json file.
{
  "name": "@leaf/pie-multi-radius-with-title",   //@Namespace/Widget name. The namespace is the name of a widget package. If you do not specify a namespace, the widget cannot be published.
  "version": "0.1.5",                            // The version number.
  "dependencies": {                              // The dependencies that exclude datav:/com/.
    "bcore": "0.0.9",
    "jquery": "2.1.4",                           // All dependency versions must be locked.
    "lodash": "4.6.1"
  },
  "datav": {                                     // The configurations of DataV.
    "cn_name": "Multidimensional pie chart with a title",               // The name of the widget.
    "protocol": 2,                               // The version of the protocol.
    "type": ["regular_pie"],                     // The type of the widget.
    "supportTheme": true,                      // Specifies whether the widget supports theme configurations.
    "view": {
      "width": 300,
      "height": 200,
      "minWidth": 100,
      "minHeight": 50
    },
    "icon": "",                                    // The URL of the widget icon.
    "apis": {                                      // The widget APIs. You can add one or more APIs.
      "source": {                                  // The name of the API.
        "handler": "render",                       // The method to handle the widget returned by the API.
        "description" : "The API of a multidimensional pie chart",          // The description of the API.
        "fields" : {                               // The fields required by the API. You can add one or more fields.
          "x" : {                                  // The name of the field.
            "description" : "Category",                // The description of the field.
            "type" : "string",                     // The type of the field.
            "optional": true                       // Specifies whether the field is optional.
          },
          "y" : {
            "description" : "Value",
            "type" : "int"
          }
        }
      }
    },
    "config" : {                                 // The configuration of the widget. It consists of the UI elements that are displayed in the editor.
      "paxis" : {
        "type" : "group",                        // Specifies that the element is a group. For more information, see Description of the config field.
        "name" : "Label",
        "children" : {
          "dx" : {
            "type" : "text",                    // Specifies that the element is a text. For more information, see Description of the config field.
            "name" : "Distance from the label to the center",
            "default" : 220
          }
        }
      },
      "title" : {
        "type" : "group",
        "name" : "Title",
        "children" : {
          "value" : {
            "hasVisibility" : "true",
            "visible" : "true",
            "type" : "text",
            "name" : "Title",
            "default" : "This is a title"
          },
          "font-size" : {
            "type" : "number",                 // Specifies that the element is a number. For more information, see Description of the config field.
            "name" : "Font",
            "min" : 10,
            "default" : 32,
            "max" : 100
          },
          "text-align" : {
            "name" : "Alignment",
            "type" : "select",                // Specifies that the element is a drop-down list. For more information, see Description of the config field.
            "options" : [
              {"name" : "Left", "value" : "left"},
              {"name" : "Right", "value" : "right"},
              {"name" : "Center", "value" : "center"}
            ],
            "default" : "center"
          },
          "color" : {
            "name" : "Font color",
            "type" : "color",                  // Specifies that the element is a color. For more information, see Description of the config field.
            "default" : "#fff"
          },
          "background-color" : {
            "name" : "Background",
            "type" : "color",
            "default" : "#000"
          }
         }
        }
      }
    },
  "api_data":{                               // The API data. You can add one or more pieces of data.
    "source" : [                             // The name of the API. It must be the same as the API name in the apis field. The size of data contained in this field cannot exceed 6 KB.
      {"x": "General goods", "y" : 5},
      {"x": "General goods", "y" : 22},
      {"x": "Light goods", "y" : 22},
      {"x": "Devices", "y" : 14},
      {"x": "Mineral products", "y" : 15},
      {"x": "Steel", "y" : 15},
      {"x": "Building materials", "y" : 12},
      {"x": "Food", "y" : 12},
      {"x": "Grain", "y" : 28}
    ],
  },
  "events": {                              // The global event parameters.
    "event-name": {                        // The name of the event.
      "description": "Event description",           // The description of the event.
      "fields": {                          // Specifies one or more fields.
        "value": {                         // The name of the field.
          "description": "Description"          // The description of the field.
        }
      }
    }
  },
  "publicHandler": {
    "show": {
      "name": "Display",
      "description": "Description",
      "type": "object",                  // Valid values: object, array, null, and any. The value any indicates any type.
      "fields": {
        "data": {
          "name": "Data",
          "type": "array",
          "children": {
                    ...
          }
        }
      }
    }
  },
}

Configuration items in the config field

The config field contains the configuration items of a widget. These configuration items control the display of a widget and are used to present UI elements in the editor.

When you configure the config field, take note of the following requirements:
  • Specify the default configuration items of the widget.
  • Specify the input requirements so that the editor can identify the input information.

type in the config field allows you to configure the type and style of a widget. The type field determines the UI elements that are displayed in the editor. You can configure the type field as needed to significantly improve the quality and user experience of a widget. For more information, see Control configuration.

apis and api_data fields

  • apis field
    The apis field defines the names of APIs in a widget and the fields required by the APIs. You can specify multiple APIs and fields.
    "apis": {                                    
      "source": {                                
      "handler": "render",                     
        "description" : "The API of a multidimensional pie chart",          
        "fields" : {                              
          "x" : {                                 
            "description" : "Category",                
            "type" : "string",                     
            "optional": true                       
          },
          "y" : {
            "description" : "Value",
            "type" : "int"
          }
        }
      },
      "source2":{
          ...                                     
      }
    }
    FieldDescriptionRequiredRemarks
    apisThe APIs of a widget.YesA widget can provide multiple APIs.
    sourceThe name of an API.NoA custom value is allowed.
    handlerThe name of the method to process data returned by an API.YesThe method must be specified in the source code of the index.js file.
    descriptionThe description of an API.NoNone.
    fieldsThe fields required for an API.YesAn API can contain multiple fields.
    fields.xThe name of a field.YesA custom value is allowed.
    fields.x.descriptionThe description of a field.NoNone.
    fields.x.typeThe type of a field.NoValid values: number, string, boolean, object, and array.
    fields.x.optionalSpecifies whether a field is optional.NoA value of the BOOLEAN type is supported. true indicates that the field is optional, and false indicates that the field is required.
  • api_data field
    The api_data field defines data of one or more APIs. API names in this field must be the same as those in the apis field. The size of data contained in the api_data field cannot exceed 6 KB. For more information, see the comments.
    "api_data":{                          
      "source" : [                       
        {"x": "General goods", "y" : 5},
        {"x": "General goods", "y" : 22},
        {"x": "Light goods", "y" : 22},
        {"x": "Devices", "y" : 14},
        {"x": "Mineral products", "y" : 15},
        {"x": "Steel", "y" : 15},
        {"x": "Building materials", "y" : 12},
        {"x": "Food", "y" : 12},
        {"x": "Grain", "y" : 28}
      ],
    }
    FieldDescriptionRequiredRemarks
    api_dataThe data of APIs.YesA widget can contain data of one or more APIs.
    sourceThe name of an API.NoThe API name in this field must be the same as that in the apis field. The size of data contained in the field cannot exceed 6 KB.

Specifications of interaction events

Interaction events of DataV are controlled by the emit method (triggered in the widget code) and the events field in the package.json file.

  • events field
    The events field is under the datav field and is at the same level as the config field. The events field defines the name, description, and variable name of an interaction event.
    {
      "events": {                 
        "click-me": {      "description": "Click-triggered event",           
          "fields": {                            
            "value": {                        
              "description": "Click value" 
            }
          }
        }
      }
    }
    FieldDescriptionRequiredRemarks
    click-meThe name of an event.YesA custom value is allowed.
    descriptionThe description of an event.NoThis field is used to describe the usage of an event.
    fieldsThe fields.YesThis field can contain the names and descriptions of multiple fields.
    fields.valueThe name of a field.YesA custom value is allowed.
    fields.value.descriptionThe description of a field.NoNone.
  • emit method
    emit is a basic method that passes event names and data in a widget as parameters. After this method is triggered, other widgets can obtain the parameter values of the widget based on the variable name. This method is implemented in the source code of the index.js file. For more information, see the comments.
    render: function () {
      this.container.on('click', () => {
        this.emit('click-me', data)            // data must be an object, instead of a value. The attribute name is the variable name.
      })
    }

type field

The type field defines the type of a widget. For more information, see the comments.
type: ["regular_bar", ...]  // One widget can belong to multiple groups. Multiple widget types are separated by underscores (_), for example, "type1_type2".
  {                      // The common widget types.
    regular: "Regular chart",
    map: "Map", 
    media : "Media", 
    network: "Network", 
    text: "Text", 
    interact: "Interaction",
    material: "Material"
  }

publicHandler field

The publicHandler field defines a behavior event of DataV. Example:

"publicHandler": {
  "select": {
    "name": "select",
    "description": "Select an option",
    "type": "object",    
    "fields": {
      "data": {
        "name": "Data",
        "type": "array",
        "children": {
               ...
        }
      }
    }
  }
}

In the preceding example, a select behavior event is registered. The index.js file must implement the select method. Otherwise, an error is returned if the select method is executed.

Important
  • If you do not implement the show, hide, and updateOptions methods, DataV automatically registers and implements these methods.
  • You can manually implement the updateOptions method. If the manual operation is not performed, DataV calls the render method to implement the updateOptions method.
FieldDescriptionRequiredRemarks
nameThe name of an event.YesThe event name is used in node-based programming configurations.
descriptionThe description of an event.NoThere is no limit on the number of characters in a description.
typeThe type of the first input parameter of an event.NoOptional. The value is fixed to object.
fieldsThe field.NoNone.
fields.data.nameThe name of a field.YesNone.
fields.data.descriptionThe description of a field.NoNone.
fields.data.typeThe type of a field.YesOptional. Valid values: number, string, boolean, object, and array.
fields.data.childrenThe subnode.NoThis field must be specified if fields.data.type is set to object or array.
fields.data.defaultThe default value.NoThis field must be specified if fields.data.type is set to number, string, or boolean.
fields.data.optionalSpecifies whether a field is optional.NoOptional. This field takes effect when fields.data.type is set to boolean. true indicates that the field is optional, and false indicates that the field is required.