Datagrid Configuration component
Create This Page Sample PageDatagrid Configuration components are the foundation for building Datagrid pages, and render in a complex variety of ways based on what is selected in the Datagrid Configuration component.
The Component
-
Datagrid Configuration components are complex, please closely follow the instructions below when creating the component.
Tip: If you are using .csv for your original file, do not enter data with a comma (like "January 1, 2020" or "Anoka, MN") in your original file, because the system will read the comma as a break and insert the data following the comma ("2020" or "MN") in the next column. This will also shift all other following data for that row to the next column.
Source File: the data types allowed are tab delimited (.txt), comma delimited (.csv), JSON, or XML. Creating the source file is a complex process by itself, please see the instructions on this page for creating your source file and uploading it into Tridion. Once your file has been uploaded into Tridion, select it by clicking the browse folder icon
at the end of the Source File field, and then navigate to the file in Tridion and double-click on it.
- Source Data Type: select one of the following options: tab, csv, json, or xml. This must match the data type used when creating the Source File.
- Grid or Table: select grid or table from the drop-down menu; this sets your datagrid view on the published page. See examples of the grid and table views.
- Target div tag ID: if you are going to have just one datagrid on your page, you can leave the default entry for this field ("dataTable"). If you intend to have multiple datagrids on your page, this field needs to have a unique ID for each grid. You can put whatever you want in the field, like "presidents" or "erasers," just as long as it doesn't match what was entered in a different grid.
- Table Width: enter the width, in percentage, that the datagrid should take up on your page. We strongly recommend using the 100% default, as the narrower you go, the more your columns will get squished.
- Resizable columns (grid view only): select True or False. If set to True, this allows web users to narrow or widen the columns on the datagrid by clicking and dragging the column edges. If set to False, users will not be able to change the column widths.
- Drag and Drop columns (grid view only): select True or False. If set to True, web users will be able to click a column on the page and drag/drop it into a different place. This allows users some control over how they view and sort data. If this field is set to False, the columns will remain locked in place and users will not be able to move them.
- Sortable columns: select True or False. If True, web users can sort the columns in either ascending order (A to Z, 1 to 99, etc.) or descending order (Z to A, 99 to 1, etc.). If set to False, users will not be able to sort columns.
- Data is filterable: select True or False. If True, web users will be able to filter the data in individual columns by searching in the filter box(es) at the top of the columns. If set to false, users will not be able to filter data.
- Show Filter Row (grid view only): select True or False. If set to True, a row for filtering data (which looks like a bunch of search boxes) will appear above the first row of data in the grid. If set to False, this row for filtering data will not appear on the grid.
- Striped Rows: select True or False. If set to True, the background color of the rows in the datagrid will alternate between white and a subtle gray. If set to false, all datagrid rows will be white.
- Table pagination: select True or False. If set to True, users will be given the ability to move back and forth between pages in the datagrid. If set to false, the page navigation will be removed and all of the data rows will be visible in a single datagrid.
- Auto Height (grid view only): select True or False. If True, the height of the grid will be equal to the total height of all the grid rows. We recommend this if you have pagination (#12) set to True. If set to False, the grid will not equal the total height.
- The tool-tip help text that appears when mousing over the detail view toggle arrow (grid view only): enter the text that should appear when a user hovers over the expand/collapse arrow next to a row of information. If you are using a Table view, you can skip this field.
- Detail View Column Count (grid view only): set the number of columns that appear in each row of the detail view window (the detail view is what appears when a user clicks the expand arrow next to a row of information). If you are using the Table view, you can skip this field.
- Detail View Height (grid view only): set the height in pixels for the detail view area.
- Column definition: for each column in your source file (item #1), you need to create an equivalent entry in your datagrid configuration component. For each column, you will need to complete the set of fields below. The Datagrid Configuration component displays one set of Column Definition fields by default, which you can use for the first column in your source file. Click the green plus sign
to create additional sets of Column definition fields for the remaining columns in your source file.
- Column ID: create a unique ID for your column. The unique ID must be all one word without spaces. What you enter in this field cannot match any other Column IDs created in this datagrid configuration component.
- Data Type: select the type of data used for this column in your source file. Your options are:
- String: this is any combination of letters and numbers, like a phrase or sentence. **Pick this if you are unsure which data type to select.**
- Date: use this if the data in the column contains only dates. The default display for dates is the following format: "Wed Jan 01, 2020 00:00:00 GMT-0600 (Central Standard Time)," regardless of how the date was entered in the original file. This format can be changed through the Column Data Format field below.
- Number: use this if the data in the column contains only numbers. The data can contain a mix of integers and floating numbers.
- Float: This refers to numbers with decimals in them, like 1.5 or 4.23434, which are called floating numbers. The data for this field can contain a mix of integers and floating numbers.
- Int: This refers to integers, which are whole numbers (1, 10, 200, etc.). Select this if the data in your column contains only integers. Any floating numbers in the data will be converted to integers automatically by the system, through the removal of the decimal point and any numbers behind it (a number like 2.7345 will be converted into a 2, the system simply removes the decimal numbers and does not round up).
- Bool: This refers to Boolean data, which is True or False (or can equate to True or False). Use this only if all the data in your column meets this criteria.
- URL: Use this if the data in your column only contains URLs to websites or webpages. Anything entered in the field will be turned into a link, regardless of whether it is actually a link or not.
- Display column: select True or False. If True, the data in this column will be displayed on your datagrid. If False, the data will not be displayed in the default view of the datagrid. This allows you to either a) hide columns of data from the grid view, but still display them in the detail view or b) hide columns of data from the grid entirely, without having to remove those columns of data from the original csv, tab, json, or xml file.
- Display in Detail View (grid view only): select True or False. If set to True, the data in this column will only show in the expandable Detail view (note: if you selected True for the Display column field, it will show in both the default datagrid view and the detail view). If set to False, the data in this column will display as a column UNLESS you have also selected False in the "Display column" field - in which case the data will not display at all in the datagrid.
- Column Heading: enter the word or phrase that should appear as the column header (or field name, if this column is displayed in the Detail View) in the datagrid.
- Column Width: (optional) set the width for your column in the datagrid. It can be set using percentages or pixels. If you don't enter anything in this column, the datagrid will automatically size your content to fit on all devices. Please test your settings on mobile devices as well as desktops, to ensure that your grid is readable on all devices.
- Column Header Alignment: select left, center, or right to align the column header text.
- Column Data Alignment: select left, center, or right to align the column data text.
- Column Data Format: (optional) The majority of users will not enter anything in this field. If you selected Date, Number, Float, or Int in the Data Type field, you can further adjust how you want that data to display in the datagrid. Please click on the title of this field ("Column Data Format") and, in the window that appears, follow the instructions for formatting your data as you wish.
- If your data is XML, enter the base XML node name that occurs in your record sets: (optional) you only need to complete this field if your Source Data Type (#2) is XML. Click the title of this field to open a pop-up window that can help you identify your XML node name.
Component Templates
There is only one component template for the Datagrid Configuration component. However, there are lots of options for how to display your datagrid, and those options are controlled by the Datagrid Configuration component. There are two main ways to render a datagrid, either in a grid or in a table, and those are described in more detail below.
-
This is what a datagrid looks like when the Grid View (field #3) is selected in the Datagrid Configuration component. Many of the features shown below can be enabled or disabled. You can also view a datagrid in action on the datagrid sample page.
- The entire width of the grid shown above is set in the Table Width (#5) field.
- If True is selected for both fields Data is filterable (#9) and Show Filter Row (#10), then a filter row will appear above all columns in the grid as shown above. Users can search within a specific column by typing in the respective filter box for that column.
- If True is selected for Striped Rows (#11), then a subtle gray background color will be applied to every other row in the datagrid.
- If True is selected for Table pagination (#12), then pagination options will appear at the bottom of the datagrid.
- Field #17, Column definition, is where you enter a variety of settings for each column in your datagrid.
- The Display column (#17.c) field makes the column, and its data, appear in the datagrid when True is selected.
- The Column Heading field (#17.e) is where the title of the column is entered, and the Column Header Alignment (#17.g) is where the text alignment (left, center, right) for the column title can be set.
- The Column Data Alignment (#17.h) field, not indicated above, is where you can align the data text in the column.
- The Column Width (#17.f) field allows you to set the width of the column.
- Columns can be resized by users, if True is selected in the Resizable Columns (#6) field. The picture below shows an example of a column that has been resized.
- Columns can also be moved by website users, if True is selected in the Drag and Drop columns (#7) field. The picture below shows a column being moved. When trying to move a column, if the user's cursor is not located between columns, a red circle with a line through it will appear to indicate the column cannot be moved to the current location (as seen in the top row of the picture below). When the cursor is correctly located between columns, a green line will appear between the columns along with a checkmark in a green circle. If the cursor is released at that location, then the column will successfully move.
- Columns can also be sorted, if True is selected in the Sortable columns (#8) field.
- With a grid view, you can also display more information for each row inside of a Detail View. Columns are converted to rows in the Detail View, if True is selected in the Column definition Display in Detail View field (#17.d). The information entered in the Column Heading field (#17.e) is converted into a row header in the Detail View. The Detail View Column Count field (#15) allows you to set how many columns appear in your detail view, and the Detail View Height field (#16) allows you to set the overall height of the detail view window.
The datagrid Table View (field #3) is similar to the Grid View listed above, but the Table View lacks many of the features that the Grid View has (like the Detail view or movable columns). You can view a datagrid table view in action on the datagrid sample page.
- The entire width of the grid shown above is determined by what is entered in the Table Width (#5) field.
- If True is selected for the Data is filterable (#9) field, then a single search box will appear at the top of the table. Users can select the column they wish to filter by using the drop-down menu located to the left of the search box.
- If True is selected for Striped Rows (#11), then a subtle gray background color will be applied to every other row in the datagrid.
- If True is selected for Table pagination (#12), then pagination options will appear at the bottom of the datagrid.
- Field #17, Column definition, is where you enter a variety of settings for each column in your datagrid.
- The Display column (#17.c) field makes the column, and its data, appear in the datagrid.
- The Column Heading field (#17.e) is where the title of the column is entered, and the Column Header Alignment (#17.g) is where the text alignment (left, center, right) for the column title can be set.
- The Column Data Alignment (#17.h) field, not indicated above, is where you can align the data text in the column.
- The Column Width (#17.f) field, not indicated above, allows you to set the width of the column.
- Columns can also be sorted by users when they click on a column header, if True is selected in the Sortable columns (#8) field.