{"id":21842862,"url":"https://github.com/pandaplatform/jar","last_synced_at":"2025-03-21T16:15:29.591Z","repository":{"id":57035329,"uuid":"61446268","full_name":"PandaPlatform/jar","owner":"PandaPlatform","description":"Panda Json Api Responses (JAR) Package","archived":false,"fork":false,"pushed_at":"2020-09-22T11:08:54.000Z","size":47,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"3.0","last_synced_at":"2024-09-30T06:57:28.463Z","etag":null,"topics":["json-response","panda-framework","php7","request-response-processing"],"latest_commit_sha":null,"homepage":"https://pandaphp.org","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/PandaPlatform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG-3.0.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-18T18:04:35.000Z","updated_at":"2024-05-08T11:44:18.000Z","dependencies_parsed_at":"2022-08-23T20:50:42.288Z","dependency_job_id":null,"html_url":"https://github.com/PandaPlatform/jar","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PandaPlatform%2Fjar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PandaPlatform%2Fjar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PandaPlatform%2Fjar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PandaPlatform%2Fjar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PandaPlatform","download_url":"https://codeload.github.com/PandaPlatform/jar/tar.gz/refs/heads/3.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244825654,"owners_count":20516592,"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":["json-response","panda-framework","php7","request-response-processing"],"created_at":"2024-11-27T22:13:33.976Z","updated_at":"2025-03-21T16:15:29.566Z","avatar_url":"https://github.com/PandaPlatform.png","language":"PHP","readme":"# Panda Json API Responses (JAR) Package\n\nThis is the Panda Json API Responses Package.\n\n[![StyleCI](https://styleci.io/repos/61446268/shield)](https://styleci.io/repos/61446268)\n[![Latest Stable Version](https://poser.pugx.org/panda/jar/v/stable?format=flat-square)](https://packagist.org/packages/panda/jar)\n[![Total Downloads](https://poser.pugx.org/panda/jar/downloads?format=flat-square)](https://packagist.org/packages/panda/jar)\n[![License](https://poser.pugx.org/panda/jar/license?format=flat-square)](https://packagist.org/packages/panda/jar)\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n  - [Through the composer](#through-the-composer)\n- [Target Audience](#target-audience)\n- [Content Models](#content-models)\n  - [JsonContent](#jsoncontent)\n  - [EventContent](#eventcontent)\n  - [XmlContent](#xmlcontent)\n  - [HtmlContent](#htmlcontent)\n- [Distinguishing response content](#distinguishing-response-content)\n\n## Introduction\n\nThe base response object consists of a list of headers and a list of content objects.\nThe AsyncResponse base object offers an interface for adding headers and content. \n\nHowever, it does not generate the response output.\nThe output can be json (which is also the purpose of this component) but can also be something else, like xml.\n\n## Installation\n\nThis package is part of the [Panda Framework](https://github.com/PandaPlatform/framework) but it's also available as a single package.\n\n### Through the composer\n\nAdd the following line to your `composer.json` file:\n```\n\"panda/jar\": \"^3.0\"\n```\n\n## Target Audience\n\nThis library was created to facilitate the development of web applications where the ui is generated on the backend.\nThis way we can freely build the ui using any library we need and simply push it to the frontend through the `jar` library.\n\nThe library provides the flexibility to allow the Javascript client to be dummy and have a standard response handler for all the cases.\nThis way, we are free to determine how the content will be handled from the backend without writing any Javascript code.\n\nThe only way where we need to write some Javascript will be to handle backend-generated events towards the frontend.\nIn this case, we have to build the frontend client to listen for specific events and include a callback. \n\n## Content Models\n\nThe jar package support a set of models that can be either `JsonContent` or `XmlContent`, which supports specific xml parsers.\n\nBased on the needs of each application, you can use a content model that suits best for your occasion.\n\n### JsonContent\n\nJsonContent should be used when we want to deliver simple json string to the client.\nThe client should know how to parse the content accordingly.\n\nExample:\n```php\nuse \\Panda\\Jar\\Http\\Response;\nuse \\Panda\\Jar\\Model\\Content\\JsonContent;\n\n// Create a new response\n$response = new Response();\n\n// Add Json Content\n$content = (new JsonContent())-\u003esetPayload('json_payload');\n$response-\u003eaddResponseContent($content, 'response_content_key');\n```\n\nThe above output would be something like this:\n```json\n{\n  \"headers\": {},\n  \"content\": {\n    \"response_content_key\": {\n      \"type\": \"json\",\n      \"payload\": \"json_payload\"\n    }\n  }\n}\n```\n\n### EventContent\n\nEventContent is a special type of JsonContent that represents an event that should be triggered to the frontend client.\nWe can use EventContents to trigger a specific event like a redirect or any javascript action.\n\nEventContent has two attributes:\n- A name, which will be the event name\n- A payload, in json format, which will be the event payload\n\nExample:\n```php\nuse \\Panda\\Jar\\Http\\Response;\nuse \\Panda\\Jar\\Model\\Content\\EventContent;\n\n// Create a new response\n$response = new Response();\n\n// Add an page reload event\n$content = (new EventContent())-\u003esetName('window.reload');\n$response-\u003eaddResponseContent($content);\n```\n\nThe above output would be something like this:\n```json\n{\n  \"headers\": {},\n  \"content\": {\n    \"0\": {\n      \"type\": \"event\",\n      \"payload\": {\n        \"name\": \"window.reload\",\n        \"value\": \"\"\n      }\n    }\n  }\n}\n```\n\nYou can catch the above event using `jQuery` like this:\n```javascript\n$(document).on('window.reload', function(ev) {\n    location.reload();\n});\n```\n\nOr you can use an EventContent with a value and use the value as attribute to the event:\n```php\nuse \\Panda\\Jar\\Http\\Response;\nuse \\Panda\\Jar\\Model\\Content\\EventContent;\n\n// Create a new response\n$response = new Response();\n\n// Add a redirect event with target url\n$content = (new EventContent())\n    -\u003esetName('window.redirect')\n    -\u003esetValue('https://pandaphp.org');\n$response-\u003eaddResponseContent($content);\n```\n\nThe above output would be something like this:\n```json\n{\n  \"headers\": {},\n  \"content\": {\n    \"0\": {\n      \"type\": \"event\",\n      \"payload\": {\n        \"name\": \"window.redirect\",\n        \"value\": \"https://pandaphp.org\"\n      }\n    }\n  }\n}\n```\n\nYou can catch the above event using `jQuery` like this:\n```javascript\n$(document).on('window.redirect', function(ev, value) {\n    window.location = value;\n});\n```\n\n### XmlContent\n\nXmlContent is a special type of content which supports parsing DOMElements.\nThe use of the XmlContent model is to transfer xml through json so that the client can handle it accordingly.\n\n### HtmlContent\n\nHtmlContent is a special type of XmlContent which transfers html.\nIt uses the same parser as the XmlContent to convert html to string and to transfer it to the client.\n\nThe HtmlContent has some extra parameters that can be set to facilitate html handling on the client side:\n- A **holder**, which is a CSS selector to point out where this html is going to be placed\n- A **method**, which will describe how the html will be placed into the holder\n  - **Append**: it will append the html in the end of the placeholder contents\n  - **Prepend**: it will prepend the html in the beginning of the placeholder contents\n  - **Replace**: it will replace the placeholder's html with the given html\n\nExample:\n```php\nuse \\Panda\\Jar\\Http\\Response;\nuse \\Panda\\Jar\\Model\\Content\\HtmlContent;\n\n// Create a new response\n$response = new Response();\n\n// Create DOMElement to add to the response\n// The DOMElement must be assigned to a DOMDocument for parsing\n$document = new DOMDocument();\n$element = new DOMElement('div', 'value');\n$document-\u003eappendChild($element);\n$element-\u003esetAttribute('class', 'test');\n\n// Set DOMElement payload\n$htmlContent = (new HtmlContent())\n    -\u003esetMethod(HtmlContent::METHOD_APPEND)\n    -\u003esetHolder('.holder_class')\n    -\u003esetDOMElementPayload($element);\n    \n// Add content to response\n$this-\u003eresponse-\u003eaddResponseContent($htmlContent, 'b_content');\n```\n\nThe above output would be something like this:\n```json\n{\n  \"headers\": {},\n  \"content\": {\n    \"html_content\": {\n      \"method\": \"append\",\n      \"holder\": \".holder_class\",\n      \"type\": \"html\",\n      \"payload\": \"\u003cdiv class=\\\"test\\\"\u003evalue\u003c/div\u003e\"\n    }\n  }\n}\n```\n\nYou can use any ui library to generate the HtmlContent. If you have access to DOMElement, it will be much easier\nOtherwise, you can simply provide the html as string using the `setPayload()` function.\n\n## Distinguishing response content\n\nThe client side should be able to distinguish the content in the response from the `type` attribute.\nEach content should have a different type value to separate the behavior of the client's javascript code.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpandaplatform%2Fjar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpandaplatform%2Fjar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpandaplatform%2Fjar/lists"}