Creating Shared Help Topics

This document describes how to create a shared topic (template) which is used to produce separate topics for a particular feature of the IgxGrid, IgxTreeGrid and/or IgxHierarchicalGrid components.

The main idea is to have a single topic template for a feature supported by all grids. The build process will generate separate topics, for the feature in question, for each grid component.

Currently, there are separate sets of templates for each supported language. Here are the exact locations:

• for English: /en/components/grids_templates
• for Japanese: /jp/components/grids_templates
• for Korean: /kr/components/grids_templates

These sets of templates are used by the 'generate-grids-topics' gulp task during the build process. This task is producing folders with topics for each grid (IgxGrid, IgxTreeGrid and IgxHierarchicalGrid), based on the templates. There are, also, sets of variables with their corresponding values passed as arguments to each grid during build process and used to replace key parts of the shared topics. These variables and build path are all configured in the 'generate-grids-topics' gulp task.

Here are some examples of the variables:

Variable Name	Description	Grid	Tree Grid	Hierarchical Grid
igMainTopic	Name of the grid overview topic	grid	tree_grid	hierarchical_grid
igObjectRef	Name of the instance used in code examples	grid	treeGrid	hierarchicalGrid
igComponent	Short grid component's name	Grid	Tree Grid	Hierarchical Grid
igxName	The grid component's name	IgxGrid	IgxTreeGrid	IgxHierarchicalGrid
igTypeDoc	The component specific part of the doctype links	igxgridcomponent	igxtreegridcomponent	igxhierarchicalgridcomponent
igSelector	The component's selector value for a specific grid	igx-grid	igx-tree-grid	igx-hierarchical-grid

Note: Currently all topics for the three grids are generated from the templates with the exception of the main topics: grid.md, tree_grid.md and hierachical_grid.md and some other topics that are specific to the respective grid (for example, the groupby.md is IgxGrid specific).

Note: When a new topic is created, which is specific for a particular grid only (it is not auto-generated from the templates), it must be:

• Added to the gulp watch list, so when changes are made over the file, the site would be rebuilt. (The gulp watch list is an array called included, placed in the gulpfile.js)
• Added to the end of the .gitignore file for the respective language with "!" in front of its name, so it does NOT get ignored when making changes on the file.

Based on the above example, you can 'flag' a specific paragraph or code snippet using the 'if' statement like this:

@@if (igxName === 'IgxGrid') {
	This paragraph contains specific information regarding the IgxGridComponent.
}
@@if (igxName === 'IgxTreeGrid') {
    This paragraph contains specific information regarding the IgxTreeGridComponent.
}
@@if (igxName === 'IgxHierarchicalGrid') {
    This paragraph contains specific information regarding the IgxHierarchicalGridComponent.
}

Here is an example of a 'shared' code snippet:

this.@@igObjectRef.showToolbar = true;

The above example will generate the following output for the three grids:

this.grid.showToolbar = true;

this.treeGrid.showToolbar = true;

this.hierarchicalGrid.showToolbar = true;

You can even include a whole .md file inside another one, using the 'include' statement:

@@include('./externalCode.md')

and even combine 'if' and 'include' statements:

@@if (igxName === 'IgxTreeGrid') {
    @@include('./treeGridSpecificCodeSnippet.md')
}

For more information see the gulp-file-include plugin:

https://www.npmjs.com/package/gulp-file-include

https://github.com/coderhaoxin/gulp-file-include