3.1.1.12 Slicer

The Slicer entity represents a Slicer in the spreadsheet. The protocol server supports retrieving the Slicer through HTTP GET verb as well as applying changes to the current state of the slicer through HTTP POST and PUT verbs.

When a request is made using a GET:

  • If a URL parameter with a key of "$format" and value of "json" is passed, or the ACCEPT HTTP header, as specified in [RFC2616] fits the content type: "application/json" then the protocol server will return a JSON text representing the items in the requested Slicer. The protocol server recognizes URL parameters listed in the following table.

    Parameter Name

    Description

    $skip

    An unsigned integer representing the index of the first slicer item that is to be returned by the protocol server. If not specified, the default value is 0.

    $top

    An unsigned integer representing the maximum number of slicer items that are to be returned by the protocol server. If not specified, the default value is 100. The maximum number of slicer items returned is 100.

The JSON object returned by protocol server has members listed in the following table.

Member Name

Member Value

totalItemCount

A JSON number value representing the total number of items in a Slicer. MUST be present.

ItemOffset

A JSON number value representing the 0-based index of the first item returned in the items array.  MUST be present

hasEffectiveSelection

A JSON boolean value representing some of the slicer items are in unselected state. MUST be present.

NextOffset

A JSON number.

Items[]

A JSON array containing data about slicer items.

Items[].displayName

The JSON string value representing the display name of the slicer item.

Items[].uniqueName

The JSON string value representing the unique name of the slicer item. This name MUST be used when programmatic referencing the slicer item in the slicer update operation.

items[].unselected

The JSON boolean value representing that this item has been unselected. Present only when true.

items[].noData

The JSON boolean value representing that this item has no data. Present only when true.

When a request is made using PUT or POST:

If a URL parameter with a key of "$format" and value of "json" is passed, or the ACCEPT HTTP header, as specified in [RFC2616] fits the content type: "application/json" then the protocol server interprets the body of the HTTP request as a JSON text. The JSON object expected by protocol server has members listed in the following table.

Member Name

Member Value

parameters

A JSON nested object representing the operation parameters passed to the protocol server. MUST be present.

parameters.selectionMode

A JSON string value representing the way the slicer state needs to be modified. Supports the following string values:

  • cumulative

  • clearFilter

  • selectedOnly (this is the default)

parameters.selected[]

A JSON array of JSON string values representing unique names of slicer items that are to be selected. MUST be ignored if the value of selectionMode is set to clearFilter.

parameters.unselected[]

A JSON array of JSON string values representing unique names of slicer items that are not to be selected. MUST be ignored if the value of selectionMode is set to clearFilter or selectedOnly.