{"id":19760132,"url":"https://github.com/videsk/iframex","last_synced_at":"2025-04-30T13:32:32.392Z","repository":{"id":43909015,"uuid":"186722369","full_name":"videsk/iFrameX","owner":"videsk","description":"Iframe generator with dynamic content injection like HTML, Javascript, CSS, etc. and two ways communication, parent \u003c-\u003e iframe.","archived":false,"fork":false,"pushed_at":"2023-10-27T08:31:27.000Z","size":928,"stargazers_count":26,"open_issues_count":18,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-06T02:11:21.263Z","etag":null,"topics":["dom-draw","eventlistener","generator","iframe","iframe-api","iframes","injection","javascript","javascript-library"],"latest_commit_sha":null,"homepage":"https://videsk.github.io/iFrameX","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/videsk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2019-05-15T00:49:02.000Z","updated_at":"2025-03-31T12:52:10.000Z","dependencies_parsed_at":"2024-11-12T03:35:47.411Z","dependency_job_id":"43da7268-60ff-4e1b-bab8-fbe07be29fad","html_url":"https://github.com/videsk/iFrameX","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videsk%2FiFrameX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videsk%2FiFrameX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videsk%2FiFrameX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videsk%2FiFrameX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/videsk","download_url":"https://codeload.github.com/videsk/iFrameX/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251713004,"owners_count":21631472,"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":["dom-draw","eventlistener","generator","iframe","iframe-api","iframes","injection","javascript","javascript-library"],"created_at":"2024-11-12T03:35:39.340Z","updated_at":"2025-04-30T13:32:32.030Z","avatar_url":"https://github.com/videsk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![iFrameX](https://user-images.githubusercontent.com/23618492/57744560-b3314280-7697-11e9-819f-010a7c39247a.png)\n\niFrameX is a javascript class for generate iframes with a really simple schema, also have a custom event listener.\n\nThis library is not compatible with IE11. Is designed only for modern browsers.\n\n:rotating_light: **CAUTION! Never send passwords or credentials via a custom event, can be intercepted by others scripts.**\n\n## Index\n\n- [Demo](https://github.com/videsk/iFrameX#demo)\n- [How to use](https://github.com/videsk/iFrameX#how-to-use)\n- [Params](https://github.com/videsk/iFrameX#configuration)\n  - [attributes](https://github.com/videsk/iFrameX#attr)\n  - [content](https://github.com/videsk/iFrameX#content)\n  - [container](https://github.com/videsk/iFrameX#append)\n  - [options](https://github.com/videsk/iFrameX#config)\n    - debug\n    - action\n- [Custom event listener and PostMessage](https://github.com/videsk/iFrameX#send-postmessage)\n- [Some known bugs](https://github.com/videsk/iFrameX#some-known-bugs)\n- [License](https://github.com/videsk/iFrameX#license)\n\n## Demo\n\n[Demo here](https://videsk.github.io/iFrameX/examples/)\n\n## How to use\n\nUse iFrameX is really easy, only need do two things:\n\n```js\nconst iframe = new iFrameX(options);\niframe.create();\n```\n\n## Params\n\nParams is an object can accept these parameters:\n\n- attributes: `Object` with attributes of iframe.\n- content: `Object` or `Array` with a content of iframe.\n- container: `String` or `DOM` element where append iframe in query format.\n- options: `Object` with some settings parameters.\n\n### attributes\n\n```js\nconst attributes = {\n  width: 100,\n  height: 100,\n  class: 'myiframe'\n};\n```\n\n### content\n\nThis allows adding elements in `Object` schema. Can set these parameters in object:\n\n- type: `String` value of element to create. `REQUIRED`\n- append: `String` value of element where append the new element to create. By default is `body`. `OPTIONAL`\n- content: `String` value of content element, can be `HTML`, `Javascript`, `CSS`, etc. `OPTIONAL`\n- attr: `Object` value of attributes of element. `OPTIONAL`\n\n**Object example**\n```js\nconst content = {\n  type: script,\n  append: 'body',\n  content: `alert('This executed from iframe')`,\n  attr: {\n    async: true\n  },\n};\n```\n\n**Array example**\n```js\nconst content = [\n  {\n    type: 'link',\n    append: 'head',\n    attr: {\n      href: 'https://cdn.example.com/assets/css/main.css' ,\n      rel: 'stylesheet'\n    },\n  },\n  {\n    type: 'script',\n    append: 'body',\n    content: `alert('This executed from iframe')`,\n    attr: {\n      async: true\n    },\n  },\n  {\n    type: 'button',\n    content: `My button`,\n    attr: {\n      class: 'mybutton',\n      onclick: 'myFunction()'\n    },\n  },\n];\n```\n\n### container\n\nSet where is appended the iframe, and the append value need be in elements query selector format. Read more about elements query selector format [here](https://developer.mozilla.org/es/docs/Web/API/Document/querySelector).\n\nBy default, will be appended into `body` tag.\n\n```js\nconst append = '#myid';\nconst append = '[data-id=\"893283420949032\"]';\nconst append = document.querySelector('#my-container');\n```\n\n### options\n\nIn options parameter you can set:\n\n- `ìd`: `String` Custom if of iFrame\n- `eventName`: `String` Custom event name from iframe\n- `gateway`: `Function` Function to handle the custom event from iframe\n\n```js\nconst options = {\n  id: 'my-custom-iframe-id',\n  eventName: 'MyCustomEventName',\n  gateway: function HandleEvent(data) {\n    doSomething(data);\n  },\n};\n```\n\n## Custom event listener and PostMessage\nThis provides the ability of listen custom events from iframe in a simple way.\n\nTo use it you need set `eventName` in `options` and `gateway` with a function can handle the event.\n\n### Listen event comes from iframe in parent\n\nIf you want provide states of HTML elements, data or anything you want from iframe to parent can use this feature, like this:\n\n```js\nconst options = {\n    eventName: 'CustomEventName',\n    gateway: function HandleEvent(data) {\n        // Here data schema depend how you send from iframe\n        doSomething(data);\n    },\n}; \n\n// Example content code in multiple lines\n(() =\u003e {\n    // This is how you can send from iframe to parent\n    const event = new CustomEvent(\"CustomEventName\", { detail: {date: new Date()} });\n    window.parent.document.dispatchEvent(event);\n})();\n\nconst content = {\n    type: 'script',\n    content: '(() =\u003e window.parent.document.dispatchEvent(new CustomEvent(\"CustomEventName\", { detail: {date: new Date()} })))()', // Example content in one line\n}; \n\nconst iframe = new IframeX({content, options});\niframe.create();\n```\n\nThe above example code, create an iframe and when this will render, sent custom event `CustomEventName` with data, that contains an `Object` with `date: new Date()`. (Obviously data is completely customizable)\n\n### Listen event in iframe from parent\n\nTo listen events in iframe that comes from outside is really simple:\n\n**In iframe**\n```js\nfunction newMessage(event) {\n    const data = event.detail;\n    doSomething(data);\n}\n\nwindow.addEventListener('CustomEventName', newMessage);\n```\n\n**In parent**\n```js\niframe.sendMessage('CustomEventName', {date: new Date()});\n```\n\n**Is too important the event listener on iframe will set before send the event from the parent. Is highly recommended set event listener on iframe before all scripts on the body!** \n\n### Why not use PostMessage?\n\nBecause you need set `message` listener before iframe will render on a parent. And can't create multiples custom events before and after iframe was rendered.\n\nThat means pass all data via PostMessage making too complex handle different events and data.\n\nIf you're curious is possible handle multiple events with PostMessage with the following schema:\n\n```js\nwindow.addEventListener('message', newMessage);\n\nfunction newMessage(event) {\n    const {event, data} = event.data;\n    eventHandler(event, data); // In this function need use if or key object access by event name.   \n}\n```\n\n**You can use PostMessage in parallel with iFrameX!**\n\n\n## Some known bugs\nIf have error with injection of content, try change order in object `content` of scripts that block the DOM draw, and move to the final.\nFor example `alert('hi')` block DOM drawing, try move to the final and works!.\n\n[Issue #1](https://github.com/videsk/iFrameX/issues/1).\n\n## License\n\nLGPL-2.1 License - By Videsk™\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvidesk%2Fiframex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvidesk%2Fiframex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvidesk%2Fiframex/lists"}