Functional Blocks
Functional Blocks in StaticPHP allow you to create dynamic content without writing PHP. They are similar to using PHP functions but with a simplified syntax.
Syntax
A Functional Block starts with an opening tag using the same delimiter as MetaData, followed by the block name, and then a set of key-value parameters within parentheses. The block is closed with an end tag, which is the word "end" followed by the block name, surrounded by the MetaData delimiter.
Here's an example:
--- func(key = "value", another-key = "another-value") ---
Put anything here.
--- endfunc ---
The Loop Functional Block
The loop block allows you to iterate through a list of items and display information for each item as you define.
Directory Contents
Use the dir parameter to loop through each file in a directory. You can specify an absolute path or a relative path (without a leading slash). Relative paths are relative to the location of the StaticPHP file, not the file containing the loop block.
You can access MetaData within each file using placeholders prefixed with "loop" instead of "metadata."
Example:
--- loop(dir = "src/items") ---
Item Name: --- loop.item-name ---
--- endloop ---
For more information on setting MetaData in files and using placeholders, refer to the MetaData page.
A special placeholder --- loop.uri --- is available when using the dir parameter, displaying the path to the current directory item for use in links.
Sorting Order
By default, items are sorted as the filesystem sorts them, typically in ascending order. You can change this by setting the sort parameter to either ascending or descending.
Example of sorting with dir:
--- loop(dir = "src/items", sort = "descending") ---
Item Name: --- loop.item-name ---
--- endloop ---
Outputting JSON
You can make the loop results available as a JSON file by setting the json parameter to the desired file path. Similar to dir, this path can be relative to StaticPHP or absolute.
Example of JSON output:
--- loop(dir = "src/items", json = "src/api/items.json") ---
Item Name: --- loop.item-name ---
--- endloop ---
Ignoring Items
You can specify additional items for the loop to ignore using the ignores parameter. This parameter takes a semicolon-separated list of items to ignore, optionally with spaces for readability.
Example of ignoring items:
--- loop(dir = "src/items", ignores = "ignore-this; ignore-that") ---
Item Name: --- loop.item-name ---
--- endloop ---
Filtering Items
By default, any web page found in the specified directory will be listed, but you may want to filter this and only show certain ones. You can filter the items displayed in the rendered list using MetaData keys and values, and the filter-key and filter-value parameters.
Example of filtering items based on key alone.
--- loop( dir = "src/items", filter-key = "item-name" ) ---
Item Name: --- loop.item-name ---
--- endloop ---
In the above example, only items containing the MetaData key item-name fill be displayed.
Example of filtering items based on key and value.
--- loop( dir = "src/items", filter-key = "category", filter-value = "random" ) ---
Item Name: --- loop.item-name ---
--- endloop ---
In the above example, only items containing the MetaData key category with a value of random fill be displayed. This is useful for blog post listings for a specific category.
The If Functional Block
The if functional block allows you to perform conditional checks on MetaData.
Example of Use
Assume you have the following MetaData at the top of your home page file, indicating that this page is the home page.
---
current-page: home
---
You can perform a check that the current page is the home page using the following if functional block.
--- if( current-page == "home" ) ---
<p>This is the home page.</p>
--- endif ---
When the condition is true, it will output the content inside.
<p>This is the home page.</p>
Checking the Key Only
The IF functional block can be used to only check if the key exists. Assume you want to output the page title, and have the following MetaData...
---
page-title: Welcome
---
You want to check if there is a title before displaying it, so you have the following if functional block...
--- if( page-title ) ---
<h1>--- metadata.page-title ---</h1>
--- endif ---
When the condition is true, it will output the content inside.
<h1>Welcome</h1>
Negation Checking
Check if a MetaData key is NOT set, or if the value of that key is NOT a specific value.
For example, check if the page does NOT have a title.
--- if( !page-title ) ---
<p>There is no page title.</p>
--- endif ---
Another examaple, check if the current page is NOT home.
--- if( current-page != "home" ) ---
<p>This is not the home page.</p>
--- endif ---
The if functional block is currently limited to this basic functionality. The functionality may get extended in the future.
More Features Coming Soon
Stay tuned for updates and additional features in the documentation.