Docs

<zg-param>

Interactive Storybook Playground

ZingGrid has a predefined set of parameter name values which have default behavior for fetching and receiving data.

Image of the DOM relationship for the zg-param web component tag

ZGParam Relationships
Component Relationship Type Ancestor
ZGData Parent Manual n/a

Related Web Components

Usage

<zg-param> name values are an extension of the ZingGrid library and are used to increase and alter fetching data or alter data on return from fetch.

<zing-grid 
  pager
  page-size="5"
  layout="row"
  layout-controls="disabled"
  viewport-stop>
  <zg-caption>
    ZingGrid Star Wars Server Paging
    <span class="button" id="reloadBtn">Reload Demo</span>
  </zg-caption>
  <zg-data>
    <!-- define the main source for the API -->
    <zg-param name="src" value="https://swapi.py4e.com/api/people/"></zg-param>
    
    <!-- define the path in the JSON to get the array of results. 
        In this case it is body.results -->
    <zg-param name="recordPath" value="results"></zg-param>
    
    <!-- if loadByPage is set to true it will go to the 
      server for each new page of data -->
    <zg-param name="loadByPage" value="true"></zg-param>
    
    <!-- define the "page" query parameter -->
    <zg-param name="pageKey" value="page"></zg-param>

    <!-- Need to tell ZG how many records were returned so it knows
        how to divide up the page-size -->
    <zg-param name="countPath" value="count"></zg-param>
    
    <!-- define the path in the result JSON to find next/prev urls -->
    <zg-param name="nextPath" value="next"></zg-param>
    <zg-param name="prevPath" value="previous"></zg-param>
    
  </zg-data>
  <zg-colgroup>
    <zg-column index="name"></zg-column>
    <zg-column index="height"></zg-column>
    <zg-column index="mass"></zg-column>
    <zg-column index="hair_color"></zg-column>
    <zg-column index="eye_color"></zg-column>
    <zg-column index="skin_color"></zg-column>
  </zg-colgroup>
</zing-grid>
Top

Attributes

<zg-param> is a non-visual element used to pass the configuration options for the <zg-data> element more cleanly via name-value pairs. The element is not required, though it is preferred, as everything set within a <zg-param> element can also be set directly on <zg-data> via the config attribute (developers should note this when setting complex values for the value attribute to use JSON encoded values). As a non-visual element, CSS styling does not apply to <zg-param>.

Example Usage

<zing-grid src="https://cdn.zinggrid.com/datasets/user-roles.json">
  <zg-column index="firstName" header="First"></zg-column>
</zing-grid>

name

String

Description

Name of parameter

Default Value

""

Accepted Values

Demo

value

String

Description

The value for given data key. If the value is an object, format as JSON encoded version of string.

Default Value

""

Accepted Values

Demo
Top

Name Attribute Values

The list below is detailed information about the name values used in <zg-param>. The example input column demonstrates the type of value to feed to the name attribute. The related attributes column shows other parameters that usually go in conjunction with the current one.

