creating-a-tree.ftd

-- import: ftd.dev/assets
-- import: fpm

-- ft.page-with-toc: How to create a tree using `ftd`?
toc: $config.examples-toc
id: main


-- ft.markdown: 

A tree view represents a hierarchical form of items where each item can have 
subitems and so on. In this tutorial, we will learn how to create a tree using 
`ftd` step by step.


-- ft.h1: Create a component for tree

Let us create a component that would contain all the items and subitems.
The component needs to be of [`column`](/ftd/column/) type which would stack the 
items vertically.


-- ft.code:
lang: ftd

\-- ftd.column:


-- ft.image:
src: $assets.files.images.tree.first.jpeg
width: fill


-- ft.markdown:

The above code uses `ftd.column` which is a [kernel component](/ftd/kernel/).
Now let's insert an item.


-- ft.code:
lang: ftd

\-- ftd.column:

\-- item:
name: Beverage


-- ft.image:
src: $assets.files.images.tree.second.jpeg
width: fill


-- ft.markdown:

Bravo! we have successfully inserted an item with the property `name: Beverage`. 
You must have noticed that we have called another component with the name `item` to display this item.
This component becomes subsection/child of the `ftd.column` component.
Before we insert another item, let's understand how to create the `item` component first.


-- ft.h1: Create an `item` component


-- ft.code:
lang: ftd

\-- component item:
component: ftd.column
string $name:
padding-left: 10
open: true


-- ft.image:
src: $assets.files.images.tree.third.jpeg
width: fill


-- ft.markdown:

Let's understand the above code in detail. As we need to insert subitem inside 
`Beverage` item and it's proper to show subitems vertically. So we have created 
[component](/ftd/component/) with type column.

The other important thing to notice here is we have defined `open: true` which 
would make the component open. (i.e. any element that comes after its call would
become its child. To understand this better, please check this out 
[container-management](/ftd/container-management/)).

We have also defined an argument `$name` of type `string`. So, at the time of 
calling this component, we have to pass an argument `name` of type `string`. Now, 
We have to consume this argument to show it in frontend.


-- ft.code:
lang: ftd

\-- component item:
component: ftd.column
string $name:
padding-left: 10
open: true

\--- ftd.text: $name


-- ft.image:
src: $assets.files.images.tree.fourth.jpeg
width: fill


-- ft.markdown:

Here, we have inserted [`--- ftd.text: ref $name`](/ftd/text/) as the 
child/subsection of `item` component. This has reference to the argument `$name`. 
Hence consuming it 😊. Before we proceed further let's call this component and 
see the result.


-- ft.code:
lang: ftd

\-- item: 
name: Beverage


-- ft.image:
src: $assets.files.images.tree.fifth.jpeg
width: fill


-- ft.markdown:

Output:


-- ftd.column item1:
string name:
padding-left: 10
open: true

--- ftd.text: $name
color if $ftd.dark-mode: $fpm.color.main.text

-- ftd.column:
spacing: 20
border-width: 1
border-radius: 5
border-color if $ftd.dark-mode: $fpm.color.main.text
padding: 10
width: fill

--- item1:
name: Beverage


-- ft.h1: Add items to the tree

Let's get back to adding items. 
In this example, we are going to add Water and Juice as children of Bevarage 
and Mango Juice as child of Juice.


-- ft.code:
lang: ftd

\-- ftd.column:

\-- item:
name: Beverage
id: beverage-id

\-- item:
name: Water

\-- container: beverage-id

\-- item:
name: Juice

\-- item:
name: Mango Juice


-- ft.markdown:

We are almost done now. Let's understand this in detail. First, we have inserted
our old pal `Beverage` and now item `Beverage` becomes open. (Wait, it's different than the first time when we have inserted.
It has a property `id: beverage-id` but why?? Have patience for answer). 

Cool, after that we have inserted item `Water` and it becomes child of item `Beverage`
and now item `Water` becomes open. We need to change the open container/component to item `Bevarage` again.
In order to achieve this, we have added `--- container: beverage-id` 
which changes the open container to the one with id `beverage-id` which is item `Beverage`.
(Now, you know why item `Beverage` has `id`). After this, we have inserted item `Juice`,
and now this becomes an open container. At last, we have inserted item `Mango Juice`.


-- ft.image:
src: $assets.files.images.tree.sixth.jpeg
width: fill


-- ft.image:
src: $assets.files.images.tree.seventh.jpeg
width: fill


-- ft.image:
src: $assets.files.images.tree.eighth.jpeg
width: fill


-- ft.image:
src: $assets.files.images.tree.ninth.jpeg
width: fill


-- ft.image:
src: $assets.files.images.tree.tenth.jpeg
width: fill


-- ft.h1: Presenting Tree

Let's combine everything now and see the magic 🪄. 


(Note: I have changed component `item` a little 
and added a `row` having two elements of type `text`. One with ✌️ emoji and the other with reference to the `$name` argument.)


-- ft.code:
lang: ftd

\-- component item:
component: ftd.column
string $name:
padding-left: 10
open: true

\--- ftd.row:

\--- ftd.text: ✌️

