Htx Guide

Pages and components

Lets begin by discussing what pages and components are.

Differences and simularities

Pages are the root "component" and are responsible for the names of the output php files. By default pages are defined in src/pages, but that can be changed in the htx_config.json file.

Components are very simular and the only differences are that components can receive information (the child elements and attribute/properties) from the parent components. Page on the other hand are as I said the root component and cannot receive any information. Components usually start with an uppercase letter. Most components don't have just uppercase letters, but also lowercase. The builtin components do use all uppercase

File extension

Every component file (therefor also pages) ends in .htx unless otherwise configured in htx_config.json

Children

For those that don't know, children are what is contained inside an element. Not every component/html tag has children. In a component you can use the <INNER /> component/tag (which MUST end with /> and is builtin) to place the children there. If you want to you can also use it multiple times, but usually you don't.

Attributes

Components also have attributes/properties. You can access the in the $props variable. For example if you want to access a 'my-attribute' property you can read $props["my-attribute"].

WARNING

If an attribute/property is not defined it will not be assigned, so please validate your properties at the start of you file and give an error/exception if anything is missing

Children and Attributes example

Here is a quick example of a layout component

<?php
if(!isset($props["title"])) throw new Exception("The layout requires a title attribute/property");
?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><?= $props["title"] ?></title>
</head>
<body>
    <INNER />
</body>
</html>

Complex attributes

If you want to pass an attribute to a component (for regular tags you just use the php way) that also requires some computation you can use "nested" php code. Htx assumes all attributes/properties are valid php and therefor you can use (). Let me demonstrate

<MyComponent $z=$x /> <!-- this works -->
<MyComponent $z=$x+$y /> <!-- this works -->
<MyComponent $z=($x + $y) /> <!-- this works -->
<MyComponent $z=$x + $y /> <!-- this fails, because the "+" is detected to be an attribute name -->

Nesting can not only be done by (), but also [] and {}

Importing components

Htx does not have any auto import feature for components. Instead you have to manually import them using one of the following

<!-- import "./path/to/file/without/Extension"-->
<!-- import ComponentName from "./path/to/file/without/Extension" -->

You can use the top one to use the filename as the component name. If you want to change the name you can use the bottom one.

If you have a layout file in src/layouts/MyLayout.htx, some user component in src/other/user/Profile.htx and you have a page in src/pages/SomePage.htx You can import/use the layout in the page like this

<!-- import "../layouts/MyLayout" -->
<!-- import UserProfile from "../other/user/Profile" -->
<?php
$user = [
    "name" => "some user",
    "email" => "example@domain.com"
];
?>
<MyLayout title="Some page">
    Some page contents
    <UserProfile user=$user />
</MyLayout>

Global or Local

By default every component defines local variables and functions that cannot be accessed from other components (unless you try to). Local variables are converted to a name like htx_<component>_<uid>_<variable>. If you want to access global variables (page wide) you can use the $GLOBAL_ prefix, so $GLOBAL_x gets converted to $x. Functions are simular, but if they are not defined within a component htx assumes they are global whereas with variables they are usually assumed to be local