Introduction ConceptsEditorFolder structureProject fileGeneration overviewMain filesFragmentsUsing stylesClonesMeta instructionsAuto linksAdvancedTroubleshootingTagsAbout usLicenseFeedback Version History

Fragments

Simply put, fragments files are files containing some contiguous part of HTML. "Pouches" (i.e. meta-instructions) placed in other files would refer to such fragment files. FillPouch will take the contents of those referred fragments, and use them at the respective locations of those pouches.

When we work with HTML, it is habitual for us to place tags of paired-up elements logically in one place itself. For example; if we use the div element, we would use the starting tag: <div>in one place. Then we expect; quite naturally, that somewhere; a few lines down, we would be using </div>. It also seems correct and logical to keep that entire content in one file itself.

This situation can happen in FillPouch too -- where we keep paired elements in the same file itself. But it is also quite fine to put the starting tag in one fragment, but the ending tag in another fragment. That situation happens when we want to refactor the content between the element's start tag and its end tag.

Now the above example is quite trivial as we gave only the example of one HTML element. Such "pairing" in real sites, does not happen at the level of individual HTML elements. There is usually a set of HTML starting tags that achieve a particular look, then some content, followed by the respective ending tags of the ones we started.

Confused? Let me give an example: Here is an example from the excellent Bulma CSS documentation. This how a set of breadcrumbs are dressed up using Bulma: 
    <nav class="breadcrumb" aria-label="breadcrumbs">
        <ul>
          <li><a href="#">Bulma</a></li>
          <li><a href="#">Documentation</a></li>
          <li><a href="#">Components</a></li>
          <li class="is-active"><a href="#" aria-current="page">Breadcrumb</a></li>
        </ul>
      </nav>

Note that the actual contents of those breadcrumbs (Namely: Bulma, Documentation,Components,Breadcrumb) are "enclosed" between a "block" of starting tags of some elements, and a block of the ending tags of those elements.

If we want to implement the above example in Fillpouch, we'll place the top part of the HTML elements that contributes to the "dressing up" (i.e. stylizing) of the contents in one fragment; and the corresponding ending tags would be in another fragment file, as shown next:

Fragment for the "top" 
    <nav class="breadcrumb" aria-label="breadcrumbs">
        <ul>

Fragment for the "bottom" 
    </ul>
    </nav>

Fragment for the actual contents 
    <li><a href="#">Bulma</a></li>
    <li><a href="#">Documentation</a></li>
    <li><a href="#">Components</a></li>
    <li class="is-active"><a href="#" aria-current="page">Breadcrumb</a></li>

Budweiser?* But why sir?
The advantage of splitting up that breadcrumb into 3 parts is that the 1st fragment and 2nd fragment encloses the actual content in the 3rd fragment. Thereby, we have successfully separated the actual content (the 3rd fragment) and kept it separate from the HTML that went to dress up those contents. Once this is done, we can concentrate on changing/improving the contents without bothering about the HTML elements that played a part in only dressing up the contents.

How will these fragments be put together?
Good question! Some other file will take charge of the assembly of these fragments. In that file, we'll put "pouch" meta-instructions to instruct Fillpouch to put the matter present in these fragments at the correct locations of the said file. We'll learn how to do this subsequently in this documentation.

How are these fragments named? Where are they saved?
These fragments are kept outside the root folder in the project folder. (Note the build folder is never touched by hand. That folder is FillPouch's territory) The reason why these fragments are kept outside the root is because they should not pollute the main files present inside the site being developed.

The fragment files would usually have ".html" as their extension; provided that they do not contain any "pouch" Meta-instructions themselves. IF they do have meta-instructions, then they should be named with the ".sd" extension.
*Mallus will get this joke. Though we like beer, we do not sponsor any brand.

Top