zg-param name Values
Name Example Input Description Related Attributes Demo
adapter firebase Adapter is a shortcut to set known options for specific third party datasets. Currently supports graphql and firebase. Developers could register their own custom adapters. For more information on custom adapters, visit Guides > ZingGrid Object > registerAdapter().
idKey "state" In the case of non-key based objects, the idKey can be set to indicate the id to send back to the datasource on CRUD commands. For example, if the READ URL was https://zinggrid-named.firebaseio.com/ then the UPDATE would be https://zinggrid-named.firebaseio.com/VALUE_OF_IDKEY. Null
newIndexPath "newId" Specifies the path of the insert or CREATE response that returns an object to indicate the key value of the new record. By default, it is set to the idKey or the raw value of the response so it would not be necessary to set this property.
recordPath "data.result" | "result" Sets the path of the JSON object response to where the grid data is located. When not specified, it is assumed that the whole JSON object response is the grid data. This value takes in dot notation. Null
nodePath "node" Sets the path of the JSON object within the array. When not specified, it is assumed that the array contains the JSON object. This value takes in dot notation. Null
searchKey "searchBy" | "searchOn" The query parameter to specify the search value
"search term" The value to search by. This is automatically generated when search using <zg-search>, but the developer has option to specify if preferred.
serverFilter "true" Boolean value indicating that filtering should take place on the server. Requires loadByPage to be enabled.
filterFunction "functionName" This specifies a function to call to build the url for filtering on server side filter. The function takes in a filterObj and is expected to return a URL query string or an object of name/pair values.
sortByKey "orderBy" The query parameter to specify the sort field
sortBy "column index" Specifies the property to sort on. This is automatically generated on column sort.
sortDirKey "sortDir" The query parameter that specifies sort direction
sortDir "asc" | "desc" Sets the sort direction. This is automatically generated on column sort.
batchEditStatus tokenized string Sets the status message for batch editing Null
startAtKey "startAt" The query parameter that specifies the start location. Must specify either nextPath, nextIDPath, pageKey or startAtKey when using loadByPage or loadByScroll.
startAtValue true Boolean value indicating that a value is required (instead of an index) for the next start value
limitToKey "limitTo" | "limitToFirst" The query parameter to specify limitTo amount. Required to be used in loadByScroll or loadByPage.
limitTo 10 Sets the page size. Uses ZingGrid page size by default, so should not set.
offsetKey 10 The query paramter to specify offsetValue amount. The default if "offset".
offsetValue 10 Sets the offset or number of records to skip
pageKey 5 The query parameter to specify the page. Must specify either nextPath, nextIDPath, pageKey or startAtKey when using loadByPage or loadByScroll.
countPath "total" Sets the value to path of the total count of records.
cursor true Boolean indicating if we should handle the loadByPage as cursor-based. If set to true, no count or number of pages will be displayed. Used in loadByPage
loadByPage true Boolean value enabling each page of data to be retrieved from server. Requires setting sortBy in Firebase. Must specify either nextPath, nextIDPath, pageKey or startAtKey when using loadByPage.
loadByScroll true Boolean value enabling infinite scrolling. Enabling infinite scrolling requires setting height on <zing-grid> and also setting the following: limitToKey, startAtKey, sortByKey, startAtValue, and sortBy. The first four are set when using Firebase adapter. Must specify either nextPath, nextIDPath, pageKey or startAtKey when using loadByScroll.
hasNextPath "hasNext" Path to check if there is more data.
nextPath "next" If set, looks at response packet for full link to next path. Must specify either nextPath, nextIDPath, pageKey or startAtKey when using loadByPage.
nextIDPath "next" If set, looks at response packet for ID to next path.
nextIDKey "next" If set, adds the next key to the URL to get to the next recordset. Must specify either nextPath, nextIDPath, pageKey or startAtKey when using loadByPage.
hasPrevPath "hasPrev" Path to check if there is previous data.
prevPath "prev" If set, looks at repsonse for link to previous path.
prevIDPath "prev" If set, looks at response packet for ID to prev path.
prevIDKey "prev" If set, adds the prev key to the URL to get to the previous recordset.
pageBase 0 If loadByPage enabled, sets this to base page. The default is 1.
csvCaption 'true' Specific to CSV responseType. Specify if the first line should be the caption
csvDelimiter ';' Specific to CSV responseType. Specify the separator to split the columns. ',' is default
csvHeader 'true' Specific to CSV responseType. Specify if the first line (or second if caption defined) should be the column headers
csvLineSeparator '\n' Specific to CSV responseType. Specify the separator to split the rows. '\r\n' is default
tableHide true Hide the table referenced in tableData
tableHead ["head", "age"] Specifies the values that should be used for the grid's header
tableDataFormat html | text Specifies if the grid should copy the full html value of the data rows or just the text data.
tableHeadFormat html | text Specifies if the grid should copy the full html value of the header row or just the text data.
collection "addresses" Specific to the firebaseSDK. Sets the firebase collection to use.
subscription true Specific to the firebaseSDK. Set to true if you want to use subscription mode.
dataTable "employee_list" Specific to the dexieCloud and supabaseJS adapter. Sets the table to use for CRUD operations.
createOptions '{"method": "POST", "body": "buildInsert"}' Sets the options for CREATE request. Options are formatted as a JSON string. Avalable options for requests: body, requestType, exclude, headers, method, mode, responseType, src, queryString. Not neccessary to set, the top-level values will be taken instead.
readOptions '{"method": "GET"}' Sets the options for READ request. Options are formatted as a JSON string. Available options for requests: body, requestType, exclude, headers, method, mode, responseType, src, queryString. Not necessary to set, the top-level values will be taken instead.
updateRowOptions '{"method": "PATCH", "body": "buildUpdate"}' Sets the options for UPDATE row request. Available options for requests: body, requestType, exclude, headers, method, mode, responseType, src, queryString. Not necessary to set, the top-level values will be taken instead.
updateCellOptions '{"method": "PATCH", "body": "buildUpdate"}' Sets the options for UPDATE cell request. Available options for requests: body, requestType, exclude, headers, method, mode, responseType, src, queryString. Not necessary to set, the top-level values will be taken instead.
updateOptions '{"row":{"method": "PATCH", "body": "buildUpdate"}}' Sets the options for UPDATE request. Options can be set to either "cell" or "row" updates, the types of updates used in ZingGrid; options are formatted as a JSON string. Available options for requests: body, requestType, exclude, headers, method, mode, responseType, src, queryString. Not necessary to set, the top-level values will be taken instead.
deleteOptions '{"exclude": true}' Sets the options for DELETE request. Options are formatted as a JSON string. Available options for requests: body, requestType, exclude, headers, method, mode, responseType, src, queryString. Not necessary to set, the top-level values will be taken instead.
src "https://url-to-your-api" Option for request type. Sets the base URL for the request. ID is automatically inserted in the src for DELETE and UPDATE requests.
createSrc "https://url-to-your-api" Option for request type. Sets the base URL for the create request.
readSrc "https://url-to-your-api" Option for request type. Sets the base URL for the read request.
updateRowSrc "https://url-to-your-api" Option for request type. Sets the base URL for the update row request.
updateCellSrc "https://url-to-your-api" Option for request type. Sets the base URL for the update cell request.
deleteSrc "https://url-to-your-api" Option for request type. Sets the base URL for the delete request.
restmode "manual" Set to "manual" if you want to turn off traditional REST URL construction and method setting. Set to "method" if you only want to use REST methods and not REST url construction. Set to "url" if you want to use REST URL construction but not REST methods. Set to "auto" if you want to use REST URL constuction and REST methods. The method settings for restmode="manual" and restmode="url" is GET = GET and the all other = POST. To update method settings, use updateCellMethod, deleteMethod, etc.
method "GET" Option for request type (GET, POST, PUT, etc). ZingGrid uses the standard request type per action, but it can overwritten with this param.
createMethod "POST" Sets the method on the create request
readMethod "POST" Sets the method on the read request
updateRowMethod "POST" Sets the method on the update row request
updateCellMethod "POST" Sets the method on the update cell request
deleteMethod "POST" Sets the method on the the delete request
headers '{"Authorization": "token ################################"}' Option for request type. Sets headers for request.
queryString "?query=value" Option for request type. Adds an additional query string to request.
body "functionName" Sets the body or query string of the request, which overwrites the ZingGrid generated query string. Can be set to a template string, string, or function name. If set to function name, the function takes in rawData, method, and src and returns an object to send as body for request.
bodyMethodSuffix "Countries" Sets the suffix for the function name that will construct the body for the request. Will set the createBody, readBody, updateRowBody, updateCellBody, and deleteBody parameters to: create + suffix read + suffix updateRow + suffix updateCell + suffix delete + suffix
createBody "functionName" Sets the body on the create request Can be set to a template string, string, or function name. If set to function name, the function takes in rawData, method, and src and returns an object to send as body for request.
readBody "functionName" Sets the body on the read request Can be set to a template string, string, or function name. If set to function name, the function takes in rawData, method, and src and returns an object to send as body for request.
updateRowBody "functionName" Sets the body on the update row request Can be set to a template string, string, or function name. If set to function name, the function takes in rawData, method, and src and returns an object to send as body for request.
updateCellBody "functionName" Sets the body on the update cell request Can be set to a template string, string, or function name. If set to function name, the function takes in rawData, method, and src and returns an object to send as body for request.
deleteBody "functionName" Sets the body on the delete request Can be set to a template string, string, or function name. If set to function name, the function takes in rawData, method, and src and returns an object to send as body for request.
createCustomFunction "functionName" Sets the function that handles the external data handling for creating new records The function takes in recordId, rawData, and options and returns an object to send as body for request.
readCustomFunction "functionName" Sets the function that handles the external data handling for reading data The function takes in options and returns an object to send as body for request.
updateCellCustomFunction "functionName" Sets the function that handles the external data handling for updating a cell of data The function takes in recordId, rawData, and options and returns an object to send as body for request.
updateRowCustomFunction "functionName" Sets the function that handles the external data handling for updating a row of data The function takes in recordId, rawData, and options and returns an object to send as body for request.
deleteCustomFunction "functionName" Sets the function that handles the external data handling for delete The function takes in recordId, rawData, and options and returns an object to send as body for request.
serverErrorMessage "Server Error: [[serverMessage]]" Sets the error message for any server errors. Use [[serverMessage]] token to set message from server
serverErrorPath "error.message" serverErrorPath: Sets the path to the server error message if response is JSON.
exclude true If enabled, method will not call the external REST API
cdataEscape true If enabled, method will escape HTML wrapped in CDATA blocks on xml decoding Null
requestType "multipart/form-data" Sets the Content Type for the request. The default is application/json.
responseType "application/xml" Sets the expected Content Type for the response. The default is application/json.
dataType "application/xml" Sets the expected data type for a static data source. The default is application/json. Null
urlSuffix "/" Any string to place at the end of a REST constructed URL. Note that this cannot be used with restmode is set to 'manual'.
mode 'cors' Sets to 'cors' to specify the settings for cors request. The external server must enable 'cors' for this to take effect.
Top

CSS Variables

There are no CSS variables available for the <zg-param> web component.

Top

CSS Selector

As a non-visual element, you should not apply styles to this tag.

Top

Slots

There are no slots available for the <zg-param> web component.

Top

[api: <zg-param>]