\--- ftd.text: $name


\-- ftd.column:

\-- item:
name: Beverage
id: beverage-id

\-- item:
name: Water

\-- container: beverage-id

\-- item:
name: Juice

\-- item:
name: Mango Juice


-- ft.markdown:

Output


-- ftd.column:
spacing: 20
border-width: 1
border-radius: 5
border-color if $ftd.dark-mode: $fpm.color.main.text
padding: 10
width: fill


-- ftd.column display-item:
string name:
padding-left: 10
open: true
color if $ftd.dark-mode: $fpm.color.main.text

--- ftd.row:

--- ftd.text: ✌️

--- ftd.text: $name
color if $ftd.dark-mode: $fpm.color.main.text

-- ftd.column:


-- display-item:
name: Beverage
id: beverage


-- display-item:
name: Water


-- container: beverage


-- display-item:
name: Juice


-- display-item:
name: Mango Juice


-- container: main


-- ft.h1: Adding Events

We have learnt how to create a tree. Now, we'll learn how to make it more interactive.
As you have guessed, we need to do changes in `-- component item:`.
Let us take a quick look at updated version, then we'll discuss about it line by line.


-- ft.code:
lang: ftd

\-- component item:
component: ftd.column
string $name:
padding-left: 10
open: true
append-at: some-child
$visible: true

\--- ftd.row:
$on-click$: toggle $visible

\--- ftd.text: ✌️

\--- ftd.text: $name

\--- container: ftd.main

\--- ftd.column:
if: $visible
id: some-child


-- ft.markdown:

Thankfully, not many changes. phew 😮‍💨!! Let's take a closer look at changes in component `item`.


-- ft.code:
lang: ftd

\-- component item:
component: ftd.column
string $name:
padding-left: 10
open: true
append-at: some-child
$visible: true


-- ft.markdown:

Here, we have changed the `open` property value from `true` to `some-child`.
This would make the component `item` open as earlier, but now elements that come after its call 
would be inserted inside the child/subsection of component `item` which has `id` as `some-child`.
(If you still have not check out this [container-management](/ftd/container-management/) page.
It's highly recommended to do it now)

And what is that child/subsection which has `id: some-child`? (Remember?? no?? 
Check out the above code again.)
It is a kernel component `ftd.column`.

We have declared a local variable `@visible` of boolean type with default value as `true`.
(Why?? All I can say, have patience again.)

Now, let us focus on changes in subsections. We have added the below two subsections.


-- ft.code:
lang: ftd

\--- container: ftd.main

\--- ftd.column:
if: $visible
id: some-child


-- ft.markdown:

As `--- ftd.row:` was an open container, we need to change the container to component `item` 
having type `column`. This line `--- container: ftd.main` helps in achieving it.
The open container becomes `-- component item:`.

After this, we have defined another kernel component `--- ftd.column:`.
It has a property `if: @visible` which make this component (and its children) visible,
only if the condition satisfies, i.e., if local variable `@visible` is true.

We need something which changes the value of the local variable `@visible` to control its
visibility. As this component `--- ftd.column:` is the open container for `item` (How?? Remember it has `id: some-child`)
and all subsequent components will be placed inside it, so we can control the visibility
of all those components.

FTD has an action `toggle` which toggles a boolean variable. 
We can attach it with an event `click`. Check these changes in subsection `--- ftd.row:` of `item`


-- ft.code:
lang: ftd

\--- ftd.row:
$on-click$: toggle $visible


-- ft.h1: Presenting an interactive Tree

Let's combine everything now and see more magic 🪄. 
Click on `✌️Beverage` to see everything else disappears, then click it again, and everything is back.
Similarly, click on `✌️Juice` and see `✌️Mango Juice` disappear. You know how to make it appear again.


-- ft.code:
lang: ftd

\-- component item:
component: ftd.column
string $name:
padding-left: 10
open: true
append-at: some-child
$visible: true

\--- ftd.row:
$on-click$: toggle $visible

\--- ftd.text: ✌️

\--- ftd.text: $name

\--- container: ftd.main

\--- ftd.column:
if: $visible
id: some-child


\-- item:
name: Beverage
id: beverage-id


\-- item:
name: Water


\-- container: beverage-id


\-- item:
name: Juice


\-- item:
name: Mango Juice


-- ft.markdown:

Output


-- ftd.column:
spacing: 20
border-width: 1
border-radius: 5
border-color if $ftd.dark-mode: $fpm.color.main.text
padding: 10
width: fill


-- ftd.column display-item1:
string name:
color if $ftd.dark-mode: $fpm.color.main.text
padding-left: 10
open: true
append-at: some-child
boolean visible: true

--- ftd.row:
$on-click$: toggle $visible

--- ftd.text: ✌️

--- ftd.text: $name
color if $ftd.dark-mode: $fpm.color.main.text

--- container: ftd.main

--- ftd.column:
if: $visible
id: some-child


-- display-item1:
name: Beverage
id: beverage


-- display-item1:
name: Water


-- container: beverage


-- display-item1:
name: Juice


-- display-item1:
name: Mango Juice