Skip to content

refactor: Change UI to Ui #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
usernane merged 8 commits into from
Oct 7, 2025
Merged

refactor: Change UI to Ui #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
4623506
refactor: Renamed Folders
usernane Oct 7, 2025
82b2fa2
refactor: Moved from `UI` to `Ui`
usernane Oct 7, 2025
bce4097
refactor: Moved to Folder `Ui`
usernane Oct 7, 2025
ca23307
refactor: Namespace Correction
usernane Oct 7, 2025
f9bd4c9
Update README.md
usernane Oct 7, 2025
01e99cd
Merge branch 'main' into dev
usernane Oct 7, 2025
01ef31b
ci: Fix Missing Input
usernane Oct 7, 2025
0863716
test: Fix PHPUnit Config
usernane Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions .github/workflows/php83.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,6 @@ jobs:
name: Code Quality
needs: test
uses: WebFiori/workflows/.github/workflows/quality-sonarcloud.yaml@main
with:
coverage-file: 'php-8.3-coverage.xml'
secrets:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

Expand Down
145 changes: 126 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,18 +51,125 @@ A PHP library for creating HTML documents and DOM manipulation with an object-or

## 🚀 Installation

Install via Composer:
The basic use case is to have HTML document with some text in its body. The class `HTMLDoc` represent HTML document. Simply, create an instance of this class and use it to build the whole HTML document. The class can be used as follows:
``` php
use WebFiori\Ui\HTMLDoc;

```bash
composer require webfiori/ui
```

Or add to your `composer.json`:

```json
{
"require": {
"webfiori/ui": "^3.0"
All HTML elements are represented as an instance of the class `HTMLNode`. Developers can extend this class to create custom UI components as classes. The library has already pre-made components which are used in the next code sample. In addition to that, the class has methods which utilize theses components and fasten the process of adding them as children of any HTML element. The following code shows a code which is used to create a basic login form.

``` php
use WebFiori\Ui\HTMLDoc;

//Create new instance of "HTMLDoc".
$doc = new HTMLDoc();

// Build a login form.
$body = $doc->getBody();
$body->text('Login to System')->hr();

$form = $body->form(['method' => 'post', 'actiion' => 'https://example.com/login']);

$form->label('Username:');
$form->br();
$form->input('text', ['placeholder'=>'You can use your email address.', 'style' => 'width:250px']);
$form->br();
$form->label('Password:');
$form->br();
$form->input('password', ['placeholder' => 'Type in your password here.', 'style' => 'width:250px']);
$form->br();
$form->input('submit', ['value' => 'Login']);

echo $doc;
```

The output of the code would be similar to the following image.

<img src="tests/images/login-form.png">

### HTML/PHP Template Files
Some developers don't like to have everything in PHP. For example, front-end developers like to work directly with HTML since it has femiliar syntax. For this reason, the library include basic support for using HTML or PHP files as templates. If the templates are pure HTML, then variables are set in the document using slots. If the template has a mix between PHP and HTML, then PHP variables can be passed to the template.

#### HTML Templates

Assume that we have HTML file with the following markup:
``` html
<!DOCTYPE html>
<html>
<head>
<title>{{page-title}}</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="{{page-desc}}">
</head>
<body>
<section>
<h1>{{page-title}}</h1>
<p>
Hello Mr.{{ mr-name }}. This is your visit number {{visit-number}}
to our website.
</p>
</section>
</body>
</html>
```
It is noted that there are strings which are enclosed between `{{}}`. Any string enclosed between `{{}}` is called a slot. To fill any slot, its value must be passed when rendered in PHP. The file will be rendered into an instance of the class `HTMLNode`. The file can be rendered using the static method `HTMLNode::fromFile(string $templatePath, array $values)`. First parameter of the method is the path to the template and the second parameter is an associative array that holds values of slots. The keys of the array are slots names and the value of each index is the value of the slot. The following code shows how this document is loaded into an instance of the class `HTMLNode` with slots values.
``` php
$document = HTMLNode::fromFile('my-html-file.html', [
'page-title' => 'Hello Page',
'page-desc' => 'A page that shows visits numbers.',
'mr-name' => 'Ibrahim Ali',
'visit-number' => 33,
]);
echo $document
```
The output of the above PHP code will be the following HTML code.
``` html
<!DOCTYPE html>
<html>
<head>
<title>Hello Page</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="A page that shows visits numbers.">
</head>
<body>
<section>
<h1>Hello Page</h1>
<p>
Hello Mr.Ibrahim Ali. This is your visit number 33
to our website.
</p>
</section>
</body>
</html>
```
#### PHP Templates

One draw back of using raw HTML template files with slots is that it can't have dynamic PHP code. To overcome this, it is possible to have the template written as a mix between HTML and PHP. This feature allow the use of all PHP features in HTML template. Also, this allow developers to pass PHP variables in addition to values for slots.

Assuming that we have the following PHP template that shows a list of posts titles:

``` php
<div>
<?php
if (count($posts) != 0) {?>
<ul>
<?php
foreach ($posts as $postTitle) {?>
<li><?= $postTitle;?></li>
<?php
}
?>
</ul>
<?php
} else {
echo "No posts.\n";
}
}
```
Expand All @@ -80,7 +187,7 @@ Or add to your `composer.json`:
<?php
require_once 'vendor/autoload.php';

use WebFiori\UI\HTMLDoc;
use WebFiori\Ui\HTMLDoc;

// Create a complete HTML5 document
$doc = new HTMLDoc();
Expand All @@ -99,7 +206,7 @@ echo $doc;
### Build Elements Programmatically

```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

// Create a navigation menu
$nav = new HTMLNode('nav', ['class' => 'main-nav']);
Expand Down Expand Up @@ -165,7 +272,7 @@ $parent->childrenCount(); // 1
### Complete Document Structure

```php
use WebFiori\UI\HTMLDoc;
use WebFiori\Ui\HTMLDoc;

$doc = new HTMLDoc();

Expand Down Expand Up @@ -227,7 +334,7 @@ $head->addChild('link', [
### Element Creation and Manipulation

```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

// Create elements with attributes
$container = new HTMLNode('div', [
Expand Down Expand Up @@ -323,7 +430,7 @@ echo "Total items: " . $list->childrenCount(); // Direct method
### Complete Form Creation

```php
use WebFiori\UI\HTMLDoc;
use WebFiori\Ui\HTMLDoc;

$doc = new HTMLDoc();
$body = $doc->getBody();
Expand Down Expand Up @@ -470,7 +577,7 @@ $form->input('hidden', ['name' => 'form_id', 'value' => 'registration']);
### Dynamic Data Tables

```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

// Create responsive data table
$tableContainer = new HTMLNode('div', ['class' => 'table-responsive']);
Expand Down Expand Up @@ -562,7 +669,7 @@ echo $tableContainer->toHTML(true);
### Navigation Menus

```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

// Main navigation
$nav = new HTMLNode('nav', ['class' => 'navbar navbar-expand-lg navbar-dark bg-dark']);
Expand Down Expand Up @@ -644,7 +751,7 @@ echo $nestedList->toHTML(true);
### Image Galleries and Media Components

```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

// Hero section with background image
$hero = new HTMLNode('section', ['class' => 'hero-section']);
Expand Down Expand Up @@ -754,7 +861,7 @@ Create reusable HTML templates with placeholder slots:

**Using the template:**
```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

$document = HTMLNode::fromFile('template.html', [
'lang' => 'en',
Expand Down Expand Up @@ -845,7 +952,7 @@ echo $blogPost->toHTML(true);
### CSS Management

```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

$element = new HTMLNode('div');

Expand Down Expand Up @@ -925,7 +1032,7 @@ echo $visibleOnMobile->toHTML(true);
WebFiori UI implements PHP's Iterator and Countable interfaces for seamless traversal:

```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

$menu = new HTMLNode('ul', ['class' => 'main-menu']);
$menu->li('Home');
Expand Down Expand Up @@ -963,7 +1070,7 @@ while ($menu->valid()) {
### XML Document Generation

```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

// Create SAML assertion
$assertion = new HTMLNode('saml:Assertion', [
Expand Down Expand Up @@ -1001,7 +1108,7 @@ echo $assertion->toXML(true);
### Optimizing HTML Output

```php
use WebFiori\UI\HTMLNode;
use WebFiori\Ui\HTMLNode;

// For production: Use unformatted output
$container = new HTMLNode('div');
Expand Down Expand Up @@ -1181,7 +1288,7 @@ WebFiori UI implements standard PHP interfaces:
<?php
require_once 'vendor/autoload.php';

use WebFiori\UI\HTMLDoc;
use WebFiori\Ui\HTMLDoc;

// Create a complete responsive web page
$doc = new HTMLDoc();
Expand Down
2 changes: 1 addition & 1 deletion WebFiori/UI/Anchor.php → WebFiori/Ui/Anchor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

/**
* A class that represents &lt;a&gt; tag.
Expand Down
2 changes: 1 addition & 1 deletion WebFiori/UI/Br.php → WebFiori/Ui/Br.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

/**
* A class that represents &lt;br&gt; tag.
Expand Down
2 changes: 1 addition & 1 deletion WebFiori/UI/CodeSnippet.php → WebFiori/Ui/CodeSnippet.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

/**
* A class that can be used to display code snippets in good-looking way.
Expand Down
2 changes: 1 addition & 1 deletion ...I/Exceptions/InvalidNodeNameException.php → ...i/Exceptions/InvalidNodeNameException.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI\Exceptions;
namespace WebFiori\Ui\Exceptions;

use Exception;
/**
Expand Down
2 changes: 1 addition & 1 deletion .../Exceptions/TemplateNotFoundException.php → .../Exceptions/TemplateNotFoundException.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI\Exceptions;
namespace WebFiori\Ui\Exceptions;

use Exception;
/**
Expand Down
4 changes: 2 additions & 2 deletions WebFiori/UI/HTMLDoc.php → WebFiori/Ui/HTMLDoc.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

use WebFiori\Collections\LinkedList;
use WebFiori\UI\Exceptions\InvalidNodeNameException;
use WebFiori\Ui\Exceptions\InvalidNodeNameException;
/**
* A class that represents HTML document.
*
Expand Down
2 changes: 1 addition & 1 deletion WebFiori/UI/HTMLList.php → WebFiori/Ui/HTMLList.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

/**
* A class that represents ordered list or unordered list.
Expand Down
6 changes: 3 additions & 3 deletions WebFiori/UI/HTMLNode.php → WebFiori/Ui/HTMLNode.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

use Countable;
use Iterator;
use ReturnTypeWillChange;
use WebFiori\Collections\LinkedList;
use WebFiori\Collections\Stack;
use WebFiori\UI\Exceptions\InvalidNodeNameException;
use WebFiori\UI\Exceptions\TemplateNotFoundException;
use WebFiori\Ui\Exceptions\InvalidNodeNameException;
use WebFiori\Ui\Exceptions\TemplateNotFoundException;
/**
* A class that represents HTML element.
*
Expand Down
2 changes: 1 addition & 1 deletion WebFiori/UI/HTMLTable.php → WebFiori/Ui/HTMLTable.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

use InvalidArgumentException;
/**
Expand Down
2 changes: 1 addition & 1 deletion WebFiori/UI/HeadNode.php → WebFiori/Ui/HeadNode.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

use WebFiori\Collections\LinkedList;
/**
Expand Down
2 changes: 1 addition & 1 deletion WebFiori/UI/Input.php → WebFiori/Ui/Input.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

/**
* A class that represents any input element.
Expand Down
2 changes: 1 addition & 1 deletion WebFiori/UI/JsCode.php → WebFiori/Ui/JsCode.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

/**
* A node that represents in line JavaScript code that can be inserted on a
Expand Down
2 changes: 1 addition & 1 deletion WebFiori/UI/Label.php → WebFiori/Ui/Label.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
* https://github.com/WebFiori/.github/blob/main/LICENSE
*
*/
namespace WebFiori\UI;
namespace WebFiori\Ui;

/**
* A class that represents &lt;label&gt; tag.
Expand Down
Loading
Loading