zg-param

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

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>

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). Also, as a non-visual element, CSS styling does not apply to <zg-param>.

Example Usage

&lt;zing-grid src="https://cdn.zinggrid.com/datasets/user-roles.json"&gt;
  &lt;zg-column index="firstName" header="First"&gt;&lt;/zg-column&gt;
&lt;/zing-grid&gt;

name

String

Description

Name of parameter.

Default Value

""

Accepted Values

  • "adapter"
  • "idKey"
  • "newIndexPath"
  • "recordPath"
  • "nodePath"
  • "searchKey"
  • "search"
  • "sortByKey"
  • "sortBy"
  • "sortDirKey"
  • "sortDir"
  • "startAtKey"
  • "startAtValue"
  • "limitToKey"
  • "limitTo"
  • "pageKey"
  • "countPath"
  • "cursor"
  • "loadByPage"
  • "loadByScroll"
  • "hasNextPath"
  • "nextPath"
  • "nextIDPath"
  • "nextIDKey"
  • "hasPrevPath"
  • "prevPath"
  • "prevIDPath"
  • "prevIDKey"
  • "pageBase"
  • "collection"
  • "subscription"
  • "createOptions"
  • "readOptions"
  • "updateOptions"
  • "deleteOptions"
  • "src"
  • "method"
  • "headers"
  • "queryString"
  • "body"
  • "bodyMethodSuffix"
  • "createBody"
  • "readBody"
  • "updateRowBody"
  • "updateCellBody"
  • "deleteBody"
  • "exclude"
  • "requestType"
  • "mode"
  • "restmode"
  • "createCustomFunction"
  • "readCustomFunction"
  • "updateRowCustomFunction"
  • "updateCellCustomFunction"
  • "deleteCustomFunction"
  • "serverErrorMessage"
  • "serverErrorPath"
Demo

value

String

Description

Value of "name" parameter

Default Value

""

Accepted Values

  • '{"src":"http://example.com/deletestate/","method":"GET"}'
Demo

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
NameExample InputDescriptionRelated AttributesDemo
adapterfirebaseAdapter 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 neccessary 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 developer has option to specify if preferred.
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.
startAtKey"startAt"The query parameter that specifies the start location. Must specify either nextPath, nextIDPath, pageKey or startAtKey when using loadByPage or loadByScroll.
startAtValuetrueBoolean 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.
limitTo10Sets the page size. Uses ZingGrid page size by default, so should not set.
pageKey5The 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.
cursortrueBoolean 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
loadByPagetrueBoolean 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.
loadByScrolltrueBoolean 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.
pageBase0If loadByPage enabled, sets this to base page. The default is 1.
collection"addresses"Specific to the firebaseSDK. Sets the firebase collection to use.
subscriptiontrueSpecific to the firebaseSDK. Set to true if you want to use subscription mode.
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. 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.
updateRowOptions'{"method": "PATCH", "body": "buildUpdate"}'Sets the options for UPDATE row request. 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.
updateCellOptions'{"method": "PATCH", "body": "buildUpdate"}'Sets the options for UPDATE cell request. 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.
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. 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.
deleteOptions'{"exclude": true}'Sets the options for DELETE 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.
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 tradition REST URL construction and method setting. The method settings for restmode="manual" is GET = GET and the all ohther = 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 rawData, method, and src 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 rawData, method, and src 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 rawData, method, and src 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 rawData, method, and src 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 rawData, method, and src 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.
excludetrueIf enabled, method will not call the external REST API.
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.
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.

CSS Variables

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

CSS Selector

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