What is a Parameter?

A parameter is a string of characters that is replaced at run time with a defined value. Parameters are used as placeholders. There are two main types of parameters used in DiveTab: column-set or expand-set parameters, and data page parameters.

Column and Expand Set Parameters

Column set or expand set parameters identify the placeholder value with the take-parameter tag and the replacement value with the pass-parameter tag. This allows for a column-set or expand-set to be used multiple times with different summary columns.

The take-parameter tag is used in the column-set or expand-set in the definitions block of a data-area. When the column-set or expand-set is referenced in the data page, the pass-parameter tag identifies the placeholder value and the replacement value.

Here is an Closedexample of a report page using an expand-set parameter, with the columns expanded.

Example of a Column Set Parameter in use.

Here is the Closedreport page in the code, using the parameter reference $(<parameter name>).

  definitions { 
    column-set id = "pastyears" { 
      take-parameter "summary name" 
      text "$(summary name)" column = "$(summary name)" { 
        expand "Past Years" { 
          text "$(summary name) Y" column = "$(summary name) Y" 
          text "$(summary name) Y-1" column = "$(summary name) Y Y-1" 
        } 
      } 
    } 
  } 
  data-area id = "NY Data" { 
    title "Pass/Take Parameters" 
    icon "/divetab/images/Data288.png" 
  sections { 
      report-page { 
        title "RP - Parameters" 
        cplan "/cplans/basic_timeseries.cplan" 
        
        dimension "Corporate Chain" 
        column-set id = "pastyears" { 
          pass-parameter "summary name" "Cases" 
        } 
      } 
    } 
  }

Notice how Cases replaces $(summary name) in the columns.

The pass-parameter tag can be used multiple times with any available summary. For example, you can use the same column-set a second time with summary Cost.

CAUTION: If you use the time series as part of the column-set, verify that the summary you use is included in the time series.

Page Parameters

Page parameters identify which values are accepted by a target page. All dimensions are passed from a parent data page to a child data page, but only specified dimensions and values are accepted by the child page.

A link on the parent page identifies the dimension and dimension value that is passed. The target page parameter identifies which dimension, and therefore the dimension value, is accepted. The parameter appears as a QuickView on the target page with the dimension and dimension value, which allows you to change values on the target page.

The parameter tag is primarily used to identify the accepted dimensions for a target page. In addition to the basic page parameter, there are four page parameter types:

  • Anchor Date Parameters—Identifies an anchor date that is shown and changed using a QuickView. Those changes are accepted by the target page as a parameter.
  • Conditionalized Link Parameters—Identifies specific dimension values that meet certain conditions to have active links. Values that do not meet the conditions do not have active links and are therefore not passed to the target page.
  • Dimension Value Parameters—Identifies a dimension and dimension value, not visible in the page or related to the link, to pass to the target page.
  • Parameter List Parameters—Identifies a metrics, or column, that is used in a data page and can be changed using a QuickView. Those changes are accepted by the target page as a parameter.

IMPORTANT: QuickViews and their dimensions also need parameters identified to be accepted by the target page.

Here is an Closedexample of an ad hoc page.

Example of an Ad Hoc page with links to a Report page.

Here is an Closedexample of a report page after following the link for DIAGEO.

The resulting Report page after clicking the link.

Notice that the Cases total is the same. This is because a parameter is not in use, so the value is not accepted by the target page.

Here is how these Closedpages appear in the code.

  sections { 
    ad-hoc-page { 
      title "Ad Hoc Page" 
      cplan "/cplans/basic_101.cplan" 
      dimension "Vendor"
      dimcount-dimension "Resp SalesPerson" 
      text column = "Cases" { 
        link { 
          page id = "rp-param" 
        } 
      } 
    } 
  } 
  
  pages { 
    report-page id = "rp-param" { 
      title "Report Page" 
      cplan "/cplans/basic_101.cplan" 
      
      dimension "Product Name" 
      text column = "Cases" 
    } 
  }

The following example is of the same ad hoc and report pages, but with a parameter applied.

Here is an Closedexample of the report page after following the link for DIAGEO, with a parameter in use.

Notice the QuickView for Vendor with the DIAGEO value selected. The QuickView can change the dimension value without returning to the previous page. Also notice that the Cases total for the report page matches DIAGEO's total from the ad hoc page.

