Embedding and including

Embedding

An Almoststatic page is composed by a list of widgets disposed in vertical order, the next under the previous.

Often this is not enough. Sometime there is the need to embed a widget within another one. I.e. in a tabbed or accordion content, you can need to include an image row or some other widget. You can also have contents arranged in columns, so you need to embed contents on each column.

Almoststatic uses a recursive algorithm that lets easy to do it, for example, you can embed an accordion within a tabbed:

- type: tabbed
  id: my_tab
  tabs:
    - label: tab1
      text: |
        ## tab 1
        Simple text

    - label: tab2
      text:
        content:
          - type: accordion
            id: fisa1
            cards:
              - button: "Card 1"
                text: |
                  Text1
              - button: "Card 2"
                text:
                  content:
                    - type: image_row
                      image: landscape1.jpg
                      text: |
                        my lorem content
              - button: "Card 3"
                text: |
                  Text3

But there is more. As you can see, in this case we have an accordion within a tabbed, and an image_row within the accordion.

Embedding can be nested at each level, and the nesting limit is only the quality of the result you wang get.

Simply put a content field list into the text field.

Almoststatic has another two powerful ways to embed contents into the text. Using commands embed and particle you can insert widgets wherever you want.

content:
  - type: text_html
    text: "{{embed(page.txt1)}}"

  - type: text_html
    text: "{{particle('txt2')}}"

txt1:
  - type: text_html
    text: My embedded content

particles:
  - type: text_html
    id: txt2
    text: My particle

The choice is matter of taste, particle is clean and tidy, instead embed can be very powerful.

Including

All you can do with embedding, you can do even with including.

Nested embedding on long pages can be difficult to maintain and kept organized, we can have some long text which is convenient to keep separated or we can have some contents that we wish to get in several pages.

For all this reasons we can split pages into page and inclusion files:

- type: tabbed
  id: my_tab
  tabs:
    - label: tab1
      text:
        include: include/page1/mytext.md

    - label: tab2
      text:
        include: include/page1/accordion.yaml

    - label: tab3
      text:
        include: include/page1/mytext.html

- type: include
  file: include/page1/rest_of_page.yaml

In this case we split page into page and inclusions. This time we put the keyword include within the text keyword. But there is more, we can use a special widget called include outside other widgets.

Inclusion files can be stored everywhere within the content folder except the pages folder which is reserved for url pages.

Almoststatic recognize 3 kind of inclusion file extensions. *.html for plain html files, *.md for markdown files and *.yaml for files with list of widgets.

As usual, included files can have nested inclusions and embeddings. Again, the only limit is the quality of result.