{"id":20180759,"url":"https://github.com/webfiori/ui","last_synced_at":"2025-04-10T05:09:13.867Z","repository":{"id":40253870,"uuid":"125832435","full_name":"WebFiori/ui","owner":"WebFiori","description":"A set of classes for creating HTML documents.","archived":false,"fork":false,"pushed_at":"2024-07-08T22:04:49.000Z","size":943,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-10T21:21:48.128Z","etag":null,"topics":["data-structures","dom","hacktoberfest","html","html-document","html-element","linked-list","php","slot","webfiori-framework","webfiori-ui"],"latest_commit_sha":null,"homepage":"https://webfiori.com/learn/ui-package","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebFiori.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://paypal.me/IbrahimBinAlshikh"]}},"created_at":"2018-03-19T09:23:26.000Z","updated_at":"2024-07-08T22:04:10.000Z","dependencies_parsed_at":"2023-12-08T23:22:29.122Z","dependency_job_id":"9d6b1f82-b373-4429-80d1-47aaeb77f5e9","html_url":"https://github.com/WebFiori/ui","commit_stats":{"total_commits":639,"total_committers":3,"mean_commits":213.0,"dds":"0.16901408450704225","last_synced_commit":"9b081eb8adf8847e638e887573e5a076aca1103e"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebFiori%2Fui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebFiori%2Fui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebFiori%2Fui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebFiori%2Fui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebFiori","download_url":"https://codeload.github.com/WebFiori/ui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224556027,"owners_count":17330907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-structures","dom","hacktoberfest","html","html-document","html-element","linked-list","php","slot","webfiori-framework","webfiori-ui"],"created_at":"2024-11-14T02:32:50.676Z","updated_at":"2024-11-14T02:32:51.149Z","avatar_url":"https://github.com/WebFiori.png","language":"PHP","readme":"# WebFiori UI Package\r\nA set of classes that provide basic web pages creation utilities in addition to creating the DOM of web pages.\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003ca href=\"https://github.com/WebFiori/ui/actions\"\u003e\r\n    \u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php83.yml/badge.svg?branch=master\"\u003e\r\n  \u003c/a\u003e\r\n  \u003ca href=\"https://codecov.io/gh/WebFiori/ui\"\u003e\r\n    \u003cimg src=\"https://codecov.io/gh/WebFiori/ui/branch/master/graph/badge.svg\" /\u003e\r\n  \u003c/a\u003e\r\n  \u003ca href=\"https://sonarcloud.io/dashboard?id=WebFiori_ui\"\u003e\r\n      \u003cimg src=\"https://sonarcloud.io/api/project_badges/measure?project=WebFiori_ui\u0026metric=alert_status\" /\u003e\r\n  \u003c/a\u003e\r\n  \u003ca href=\"https://github.com/WebFiori/ui/releases\"\u003e\r\n      \u003cimg src=\"https://img.shields.io/github/release/WebFiori/ui.svg?label=latest\" /\u003e\r\n  \u003c/a\u003e\r\n  \u003ca href=\"https://packagist.org/packages/webfiori/ui\"\u003e\r\n      \u003cimg src=\"https://img.shields.io/packagist/dt/webfiori/ui?color=light-green\"\u003e\r\n  \u003c/a\u003e\r\n\u003c/p\u003e\r\n\r\n## Content\r\n* [Supported PHP Versions](#supported-php-versions)\r\n* [Features](#features)\r\n* [Usage](#usage)\r\n  * [Basic Usage](#basic-usage)\r\n  * [Building More Complex DOM](#building-more-complex-dom)\r\n  * [HTML/PHP Template Files](#htmlphp-template-files)\r\n    * [HTML Templates](#html-templates)\r\n    * [PHP Templates](#php-templates)\r\n* [Creating XML Documents](#creating-xml-Documents)\r\n* [License](#license)\r\n \r\n\r\n## Supported PHP Versions\r\n|                                                                                       Build Status                                                                                       |\r\n|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|\r\n| \u003ca target=\"_blank\" href=\"https://github.com/WebFiori/ui/actions/workflows/php70.yml\"\u003e\u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php70.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e  |\r\n| \u003ca target=\"_blank\" href=\"https://github.com/WebFiori/ui/actions/workflows/php71.yml\"\u003e\u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php71.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e  |\r\n| \u003ca target=\"_blank\" href=\"https://github.com/WebFiori/ui/actions/workflows/php72.yml\"\u003e\u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php72.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e  |\r\n| \u003ca target=\"_blank\" href=\"https://github.com/WebFiori/ui/actions/workflows/php73.yml\"\u003e\u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php73.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e  |\r\n| \u003ca target=\"_blank\" href=\"https://github.com/WebFiori/ui/actions/workflows/php74.yml\"\u003e\u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php74.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e  |\r\n| \u003ca target=\"_blank\" href=\"https://github.com/WebFiori/ui/actions/workflows/php80.yml\"\u003e\u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php80.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e  |\r\n| \u003ca target=\"_blank\" href=\"https://github.com/WebFiori/ui/actions/workflows/php81.yml\"\u003e\u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php81.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e  |\r\n| \u003ca target=\"_blank\" href=\"https://github.com/WebFiori/ui/actions/workflows/php82.yml\"\u003e\u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php82.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e  |\r\n| \u003ca target=\"_blank\" href=\"https://github.com/WebFiori/ui/actions/workflows/php83.yml\"\u003e\u003cimg src=\"https://github.com/WebFiori/ui/actions/workflows/php83.yml/badge.svg?branch=master\"\u003e\u003c/a\u003e  |\r\n\r\n## Features\r\n* Ability to create custom HTML UI Elements in OOP approach.\r\n* Virtual DOM through PHP.\r\n* Building dynamic HTML templates with PHP.\r\n* Support for rendering XML documents.\r\n  \r\n## Usage\r\n\r\n### Basic Usage\r\n\r\nThe 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:\r\n``` php\r\nuse webfiori\\ui\\HTMLDoc;\r\n\r\n//This code will create HTML5 Document, get the \u003cbody\u003e node and, add text to it.\r\n$doc = new HTMLDoc();\r\n$doc-\u003egetBody()-\u003etext('Hello World!');\r\necho $doc;\r\n```\r\n\r\nThe output of this code is HTML 5 document. The structure of the document will be similar to the following HTML code:\r\n``` html\r\n\u003c!DOCTYPE html\u003e\r\n\u003chtml\u003e\r\n  \u003chead\u003e\r\n    \u003ctitle\u003e\r\n      Default\r\n    \u003c/title\u003e\r\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no\"\u003e\r\n  \u003c/head\u003e\r\n  \u003cbody itemscope itemtype=\"http://schema.org/WebPage\"\u003e\r\n    Hello World!\r\n  \u003c/body\u003e\r\n\u003c/html\u003e\r\n```\r\n### Building More Complex DOM\r\n\r\nAll 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.\r\n\r\n``` php\r\nuse webfiori\\ui\\HTMLDoc;\r\n\r\n//Create new instance of \"HTMLDoc\".\r\n$doc = new HTMLDoc();\r\n\r\n// Build a login form.\r\n$body = $doc-\u003egetBody();\r\n$body-\u003etext('Login to System')-\u003ehr();\r\n\r\n$form = $body-\u003eform(['method' =\u003e 'post', 'actiion' =\u003e 'https://example.com/login']);\r\n\r\n$form-\u003elabel('Username:');\r\n$form-\u003ebr();\r\n$form-\u003einput('text', ['placeholder'=\u003e'You can use your email address.', 'style' =\u003e 'width:250px']);\r\n$form-\u003ebr();\r\n$form-\u003elabel('Password:');\r\n$form-\u003ebr();\r\n$form-\u003einput('password', ['placeholder' =\u003e 'Type in your password here.', 'style' =\u003e 'width:250px']);\r\n$form-\u003ebr();\r\n$form-\u003einput('submit', ['value' =\u003e 'Login']);\r\n\r\necho $doc;\r\n```\r\n\r\nThe output of the code would be similar to the following image.\r\n\r\n\u003cimg src=\"tests/images/login-form.png\"\u003e\r\n\r\n### HTML/PHP Template Files\r\nSome 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.\r\n\r\n#### HTML Templates\r\n\r\nAssume that we have HTML file with the following markup:\r\n``` html\r\n\u003c!DOCTYPE html\u003e\r\n\u003chtml\u003e\r\n    \u003chead\u003e\r\n        \u003ctitle\u003e{{page-title}}\u003c/title\u003e\r\n        \u003cmeta charset=\"UTF-8\"\u003e\r\n        \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"\u003e\r\n        \u003cmeta name=\"description\" content=\"{{page-desc}}\"\u003e\r\n    \u003c/head\u003e\r\n    \u003cbody\u003e\r\n        \u003csection\u003e\r\n            \u003ch1\u003e{{page-title}}\u003c/h1\u003e\r\n            \u003cp\u003e\r\n                Hello Mr.{{ mr-name }}. This is your visit number {{visit-number}} \r\n                to our website.\r\n            \u003c/p\u003e\r\n        \u003c/section\u003e\r\n    \u003c/body\u003e\r\n\u003c/html\u003e\r\n```\r\nIt 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.\r\n``` php\r\n$document = HTMLNode::fromFile('my-html-file.html', [\r\n    'page-title' =\u003e 'Hello Page',\r\n    'page-desc' =\u003e 'A page that shows visits numbers.',\r\n    'mr-name' =\u003e 'Ibrahim Ali',\r\n    'visit-number' =\u003e 33,\r\n]);\r\necho $document\r\n```\r\nThe output of the above PHP code will be the following HTML code.\r\n``` html\r\n\u003c!DOCTYPE html\u003e\r\n\u003chtml\u003e\r\n    \u003chead\u003e\r\n        \u003ctitle\u003eHello Page\u003c/title\u003e\r\n        \u003cmeta charset=\"UTF-8\"\u003e\r\n        \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"\u003e\r\n        \u003cmeta name=\"description\" content=\"A page that shows visits numbers.\"\u003e\r\n    \u003c/head\u003e\r\n    \u003cbody\u003e\r\n        \u003csection\u003e\r\n            \u003ch1\u003eHello Page\u003c/h1\u003e\r\n            \u003cp\u003e\r\n                Hello Mr.Ibrahim Ali. This is your visit number 33\r\n                to our website.\r\n            \u003c/p\u003e\r\n        \u003c/section\u003e\r\n    \u003c/body\u003e\r\n\u003c/html\u003e\r\n```\r\n#### PHP Templates\r\n\r\nOne 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.\r\n\r\nAssuming that we have the following PHP template that shows a list of posts titles:\r\n\r\n``` php\r\n\u003cdiv\u003e\r\n    \u003c?php \r\n    if (count($posts) != 0) {?\u003e\r\n    \u003cul\u003e\r\n    \u003c?php\r\n        foreach ($posts as $postTitle) {?\u003e\r\n        \u003cli\u003e\u003c?= $postTitle;?\u003e\u003c/li\u003e\r\n        \u003c?php\r\n        }\r\n        ?\u003e\r\n    \u003c/ul\u003e\r\n    \u003c?php\r\n    } else {\r\n        echo \"No posts.\\n\";\r\n    }\r\n    ?\u003e\r\n\u003c/div\u003e\r\n```\r\nThis template uses a variable called `$posts` as seen. The value of this variable must be passed to the template before rendering. In this case, the second parameter of the method  `HTMLNode::fromFile(string $templatePath, array $values)` will have associative array of variables. The keys of the array are variables names and the values are variables values.\r\n\r\nThe template can be loaded into object of type `HTMLNode` as follows:\r\n\r\n``` php\r\n$posts = [\r\n  'Post 1',\r\n  'Post 2',\r\n  'Post 3'\r\n];\r\n\r\n$node = HTMLNode::fromFile('posts-list.php', [\r\n  'posts' =\u003e $posts\r\n])\r\n```\r\n\r\n## Creating XML Documents\r\nIn addition to representing HTML elements, the class `HTMLNode` can be used to represent XML document. The difference between HTML and XML is that XML is case-sensitive for attributes names and elements names in addition to not having a pre-defined elements like HTML. To create XML document, the class `HTMLNode` can be used same way as It's used in creating HTML elements. At the end, the element can be converted to XML by using the method `HTMLNode::toXML()`.\r\n\r\n``` php\r\n$xml = new HTMLNode('saml:Assertion', [\r\n   'xmlns:saml' =\u003e \"urn:oasis:names:tc:SAML:2.0:assertion\",\r\n   'xmlns:xs' =\u003e \"http://www.w3.org/2001/XMLSchema\",\r\n   'ID' =\u003e \"_d71a3a8e9fcc45c9e9d248ef7049393fc8f04e5f75\",\r\n   'Version' =\u003e \"2.0\",\r\n   'IssueInstant' =\u003e \"2004-12-05T09:22:05Z\",\r\n]);\r\n$xml-\u003eaddChild('saml:Issuer')-\u003etext('https://idp.example.org/SAML2');\r\n\r\necho $xml-\u003etoXML();\r\n//Output:\r\n/*\r\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\r\n\u003csaml:Assertion xmlns:saml=\"urn:oasis:names:tc:SAML:2.0:assertion\" xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" ID=\"_d71a3a8e9fcc45c9e9d248ef7049393fc8f04e5f75\" Version=\"2.0\" IssueInstant=\"2004-12-05T09:22:05Z\"\u003e\r\n    \u003csaml:Issuer\u003e\r\n        https://idp.example.org/SAML2\r\n    \u003c/saml:Issuer\u003e\r\n\u003c/saml:Assertion\u003e\r\n*/\r\n```\r\n\r\n\r\n## License\r\nThe library is licensed under MIT license.\r\n","funding_links":["https://paypal.me/IbrahimBinAlshikh"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebfiori%2Fui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebfiori%2Fui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebfiori%2Fui/lists"}