Here is how these Closedpages appear in the code.

  sections { 
    ad-hoc-page { 
      title "Ad Hoc Page" 
      cplan "/cplans/basic_101.cplan" 
      dimension "Vendor"
      dimcount-dimension "Resp SalesPerson" 
      text column = "Cases" { 
        value-format "#,###.00" 
        link { 
          page id = "rp-param" 
        } 
      } 
    } 
  } 
  
  pages { 
    report-page id = "rp-param" { 
      title "Report Page" 
      cplan "/cplans/basic_101.cplan" 
      parameter "Vendor"
      dimension "Product Name" 
      text column = "Cases" { 
        value-format "#,###.00" 
      } 
    } 
  }

An Anchor Date Parameter uses an Anchor Date QuickView to change the date for the data. The target page accepts the selected value.

Here is an Closedexample of a report page using an Anchor Date QuickView.

Example of a Report page with an Anchor Date QuickView.

Here is an Closedexample of the same report page with the Current Date changed to 2011-03.

Example of the same Report page with a different Anchor Date applied.

Notice how the values have changed.

Here is the Closedresulting target report page after following a Cases YTD column link.

Example of the target page passing the Current Date parameter value.

IMPORTANT: The Vendor dimension is not included as a parameter in the code, so the Vendor value is not passed to the next page.

Notice that the Current Date value is accepted from the parent page.

Here is how the Closedpages appear in the code.

  sections { 
    
    report-page { 
      title "Vendor Report" 
      cplan "/cplans/timeseries_qv.cplan" 
      quickview-set { 
        cplan "/cplans/timeseries_qv.cplan" 
        dimension-quickview "Current Date" single-selection = true all-values = false { 
          dimension "Posting Period" 
          default-values "2013-01" 
          default-last-value 
        } 
      } 
      dimension "Vendor" 
      text column = "Cases YTD" { 
        link { 
          page id = "rp-param" 
        } 
      } 
    } 
  } 
  
  pages { 
    report-page id = "rp-param" { 
      title "Product Page" 
      cplan "/cplans/timeseries_qv.cplan" 
      quickview-set { 
        cplan "/cplans/timeseries_qv.cplan" 
        dimension-quickview "Current Date" single-selection = true all-values = false { 
          dimension "Posting Period" 
          default-values "2013-01" 
          default-last-value 
        } 
      } 
      parameter "Current Date" 
      dimension "Product Name" 
      text column = "Cases YTD" 
    } 
  }

Note that the target page includes the same quickview-set as the parent page, with the QuickView dimension as a parameter.

Here is the Closedcode for the cPlan used, which defines the Anchor Date.

  cplan { 
    cbase-input "/cbases/NY.cbase" 
    
      take-parameter "Current Date" { 
      default "TODAY" 
    } 
    
    time-series { 
      date `value("Posting Period")` 
      
      anchor ```if(param("Current Date") = "TODAY", 
      today(), period_end(period("gregorian month", 
      param("Current Date"), "YYYY-MM")))``` 
      
      summary "Cost" 
      summary "Cases" 
          
      ranges { 
        year-to-date 
        month-to-date 
        current-year 
        all-quarters 
        rolling-months 3 
        rolling-months 6 
        recent-weeks 24 
        recent-months 12 label-format = "MMM" 
        all-months label-format = "MMM" 
      } 
    } 
  }

A Conditionalized Link Parameter uses a column with conditionalized links to link to a target page. A conditionalized link is a column value that must meet certain criteria in order to have an active link. Using a parameter means that values with active links can be accepted by the target page. Values without links cannot be accepted because they are not linked.

Here is an Closedexample of the Brand Report page with a conditionalized link column.

Example of a page using a conditionalized link.

For the Chain Store ID, the conditionalized link requires a value for active links. Notice that values of 0 do not have links.

Here is the Closedresulting page for value ARROWOOD.

The resulting page after following the link for ARROWOOD.

Here is how the Closedpages appear in the code.

  sections { 
    report-page { 
      title "Brand Report" 
      cplan "/cplans/basic_101.cplan" 
      dimension "Corporate Brand" 
      text column = "Cases" 
      text column = "Chain Store ID" { 
        link { 
          condition column = "Chain Store ID" 
          page id = "rp-sales" 
        } 
      }
    } 
  } 
  pages { 
    report-page id = "rp-sales" { 
      title "Customer Page" 
      cplan "/cplans/basic_101.cplan" 
      parameter "Corporate Brand" 
      dimension "Customer" 
      text column = "Cost" 
      text column = "Net Sales" 
    } 
  }

A Dimension Value Parameter uses a dimension not visible on the parent page and a dimension value specified in the code as the values passed by the parent page.

NOTE: Dimension Value Parameters are typically used for central or overview pages when you are using similar links and want to pass different values.

Here is an Closedexample of a report page with a dimension value parameter.

Example of a page using a column with a dimension value parameter.

Here is the Closedresulting page for value Gorman, accepting the hidden parameter for Premise value ON PREMISE.

The resulting page after the parameter is accepted by the target page.

The dimension Premise value ON PREMISE is not used in the parent page, so it is applied to the link block in order for the value to pass to the target page.

Here is how the Closedpages appear in the code.

  sections { 
    report-page { 
      title "Dimension Value Parameters" 
      cplan "/cplans/dim-value_param.cplan" 
      dimension "Resp Team" 
      
      text column = "Cases" 
      text column = "Cases On Premise" { 
        link { 
          page id = "pg-target" 
          parameter "Premise" "ON PREMISE" 
        } 
        value-format "#,###.00" 
      } 
    } 
  } 
  
  pages { 
    report-page id = "pg-target" { 
      title "Target Page" 
      cplan "/cplans/dim-value_param.cplan" 
      
      parameter "Resp Team" 
      parameter "Premise" 
      dimension "Product Name" 
      
      text column = "Net Sales" 
      text column = "Cost" 
    } 
  }

Notice that the dimension used in the parent page is used as a parameter in the target page.

Here is the Closedcode for the cPlan in use.

  cplan { 
    cbase-input "/cbases/NY.cbase" 
    calc "Cases On Premise" `add(value("Cases"))` filter=`(value("Premise")) = "ON PREMISE"` 
  }

A Parameterized List Parameter uses a Parameterized List QuickView to change columns on the page. The target page accepts the selected value. For example, you can change a Cases column to a Cost column using a QuickView, and this change remains on the target page.

Here is an Closedexample of a report page using a Parameterized List QuickView.

Example of a Report page using a Parameterized List QuickView.

Here is an Closedexample of the same report page with the Metric value changed to Net Sales.

The same Report page with a different Metric value applied.

Notice how the column name and values changed.

Here is the Closedresulting target report page after following a Net Sales column link.

Example of the target page passing the Metric parameter value.

IMPORTANT: The Product Name dimension is not included as a parameter in the code, so the Product Name value is not passed to the next page.

Notice how the Net Sales column is accepted from the parent page.

Here is how the Closedpages appear in the code.

  sections {
    report-page { 
      title "Product Report" 
      cplan "/cplans/metric_qv.cplan" 
      
      quickview-set { 
        cplan "/cplans/metric_qv.cplan" 
        list-quickview "Metric" single-selection = true all-values = false { 
          default-values "Cases" 
          values "Cases" "Cost" "Net Sales" "Discount" 
        } 
      } 
      
      dimension "Product Name" 
      text column = "Metric Value" { 
        link { 
          page id = "rp-param" 
        } 
      } 
    } 
  } 
  
  pages { 
    report-page id = "rp-param" { 
      title "Brand Page" 
      cplan "/cplans/metric_qv.cplan" 
      
      quickview-set { 
        cplan "/cplans/metric_qv.cplan" 
        list-quickview "Metric" single-selection = true all-values = false { 
          default-values "Cases" 
          values "Cases" "Cost" "Net Sales" "Discount" 
        } 
      } 
      
      parameter "Metric" 
      dimension "Corporate Brand" 
      text column = "Metric Value" 
    } 
  }

Note that the target page includes the same quickview-set as the parent page, with the QuickView dimension as a parameter.

Here is the Closedcode for the cPlan used, which defines the Metric and Metric Value.

  cplan { 
    cbase-input "/cbases/NY.cbase" 
    take-parameter "Metric" { 
      default "Cases" 
    } 
    calc "Metric Value" `calc(param("Metric"))` label = "$(Metric)" 
  }

See also:

Mentioned in: