|
| 1 | +# Building a Table |
| 2 | + |
| 3 | +Table construction happens by interacting with an instance of an `ITableBuilder`. Broadly, `Tables` consist of 3 parts: columns, which are composed of `ColumnConfigurations` and `Projections`, and `TableConfigurations`. An `ITableBuilder` has methods that accept all three of these objects. |
| 4 | + |
| 5 | +* [Column](#column) |
| 6 | + * [ColumnConfiguration](#columnconfiguration) |
| 7 | + * [Projection](#projection) |
| 8 | +* [Combining ColumnConfiguration and Projections](#combining-columnconfiguration-and-projections) |
| 9 | +* [TableConfiguration](#tableconfiguration) |
| 10 | + * [ColumnRole](#columnrole) |
| 11 | + |
| 12 | +## Column |
| 13 | + |
| 14 | +A column is a conceptual (`ColumnConfiguration`, `Projection`) pair that defines data inside a [Table](#table). |
| 15 | + |
| 16 | +### ColumnConfiguration |
| 17 | + |
| 18 | +A `ColumnConfiguration` contains metadata information about a column. For example, it contains the column's name and description, along with `UIHints` that help GUI viewers know how to render the column. |
| 19 | + |
| 20 | +Typically, `ColumnConfigurations` are stored as `static` fields on the `Table` class for the `Table` being built. For example, |
| 21 | + |
| 22 | +```cs |
| 23 | +[Table] |
| 24 | +public sealed class WordTable |
| 25 | +{ |
| 26 | + ... |
| 27 | + |
| 28 | + private static readonly ColumnConfiguration lineNumberColumn = new ColumnConfiguration( |
| 29 | + new ColumnMetadata(new Guid("75b5adfe-6eee-4b95-b530-94cc68789565"), "Line Number"), |
| 30 | + new UIHints |
| 31 | + { |
| 32 | + IsVisible = true, |
| 33 | + Width = 100, |
| 34 | + }); |
| 35 | + |
| 36 | + private static readonly ColumnConfiguration wordCountColumn = new ColumnConfiguration( |
| 37 | + new ColumnMetadata(new Guid("d1c800e5-2d19-4474-8dad-0ebc7caff3ab"), "Number of Words"), |
| 38 | + new UIHints |
| 39 | + { |
| 40 | + IsVisible = true, |
| 41 | + Width = 100, |
| 42 | + }); |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +### Projection |
| 47 | + |
| 48 | +A column's `Projection` is a function that maps a row index for a column to a piece of data. Projections are normally constructed at runtime by a `Build` method, since they depend on the data inside the final table. The SDK offers many helper methods for constructing `Projections`, such as |
| 49 | +* `Projection.Index(IReadOnlyList<T> data)`, which projects a column index `i` to `data[i]` |
| 50 | +* `Projection.Compose(this IProjection<T1, T2>, Func<T2, TResult>)` which composes one `IProjection` with another method |
| 51 | + |
| 52 | +For example, suppose we have a collection of `LineItem` objects that each have two properties: `LineNumber` and `Words`. We can use the above helper methods to create the following projections: |
| 53 | + |
| 54 | +```cs |
| 55 | +var baseProjection = Projection.Index(myLineItemCollection); |
| 56 | + |
| 57 | +var lineNumberProjection = baseProjection.Compose(lineItem => lineItem.LineNumber); |
| 58 | +var wordCountProjection = baseProjection.Compose(lineItem => lineItem.Words.Count()); |
| 59 | +``` |
| 60 | + |
| 61 | +## Combining ColumnConfiguration and Projections |
| 62 | + |
| 63 | +If we have the `ColumnConfigurations` and `Projections` above, we can add them to the table we're building by calling `ITableBuilder.AddColumn`: |
| 64 | + |
| 65 | +```cs |
| 66 | +tableBuilder.AddColumn(this.lineNumberColumn, lineNumberProjection); |
| 67 | +tableBuilder.AddColumn(this.wordCountColumn, wordCountProjection); |
| 68 | +``` |
| 69 | + |
| 70 | +Note that _every_ column a table provides must be added through a call to `ITableBuilder.AddColumn`, even if they're not used in a `TableConfiguration` (see below). |
| 71 | + |
| 72 | +## TableConfiguration |
| 73 | + |
| 74 | +Some tables may have _many_ columns available. In these situations, it is not useful for a user to be shown every single column at once. A `TableConfiguration` describes groupings of columns that should be used together, along with metadata information such as `ColumnRoles`. Every `Table` must provide at least one `TableConfiguration`. |
| 75 | + |
| 76 | +For example, here is a `TableConfiguration` that contains both of columns above: |
| 77 | + |
| 78 | +```cs |
| 79 | +var tableConfig = new TableConfiguration("All Data") |
| 80 | +{ |
| 81 | + Columns = new[] |
| 82 | + { |
| 83 | + this.lineNumberColumn, |
| 84 | + this.wordCountColumn, |
| 85 | + }, |
| 86 | +}; |
| 87 | +``` |
| 88 | + |
| 89 | +You also specify [Special Columns](../Glossary.md##special-columns) in a `TableConfiguration`. |
| 90 | + |
| 91 | +Once a `TableConfiguration` is created, it is added to the table we're building by calling `ITableBuilder.AddTableConfiguration`: |
| 92 | + |
| 93 | +```cs |
| 94 | +tableBuilder.AddTableConfiguration(tableConfig); |
| 95 | +``` |
| 96 | + |
| 97 | +It is also recommended to set a default `TableConfiguration`: |
| 98 | +```cs |
| 99 | +tableBuilder.SetDefaultTableConfiguration(tableConfig); |
| 100 | +``` |
| 101 | + |
| 102 | + |
| 103 | +### ColumnRole |
| 104 | + |
| 105 | +A `ColumnRole` is metadata information about a column that defines the column's role in data presentation. For example, a column that contains a `Timestamp` whose value indicates when an event occured relative to the start of a `DataSource`](#datasource)` may be marked as a "start time" Column: |
| 106 | + |
| 107 | +```cs |
| 108 | +tableConfig.AddColumnRole(ColumnRole.StartTime, relativeTimestampColumnConfiguration); |
| 109 | +``` |
| 110 | + |
| 111 | +# More Information |
| 112 | +There are many other things you can do with your `Tables`, such as adding `TableCommands` or configuring its default layout style. For more information, refer to the [Advanced Topics](./Advanced/Overview.md). |
0 commit comments