In this topic

3. Writing a Styling section for article

7. Creating shared help topics

8. Updating of Data Visualization related topics

Writing an article

When writing an article about a specific component, it is important to have a plan that you stick to. This will improve the overall cohesion of the text, making it more structured and clear for the reader.

There are a few questions one can ask, when charting such plan.

1. What is this article about (objective)?

a. List required previous knowledge to better understand the concept of the topic. For instance, if the article is about a directive feature, put references to the ng directives in the beginning of the article.

b. Identify common use cases. Where would said component/directive be used in most often. Try to outline samples around said use cases.

2. What are the prerequisites to using said component/directive?** Does it depend on other components, or can it be used on its own?

3. How does one get started with using said component/directive?

4. Identify the most important feature(s) of a component/directive.

Why was a feature implemented? What problem does it solve? How important is that feature for the overall weight of the component? Can this component exist without the feature and still be perceived useful? Rank features by importance and write about the most important ones.

5. What are some common gotchas about a component/directive’s feature?

Does the feature require any previous knowledge? If yes, then refer the user to it.

6. Can we identify some problems that may occur when using said component/directive?

If yes, we can anticipate questions and have a troubleshooting section where we outline such issues and how to solve them.

7. Do we have a summary of the article and component APIs?

Since the product API docs have been made available online, the API tables in the DocFX articles are inapplicable. All API tables should be removed, if there are such in the component topics, and they should be replaced with links to the API for each component mentioned in the article. If such tables are not present, and the article is updated to mention a new component that is not present as an API link, then a link to the component's API should be included. Example of listing the mentioned components:

[IgxGridComponent API]({environment:angularApiUrl}/classes/igxgridcomponent.html)
[IgxGridComponent Styles]({environment:sassApiUrl}/index.html#mixin-igx-grid)
[IgxGridRow API]({environment:angularApiUrl}/classes/igxgridrow.html)

Also any text in the article that mentions a component class, or other class/interface that can be linked to in the API docs, should be accompanied by a link to the corresponding class in the API documentation. Example of linking a corresponding item in the article to the API documentation in the grid filtering topic:

Depending on the set [`dataType`]({environment:angularApiUrl/classes/igxcolumncomponent.html#datatype}) of the column, the correct set of [**filtering operations**](grid.md#filtering-conditions) is loaded inside the filter UI dropdown.

8. Where does one find further help related to the topic of the article?

Topic structure

The purpose of this section is to present what the structure of the topic should be and the arrangement of the main elements in it.

1. The first title of the page should be with `<h1>` tag (`#` Page Title) and it wont appear on the submenu on the right.

2. Every main title should be with `<h2>` tag (`##` Main Title).

3. Using nested titles.

Minor titles related to the main titles can be used with <h3>(###) or <h4> (####). Note: when <h4> (####) is used the title wont appear on the submenu on the right.

Writing a Styling section for article

The main purpose of the Styling section is to provide simple examples on how to style most common parts of the UI (lets say styling for alternate rows in the grid), copy/paste the code in any sample and see it working. In order to write content that fullfills the purpose, follow the steps below:

1. Give the content an `<h3>` Section header, so that it appears on the submenu on the right.

2. Start the content with the example of adding the theming index file.

3. Provide the simplest styling example, which is to extend the default theme for the corresponding feature/component. For example, when styling the paginator UI, the `igx-grid-paginator-theme` needs to be extended:

$dark-grid-paginator: grid-paginator-theme(
    $text-color: #F4D45C,
    $background-color: #575757,
    $border-color: #292826
);

4. If other elements in the feature UI are styled by another theme, add example for that theme too. For example - the buttons in the paginator UI require that a new theme for buttons is created.

5. If a theme provides a ton of parameters for styling, choose those that you decide would be the most common. You may state in one sentence what each property controls, and provide a link to the theme under the SASS API.

6. Provide the last step, which is to include the component mixin, along with two notes – the first one for scoping any mixin if needed, and the second note about penetrating the `ViewEncapsulation`, along with example on how to overcome the encapsulation.

7. Add an iframe with an example, along with a Stackblitz button

8. Examples on styling with `igx-color`, `palettes` and `schemas` are not necessary, but you may add a link to Theming engine topics as they are quite detailed.

9. When adding a section for a certain grid feature, add it for the igxHierachicalGrid and igxTreeGrid as well.

Workflow

When working on an issue for the Ignite UI for Angular DocFX Site Builder, you need to be aware of and to follow a correct status workflow. We have created a number of status labels in order to communicate well what the current status of a single issue/pull request is. The statuses are as follows:

Development - applicable to issues and pull requests

status: in-review this is the initial status of an issue. If the label is not placed, go ahead and place it.
status: in-development this is the status once you start working on an issue. Assign the issue to yourself if it hasn't been assigned already and remove the previous status and assign it an in development status.
status: by-design this is the status of an issue that has been reviewed and has been determined that the current design of the feature is such that the issue describes the correct behavior as incorrect. Remove other statuses and place this status if you've reviewed the issue.
status: third-party-issue this is the status of an issue that has been reviewed, has been determined to be an issue, but the root case is not in the Ignite UI for Angular code. Example would be browser specific bugs caused by the particular browser's rendering or JavaScript engines, or an issue with the Angular framework. Remove other statuses and place only this one if you're the one performing the investigation.
status: not-to-fix this is the status of issues that derive from our code, but have been decided to leave as is. This is done when fixes require general design and/or architecture changes and are very risky.
status: already-fixed this status indicates that the issue is already fixed in the source code. When setting this status assign the person that logged the issue so that he can verify the issue is fixed in the respective development branch. Remove other statuses and place this status if you've reviewed the issue.
status: cannot-reproduce this status indicates that you cannot reproduce the issue in the source code. A reason may be because the issue is already fixed. When setting this status assign the person that logged the issue so that he can respond with more details on how to reproduce it.
status: not a bug this is the status of an issue that you reviewed and concluded that it's not a bug. You should comment explaining the reasons why you think the issue is not a bug.
status: resolved this is the status of an issue that has been fixed and there are active pull requests related to it.

Example status workflows:

status: in-review => status: in-development => status: resolved (PR is created)

status: in-review => status: by-design (Issue can be closed)

status: in-review => status: third-party-issue (Issue can be closed)

status: in-review => status: not-to-fix (Issue can be closed)

Note: In most cases the development will be related to new topics creation or updating of existing one. Keep in mind that for each newly added topic the toc.yml should be updated with a reference to the new topic. It is recommended Additional references section to be added at the end of each topic.

Testing - applicable to pull requests

status: awaiting-test this is the initial status of pull requests. If you're performing the pull request, please place this status on it. Pull requests are accepted if and only if all status checks pass, review is performed, and the pull request has been tested and contains status: verified.
status: in-test place this status once you pick up the pull request for testing.
status: verified place this status once you've tested the pull request, have verified that the issue is fixed, and have included all necessary automated tests for the issue.
status: not-fixed place this status once you've tested the pull request and you are still able to reproduce the issue it's attempting to fix. Then assign the developer back on the pull request.

Example status workflows:

status: awaiting-test => status: in-test => status: verified (PR can be merged if all prerequisites are met)

status: awaiting-test => status: in-test => status: not-fixed => status: in-development => status: awaiting-test

Note: When you are assigned to test a PR related to new topic creation or updating an existing one:

Check the build result.
Be sure that Writing an article guidance is respected.
Check whether the embed sample is working.
Code views are working as well
Each hyperlink is working properly.
Table of content is correct.

Note: Testing a PR from Angular Samples (when new sample is added) with combination of PR related to topic update (or when new topic is added). Open both repositories and perform npm start. This will start both projects and you will see the embed sample in your topic under localhost.

Localization - applicable to issues and pull requests

Ensure that whenever a change is made to the text content the appropriate status is set:

status: pending-localization this status tells that there are changes in the localization strings that need to be translated. When you make such changes, put this status badge without removing the other applicable ones and assign a person to do the translations.

Note: This status should be set only when the PR is approved. This will indicate that no further changes will be applied.

status: localized this status is for issues that were with a pending translation status and have already been localized. Place this status label once these translation changes have been included in the current pull request, or the changes are already pulled with a different pull request.

Note: Keep in mind that when you submit a change in the EN .md files, you don't need to make the same change in the JP/KR versions. This task will be handled by the Localization team.

Fixing a bug

Depending on where the bug/change/feature was found/is planned the current version or the ongoing release version, checkout a development branches from vnext or/and master branch. vnext is the version that is going to be used upon release (next version), and master is the branch with the current state (current version available on production). If the change/fix is applicable only to the ongoing release branch (vnext) there is no need to cherry-pick to master branch as the change/fix/feature will be pushed to master branch upon release.
Run lint
Pull request your changes and reference the issue. Use the enforced commit message format with applicable type, scope, etc.
Don't forget to make the necessary status updates, as described in the workflow section.

Note: Cherry-pick to master branch only changes with high priority. There is no need to cherry-pick into master every bug fix/change from vnext> A regular mass merge PRs are going to be made from vnext into master.

Example workflow for a bug with high priority The process will look like this:

Checkout new branch from vnext. For code example purposes let's say the new branch is called fixing-bug-5423-vnext.
Commit your changes to your fixing-bug-5423-vnext branch.
Push and PR to the vnext branch.
Switch to the master branch.
Create a new branch from master. For code example purposes let's say the new branch is called fixing-bug-5423-master.
Cherry pick your commit from the fixing-bug-5423-vnext branch: git cherry-pick fixing-bug-5423-master
Push to your fixing-bug-5423-master branch and PR to the master branch.

Environment variables

The environment variables are a syntactic sugar for pointing out the location of the resources used in a topic. These variables are defined in the environment.json file of a docfx project. Each environment variable is replaced with its corresponding value during build time.

Code View Configuration

If you want to add a sample and introduce the code behind this sample to the readers, you have to add a <code-view></code-view> element. This element is rendered as a container with tabs, their respective views and a footer element containing StackBlitz and Codesandbox buttons for live editing purposes. The first tab renders the sample iframe and each following tab renders the content of a specific file, used for the development of the sample. The live editing buttons create StackBlitz and Codesandbox applications for the sample in the code view.

The <code-view></code-view> element has the following attributes:

style: The global style attribute. At runtime its values are applied to the container of the sample.

Note: It is necessary to add the height of the code-view when you create this element.

data-demos-base-url: The base url of the sample. It is recommended to assign an environment variable to this attribute.
iframe-src: The absolute path of the sample. It is recommended to assign the value of the data-demos-base-url attribute combined with the relative (relative to its base url) path of the sample.
alt (optional): This attribute is applied as an alt attribute to the iframe of the sample.

Code view example:

<code-view style="height:700px" 
           data-demos-base-url="{environment:lobDemosBaseUrl}" 
           iframe-src="{environment:lobDemosBaseUrl}/grid/grid" 
           alt="Angular data grid example">
</code-view>

Here is a brief explanation of how the code view element works. For each sample (grid-sample-1) a .json file is created (grid--grid-sample-1.json). Each .json file contains the source code of the sample. All of the .json files are located under /assets/samples of igniteui-angular-samples project.

Note: Samples without a respective .json file are still rendered in the code view, but the code tabs and the footer will be omitted.

Add/Change environment variables

Our samples are embedded in the topics with iframes. Some topics have more than one sample and in order to prevent loading delays, we've added lazy loading functionality of the iframes. In order to achieve this we use lazysizes library.

Follow the steps below for lazy loading implementation in a topic (PR example):

Generally the first sample should not be lazily loaded. Add loading class to the sample container and: onload="onSampleIframeContentLoaded(this); on the iframe.
For all of the sample you'd like to load lazily, add

loading class to the sample container
lazyload class to the iframe
rename the src of the iframe to data-src
you shouldn't have onload="onSampleIframeContentLoaded(this);"

Creating shared help topics

Here you can find the document which describes how to create a shared topic (template) which is used to produce separate topics for a particular features. For example shared templates for IgxGrid, IgxTreeGrid and/or IgxHierarchicalGrid components.

Updating of Data Visualization related topics

Our cross platform docs are in internal repo.

If you need to update the cross platform docs, please do so from the igniteui-xplat-doc repo, queue an Angular build from AngularDocFX_EN build definition in the igniteui-xplat-doc repository, and then approve the PR that will come into public repo from ESShared.

Adding of images in the topic

When there is a need to add image (png, jpeg and etc.) to a topic use the following guidance:

add b-lazy and responsive-img classes - these are responsible for the lazy loading and part of the image responsiveness
always add the image as part of the images folder.
define data-srcset with 480w, 768w and 1100w
set alt and title attributes

Example:

<img class="b-lazy responsive-img"
    src="../../images/general/landing-grid-page.png" 
    data-src="../../images/general/landing-grid-page.png" 
    data-srcset="../../images/general/landing-grid-page.png 480w, ../../images/general/landing-grid-page.png 768w, ../../images/general/landing-grid-page.png 1100w" 
    alt="Angular Data Grid"
    title="Angular Data Grid">
</div>

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls