documentation/configuration.html

<div id="midcolumn">
	<h3>Configuration</h3>
	<div id="introText">
		<p>
			Here you will find general information about configuring NatTable and the concepts involved.
		</p>
	 </div>
	<div id="doccontent">
		<div class="chapter">
			<h5>ConfigRegistry</h5>
			<div class="content">
				<p>
					This is a global object holding the following kinds of configuration
					<ol>
						<li><a href="/nattable/documentation.php?page=styling" title="Styling">Styling</a></li>
						<li><a href="/nattable/documentation.php?page=editing" title="Editing">Editing</a></li>
						<li>Comparators for <a href="/nattable/documentation.php?page=sorting" title="sorting">sorting</a></li>
						<li>Any piece of arbitary information can be stored in this registry.</li>
					</ol>
				</p>
			</div>
		</div>
	</div>
	<div id="doccontent">
		<div class="chapter">
			<h5>UiBindingRegistry</h5>
			<div class="content">
				<p>
					This is a global object holding the following kinds of configuration
					<ol>
						<li>Key bindings </li>
						<li>Mouse bindings </li>
					</ol>
					You can find more information regarding bindings <a href="/nattable/documentation.php?page=binding" title="UI Bindings">here</a>.
				</p>
			</div>
		</div>
	</div>
	<div id="doccontent">
		<div class="chapter">
			<h5>DisplayMode</h5>
			<div class="content">
				<p>
					DisplayMode is a tag applied to a cell to identify the state the cell is in. 
					Currently the following display modes are supported:
					<ol>
						<li><i>Normal</i> - The usual state</li>
						<li><i>Select</i> - Signifies a cell is currently selected</li>
						<li><i>Edit</i> - Signifies that the cell is being edited</li>
					</ol>
					For example, a cell might be colored white in <i>normal</i> mode but a gray color might be applied to it 
					when it is in <i>select</i> mode.
				</p>
			</div>
		</div>
	</div>
	<div id="doccontent">
		<div class="chapter">
			<a name="labels"></a><h5>Cell labels</h5>
			<div class="content">
				<p>
					Cell labels are a mechanism to tie configuration to specific cells. A cell label is a string/label which is 
					attached to a cell.
				</p>
				
				<p>
					For example,
					<ul>
						<li>We might attach a label 'error' to cells which meet certain criteria. While painting all cells with the label 'error' will be painted red.</li>
						<li>We can attach a label 'checkbox' to all cell holding a boolean value. While painting all cells with the label 'checkbox' will be painted as a 'checkbox'.</li>
					</ul>
				</p>
				
				<h6>Attaching a label to a cell</h6>
				<p>
					Following the overall design convention, Layers can add labels to cells. In order to attach a label to a cell(s) you 
					need to implement the <span class="code">IConfigLabelAccumulator</span> interface. 
					The <span class="code">IConfigLabelAccumulator.accumulateConfigLabels()</span> is called on each layer. Every layer 
					can add its labels to the <span class="code">LabelStack</span>. 
				</p>	
				<p>
					The most common use cases are available out of the box, including but not limited to:
					<ul>
						<li><span class="code">CellOverrideLabelAccumulator</span> - applies labels to cell(s) containing a specified data value</li>
						<li><span class="code">ColumnOverrideLabelAccumulator</span> - applies labels to all cells in a column</li>
						<li>You can make custom implementations for your own rules</li>
					</ul>
				</p>

				<h6>Default labels</h6>
				<p>
					The name of the region the cell is in is added as a default label. For example, all cells in the body region have 
					the label <i>BODY</i> by default.
				</p>
			</div>
		</div>
	</div>
	<div id="doccontent">
		<div class="chapter">
			<h5>Layers and configuration objects</h5>
			<div class="content">
				<p>
					Configuration information is contributed by individual layers. When a layer is added to the stack it contributes 
					relevant configuration via the <span class="code">AbstractLayer.addConfiguration()</span> method. For example, 
					when the <span class="code">SelectionLayer</span> is added it contributes selection styling via the 
					<span class="code">DefaultSelectionLayerConfiguration</span>.
				</p>
				<p>
					In order to contribute configuration information you need to:
					<ol>
						<li>Implement the <span class="code">IConfiguration</span> interface. It is usually easier to override one of the 
						default configuration objects.</li>
						<li>Disable default configuration. This is done by setting 'autoconfigure' to false on the layer constructor. 
						By default a layer will automatically add its default configuration.</li>
						<li>Add your configuration to the layer using the <span class="code">AbstractLayer.addConfiguration()</span> method.</li>
					</ol>
    			</p>
    			<p>
					When the grid initializes it invokes your configuration object. At this point you can make entries in the 
					<span class="code">IConfigRegistry</span> and the UiBindingRegistry. These are global objects held by NatTable. 
				</p>
			</div>
		</div>
	</div>
</div>