.. _nodes-system-intro:

===================================
Node-types, nodes-sources and nodes
===================================

This part is the most important part of Roadiz. Quite everything in your website will be a node.

Let's check this simple node schema before explain it.

.. image:: ./img/node-struct.*

Now, it's time to explain how it's working!

.. _node-types:

What is a Node-type
-------------------

A node-type is the blueprint for your node-source.
It will contain all fields that Roadiz will use to generate an extended node-source class.

.. image:: ./img/NSPage-php.*
   :align: center


For example, a node-type "Page" will contain "content" and "header image" fields.
The "title" field is always available as it is hard-coded in ``NodesSources`` class.
After saving your node-type, Roadiz generates a ``NSPage`` class which extends the ``NodesSources`` class.
You will find it in the ``src/GeneratedEntity/`` folder.
Then Roadiz calls *Doctrine* update tool to migrate your database schema.
**Do not modify the generated class.** You’ll have to update it by the backend interface.

Here is a schema to understand how node-types can define custom fields into node-sources:

.. image:: ./img/NSPage-schema.*
   :align: center


All node-types management will be done by editing ``app/config/node_types/*.yaml`` files. You will be able to
create, update node-types objects and each of their node-type fields independently.
Some CLI commands are available to export, list and validate types and fields.
We really encourage you to check the commands with ``--help`` argument, as following:

.. code-block:: console

    nodetypes:default-values  Get all default values for a field across all node-types.
    nodetypes:export-files    Migrate database node-types to YAML files.
    nodetypes:list            List available node-types or fields for a given node-type name
    nodetypes:validate-files  Import all node-type YAML files and validate them.


Keep in mind that each new node-type or adding/removing node-type fields operation will require a database migration.
Doctrine has to create specific columns per node-type and fields. Do not forget to execute ``bin/console app:migrate`` command to
generate a new Doctrine migration based on your changes.
It’s very important to understand that *Doctrine* needs to see your node-types generated classes **before**
upgrading database schema. If they don’t exist, it won’t able to create your custom types tables, or worst, it could
delete existing data since *Doctrine* won’t recognize specific tables. You can execute ``bin/console generate:nsentities``
to regenerate your node-types PHP classes.


Now let's have a look on node-sources.


.. _node-sources-intro:

Node-sources and translations
-----------------------------

Once your node-type created, its definition is stored in database in ``node_types`` and ``node_type_fields`` tables.
This informations will be only used to build your node-sources edition forms in backoffice and to build a custom database table.

Inheritance mapping
^^^^^^^^^^^^^^^^^^^

With Roadiz, each node-types data (called node-sources) is stored in a different table prefixed with ``ns_``. When you create a *Page*
node-type with 2 fields (*content* and *excerpt*), Roadiz tells Doctrine to build a ``ns_page`` table with 2 columns and one primary key column inherited from ``nodes_sources`` table. It’s called *inheritance mapping*: your ``ns_page`` table extends ``nodes_sources`` table and when you are querying a *Page* from database, Doctrine mix the data coming from these 2 tables to create a complete node-source.

At the end your node-source *Page* won’t contain only 2 fields but many more as ``NodesSources`` entity offers ``title``, ``metaTitle``,
``metaDescription``, ``metaKeywords`` and others useful data-fields which can be used among all node-types.

Translations
^^^^^^^^^^^^

Node-sources inheritance mapping is not only used to customize data but to make data translations available. As you saw in the first picture, each nodes can handle many node-sources, one per translation.