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.
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 block allows you to iterate through a list of items and display information for each item as you define.
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.
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.
dir:--- loop(dir = "src/items", sort = "descending") ---
Item Name: --- loop.item-name ---
--- endloop ---
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 ---
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 ---
The if functional block allows you to perform conditional checks on MetaData.
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>
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>
The if functional block is currently limited to this basic functionality. The functionality may get extended in the future.
This is just the beginning for Functional Blocks in StaticPHP. Stay tuned for updates and additional features in the documentation.