.. _omnigraph_node_categories:

OmniGraph Node Categories
=========================

An OmniGraph node can have one or more categories associated with it, giving the UI a method of presenting large lists
of nodes or node types in a more organized manner.

Category Specification In .ogn File
-----------------------------------
For now the node categories are all specified through the .ogn file, so the node will inherit all of the categories
that were associated with its node type. There are three ways you can specify a node type category in a .ogn file;
using a predefined category, creating a new category definition inline, or referencing an external file that has
shared category definitions.

Predefined Categories
+++++++++++++++++++++
This is the simplest, and recommended, method of specifying categories. There is a single .ogn keyword to add to the
file to associate categories with the node type. It can take three different forms. The first is a simple string with
a single category in it:

.. code-block:: json

    {
        "MyNodeWithOneCategory": {
            "version": 1,
            "categories": "function",
            "description": "Empty node with one category"
        }
    }

.. warning::

    The list of categories is intentionally fixed. Using a category name that is not known to the system will
    result in a parsing failure and the node will not be generated. See below for methods of expanding the list of
    available categories.

The second is a comma-separated list within that string, which specifies more than one category.

.. code-block:: json

    {
        "MyNodeWithTwoCategories": {
            "version": 1,
            "categories": "function,time",
            "description": "Empty node with two categories"
        }
    }

The last also specifies more than one category; this time in a list format:

.. code-block:: json

    {
        "MyNodeWithAListOfTwoCategories": {
            "version": 1,
            "categories": ["function", "time"],
            "description": "Empty node with a list of two categories"
        }
    }

The predefined list is contained within a configuration file. :ref:`Later<omnigraph_categories_shared_file>` you will
see how to add your own category definitions. The predefined configuration file looks like this:

.. literalinclude:: ../../../../source/extensions/omni.graph.tools/ogn_config/CategoryConfiguration.json
    :language: json

.. note::

    You might have noticed some categories contain a colon as a separator. This is a convention that allows splitting
    of a single category into subcategories. Some UI may choose to use this information to provide more fine-grained
    filtering an organizing features.

Inline Category Definition
++++++++++++++++++++++++++
On occasion you may find that your node does not fit into any of the predefined categories, or you may wish to add
extra categories that are specific to your project. One way to do this is to define a new category directly within
the .ogn file.

The way you define a new category is to use a *name:description* category dictionary rather than a simple string.
For example, you could replace a single string directly:

.. code-block:: json

    {
        "MyNodeWithOneCustomCategory": {
            "version": 1,
            "categories": {"light": "Nodes implementing lights for rendering"},
            "description": "Empty node with one custom category"
        }
    }

You can add more than one category by adding more dictionary entries:

.. code-block:: json

    {
        "MyNodeWithTwoCustomCategories": {
            "version": 1,
            "categories": {
                "light": "Nodes implementing lights for rendering",
                "night": "Nodes implementing all aspects of nighttime"
            },
            "description": "Empty node with two custom categories"
        }
    }

You can also mix custom categories with predefined categories using the list form:

.. code-block:: json

    {
        "MyNodeWithMixedCategories": {
            "version": 1,
            "categories": ["rendering",
                {
                    "light": "Nodes implementing lights for rendering",
                    "night": "Nodes implementing all aspects of nighttime"
                }
            ],
            "description": "Empty node with mixed categories"
        }
    }

.. _omnigraph_categories_shared_file:

Shared Category Definition File
+++++++++++++++++++++++++++++++
While adding a category definition directly within a file is convenient, it is not all that useful as you either only
have one node type per category, or you have to duplicate the category definitions in every .ogn file. A better approach
is to put all of your extension's, or project's, categories into a single configuration file and add it to the build.

The configuration file is a .json file containing a single dictionary entry with the keyword *categoryDefinitions*.
The entries are *name:description* pairs, where *name* is the name of the category that can be used in the .ogn file
and *description* is a short description of the function of node types within that category.

Here is the file that would implement the above two custom categories:

.. code-block:: json

    {
        "categoryDefinitions": {
            "$description": "These categories are applied to nodes in MyProject",
            "light": "Nodes implementing lights for rendering",
            "night": "Nodes implementing all aspects of nighttime"
        }
    }

.. tip::

    As with regular .ogn file any keyword beginning with a "*$*" will be ignored and can be used for documentation.

If your extension is building within Kit then you can install your configuration into the build by adding this
line to your *premake5.lua* file:

.. code-block:: lua

    install_ogn_configuration_file("MyProjectCategories.json")

This allows you to reference the new category list directly from your .ogn file, expanding the list of available
categories using the .ogn keyword *categoryDefinitions*:

.. code-block:: json

    {
        "MyNodeWithOneCustomCategory": {
            "version": 1,
            "categoryDefinitions": "MyProjectCategories.json",
            "categories": "light",
            "description": "Empty node with one custom category"
        }
    }

Here, the predefined category list has been expanded to include those defined in your custom category configuration
file, allowing use of the new category name without an explicit definition.

If your extension is independent, either using the Kit SDK to build or not having a build component at all, you can
instead reference either the absolute path of your configuration file, or the path relative to the directory in which
your .ogn resides. As with categories, the definition references can be a single value or a list of values:

.. code-block:: json

    {
        "MyNodeWithOneCustomCategory": {
            "version": 1,
            "categoryDefinitions": ["myConfigDirectory/MyProjectCategories.json", "C:/Shared/Categories.json"],
            "categories": "light",
            "description": "Empty node with one custom category"
        }
    }

Category Access From Python
---------------------------

Category Access From C++
------------------------
