The Format Tab
The Format tab is where the details of each column are configured.
Level
The Level is essentially the tab on the report. The first tab will be Level 0, the next Level 1 and so on. It will default to the same value as the last column you added.
Query
Within each level, there can be five queries. A query is basically a SQL statement (usually a Stored Procedure). All queries on the same level will appear on the same report tab. Query 0 will be shown first, then Query 1 and so on.
It will default to the same value as the last column you added.
Field Name
This is the field that comes back from the SQL query. This must exactly match the fieldname in the Stored Procedure or SQL statement (case sensitive). Ideally, this should be camelCase. If using the SQL snippet below, we'd have to create field names of businessUnitName, valueOrdersIn and lastUpdate to use the data returned.
SELECT businessUnitName, valueOrdersIn, lastUpdated
Column Title
This is the text that will appear as the column heading when the report is generated. It will default to the field name (if you press the TAB key after entering the field name). This should be user readable and short (eg. Business Unit Name). Use the Short Help if you need a longer description for your column heading.
If the title begins with fa- then it is assumed to be a Font Awesome icon (rather than the actual text). For example, fa-rocket will display the rocket icon, not the text. You'll probably need to use the Short Help to explain what the icon means.
Click Link
If you want this field to be passed as a argument to the next level (when you click on a row), then set the variable name for the value to be passed as here. For example, if this column is the salesman's name, then you could enter sman in this field and then a variable @sman = 'Aaron Ferdinand' will be passed through to the next level. The name here would obviously need to match the information expected in the PHP.
Each level can pass as many click link fields as required. For example, salesman and salesTeam. If using generic.php, you must ensure that the value you enter here is picked up and used in the executeSP function.
You can click the link icon (far right of the field) to quickly set this column as a Click Link Only (ie. no data display). This will set the alignment, format, show, sort and total. This is useful for fields such as GUIDs (eg. oppGUID) which are needed to pass through to next level but are not normally displayed.
VERY IMPORTANT. If you're adding a new click-link value that you've not used before, then you'll probably need to amend
executeSPfunction ingeneric.phpso that it picks up the value (just after the globals) and uses it (in the try block)
Alignment
You have three choices, Left, Middle (center) and Right. After picking an alignment, if the format field is empty, then it will default it for you. Left assumes a text format, Middle gives Percentage and Right uses Money. These are (by far) the most common choices, but you can override if required.
When choosing an alignment, it will also change the Show, Sort and Total toggles as appropriate.
Format
These are fairly self-explanatory. The only unusual one is function. A format of function is used in conjunction with Calculation. A function format is often used with icons.
The formats that include "Blank if Zero" will not show anything for a zero value. Those without will show £ 0 or 0 % etc.
Negative numbers will alway be shown in red. This applies to money, quantity and percentage.
When you're not sure what format to use, pick Text.
Calculation
This field is used to specify a function (in the JavaScript) that is applied to the data value returned from the Stored Function / SQL.
The field can have a single value or a comma separated list. For example,
addFunc,ordersInValue,valueInPlay
In the above example, addFunc is being passed two parameters. The parameters are columns from the report. Thus, orderInValue must be a column and so must valueInPlay (both are the field names). These columns don't have to be shown, but they must be defined as columns (not just returned by the Stored Procedure / SQL).
If you use the Quick feature (button to the right of the field), it will set the calculation and default the alignment and format as appropriate.
Hover Column
Sometimes, you want extra information to appear when you hover over a value. For example, show the business unit when hovering over a salesman's name.
- Make sure the salesman column has been added to the report. This column must be shown.
- Add the Business Unit Name column. In the Hover Column field, enter salesman (where salesman is the field name you want the hover to appear with)
- You probably want to set the Show this Column toggle to No (it doesn't make sense to have a Hover and show the column).
Show this Column
This Yes/No toggle determines where this column will appear on the report.Typical reasons to not show a column are:-
- You only want the information to be passed to the next level drill down (eg. salesTeamID, oppGUID)
- You need the information as part of a calculation
Can Be Sorted
This Yes/No toggle determines if the column will have the sort indicator in the column header field.
Total this Column
This Yes/No toggle determines if the column will have a column total. Special care needs to be taken when totally columns that are percentages. For example, if the Stored Procedure is doing a variance calculation and we just display that value row by row, then a total will not make any sense (10% + 5% + 38% etc.). If you want a variance total, then you must use the Calculation and use a function (eg. calcPercentage).
Short Help
The short help appears when the user rests their mouse over the column heading. Typically, this is a slightly longer explanation for the column - very useful when you have limited space to display the full title you'd like. Since this appears as a tooltip, you'll need to keep it to a dozen words or fewer.
Notes
These are for internal use and serve as guidance as to the purpose of column or special information about the full meaning.