Components
==========

What's a Component?
-------------------

A Pharaoh project consists of any amount of components.

The file ``report_project/index.rst`` determines how the components are included in the report.
Per default all components are added in sequence on the same level but this could be changed in the template.

A component has following traits:

    Name
        The name of the component; used for identification purposes.

    :ref:`reference/components:Templates`
        A list of templates used to generate the component's files.

    Render Context
        An arbitrarily-nested dictionary that is available during generation-time templating.
        This context enables the reuse of the templates for different purposes.

    :ref:`reference/components:Resources`
        A list of resource definitions that let asset scripts easily access external data by using an alias instead of
        absolute resource specifiers (like a file path).

    Metadata
        This metadata dictionary can be used to :ref:`lookup components <reference/components:Finding Components>`
        by their metadata.

        A potential use case is grouping components by their metadata and create a customized report layout
        using the ``report_project/index.rst`` template.

Resources
---------

Resources let asset scripts easily access external data by using an alias instead of absolute resource specifiers
(like a file path or an RDDL artifact id).

The currently available resource types:

.. jinja:: default

    {% for name, resource_id in resources.items() %}
        - :class:`{{ name }} <{{ resource_id }}>`

    {% endfor %}



Accessing resources in asset scripts can be done like this::

    from pathlib import Path
    from pharaoh.assetlib.api import get_resource, FileResource

    resource: FileResource = get_resource(alias="<resource_alias>")
    first_matching_file_path: Path = resource.locate()
    ...


To get a resource from a component or update a component's resource, use these functions:

    - :func:`PharaohProject.get_resource() <pharaoh.project.PharaohProject.get_resource>`
    - :func:`PharaohProject.update_resource() <pharaoh.project.PharaohProject.update_resource>`


Templates
---------

Component templates are used to create the main content for components
(see :ref:`reference/components:Adding Components`) and can come in different forms:

- **Template Directory**

    The simplest form of a template. A directory with some files.

    If |assets| shall be generated by the component,
    the directory must contain an ``asset_scripts`` subdirectory containing Python scripts.

- **Registered Templates**

    Pharaoh's :ref:`plugins/plugin:Plugin Architecture` allows the development of plugins that register templates.

    That means plugins may come with their own template directories and register their paths in Pharaoh,
    so these templates are then selectable using a template identifier,
    like ``my_awesome_plugin.template1``.

    An advantage of plugin templates is, that for those templates, dependencies to other templates can be specified.
    For example the template ``my_awesome_plugin.template1`` may requires that the ``my_awesome_plugin.template2``
    template is used at least once in any component, otherwise cross-references won't work.

- :ref:`Template Files/Single-file templates <reference/templating:Single-file Templates>`

    The smallest and most compact form of a template.

    Single-file templates are Python files with suffix ``.pharaoh.py`` whose Python code creates |assets| and
    whose module-level docstring represents the rST content.

    This file will be internally converted to a template directory::

        my_template.pharaoh.py -> index_my_template.rst
                                  asset_scripts/my_template.py


Managing Components
-------------------

Adding Components
+++++++++++++++++

Adding a component to a Pharaoh project can be done via the API function
:func:`PharaohProject.add_component() <pharaoh.project.PharaohProject.add_component>` or the CLI
command :ref:`reference/cli:Add`:

.. automethod:: pharaoh.project.PharaohProject.add_component
    :noindex:


Updating Components
+++++++++++++++++++

Once a component is generated, the options to modify it are limited to:

    -   :func:`PharaohProject.add_template_to_component() <pharaoh.project.PharaohProject.add_template_to_component>`
    -   :func:`PharaohProject.update_resource() <pharaoh.project.PharaohProject.update_resource>`

Removing Components
+++++++++++++++++++

A generated component can be removed via
:func:`PharaohProject.remove_component() <pharaoh.project.PharaohProject.remove_component>`,
which results in deletion of ``report-project/components/<component-name>`` and its entry in ``pharaoh.yaml``:


Finding Components
++++++++++++++++++

Components can be looked up via their metadata using the function
:func:`PharaohProject.get_component_names_by_metadata()
<pharaoh.project.PharaohProject.get_component_names_by_metadata>`.


Built-In Templates
------------------

Pharaoh comes with some builtin templates:

``"pharaoh.default_project"``
    The default project template that is used when creating a new project.
    It contains a basic Sphinx project with a

    *   Pharaoh logo
    *   ReadTheDocs theme with customized layout and footer templates (includes some JS/CSS to display
        dynamic tables)
    *   Pharaoh CLI CMD wrappers for quick access to the most important commands


``"pharaoh.empty"``
    The default template for :meth:`PharaohProject.add_component() <pharaoh.project.PharaohProject.add_component>`
    if no template is specified.


``"pharaoh.report_info"``
    The template for a component that shows a list of all errors that occurred during asset generation
    in other components, grouped by the component name.

    Example:

    .. image:: /_static/report_info_component_example.png