{"id":25894578,"url":"https://github.com/devessenceinc/BlazorScriptReload","last_synced_at":"2025-03-02T22:02:17.895Z","repository":{"id":270357978,"uuid":"910110612","full_name":"devessenceinc/BlazorScriptReload","owner":"devessenceinc","description":"A solution for using JavaScript in Blazor Web Applications","archived":false,"fork":false,"pushed_at":"2025-02-11T19:18:56.000Z","size":957,"stargazers_count":10,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-11T20:27:09.093Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devessenceinc.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":"2024-12-30T14:17:01.000Z","updated_at":"2025-02-11T19:19:00.000Z","dependencies_parsed_at":"2024-12-30T15:28:18.686Z","dependency_job_id":"2b7dd73f-a080-459d-adf6-3ed2db889d14","html_url":"https://github.com/devessenceinc/BlazorScriptReload","commit_stats":null,"previous_names":["devessenceinc/blazorscriptreload"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devessenceinc%2FBlazorScriptReload","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devessenceinc%2FBlazorScriptReload/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devessenceinc%2FBlazorScriptReload/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devessenceinc%2FBlazorScriptReload/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devessenceinc","download_url":"https://codeload.github.com/devessenceinc/BlazorScriptReload/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241577073,"owners_count":19984941,"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":[],"created_at":"2025-03-02T22:01:48.762Z","updated_at":"2025-03-02T22:02:17.860Z","avatar_url":"https://github.com/devessenceinc.png","language":"JavaScript","funding_links":[],"categories":["Recently Updated","Libraries \u0026 Extensions"],"sub_categories":["[Mar 01, 2025](/content/2025/03/01/README.md)","2D/3D Rendering engines"],"readme":"# Blazor Script Reload\n\n![BlazorScriptReload - a solution for using JavaScript in Blazor Web Applications](https://github.com/devessenceinc/BlazorScriptReload/blob/main/BlazorScriptReload.png?raw=true)\n\nBlazor Web Applications (ie. Static Server-Side Blazor using Enhanced Navigation) only process ```\u003cscript\u003e``` elements during the initial page load. This means that any ```\u003cscript\u003e``` elements which are encountered during subsequent \"enhanced\" navigations are ignored, resulting in unexpected behavior and broken functionality. \n\nThis project provides a simple solution for allowing ```\u003cscript\u003e``` elements to behave in a standard manner in a Blazor Web Application. It was inspired by the [BlazorPageScript](https://github.com/MackinnonBuck/blazor-page-script) project created by Mackinnon Buck however it takes a different approach.\n\n## Goals\n\n- allow developers to use standard ```\u003cscript\u003e``` elements in their Blazor Web Application components\n- allow content creators to use standard ```\u003cscript\u003e``` elements in their markup (if they have the permission to do so in their application)\n- leverage standard browser script loading behaviors\n- support external and in-line scripts\n- support scripts in the head and body of a document\n- support most standard script libraries without requiring any modification\n- support script loading order to manage script dependencies\n- provide a simple alternative for simulating onload behavior during enhanced navigation\n- ensure that scripts are only executed once per enhanced navigation** (see Notes)\n- utilize an opt-in approach to avoid undesired side effects\n- provide a simple integration story\n\n## Solution\n\nUtilizes a custom HTML element which interacts with the Blazor \"enhancedload\" event. When an \"enhancedload\" occurs it triggers logic which iterates over all of the script elements in the page. Any script element which has a **data-reload** attribute specified is \"replaced\" in the DOM which forces the browser to process the script element utilizing its standard script loading approach.\n\n## Integration\n\n- include the latest BlazorScriptReload Nuget package into your Blazor Web Application project:\n\n```\n\u003cItemGroup\u003e\n    \u003cPackageReference Include=\"BlazorScriptReload\" Version=\"1.0.4\" /\u003e\n\u003c/ItemGroup\u003e\n```\n\n- add a ```@using BlazorScriptReload``` to your _Imports.razor (or simply add the using statement to App.razor as that is the only place it will be referenced)\n\n- include the ```\u003cScriptReload /\u003e``` component at the bottom of your body section in App.razor:\n\n```\n\u003cbody\u003e\n    \u003cRoutes /\u003e\n    ...\n    \u003cscript src=\"_framework/blazor.web.js\"\u003e\u003c/script\u003e\n    \u003cScriptReload /\u003e\n\u003c/body\u003e\n```\n\n## Basic Usage\n\nStandard ```\u003cscript\u003e``` elements can be used in Blazor components or page content (including support for all standard attributes such as \"type\", \"integrity\", \"crossorigin\", etc...). However in order for a ```\u003cscript\u003e``` element to be reloaded it MUST include a custom \"**data-reload**\" attribute:\n\n**data-reload=\"once\"** - indicates that the script element should be loaded during an enhanced navigation if it was not already loaded previously. This is useful for JavaScript libraries which only need to be loaded once and are then utilized by other JavaScript logic in your application.\n\n**data-reload=\"always\" (or \"true\")** - indicates that the script element should always be reloaded during an enhanced navigation. This is useful if you have scripts which are expected to be executed on every enhanced navigation (ie. in-line scripts).\n\n## Examples\n\nThe example below is a standard Blazor page component which contains two ```\u003cscript\u003e``` elements (in-line and external) which log a message to the browser console. In a standard Blazor Web Application these ```\u003cscript\u003e``` elements would be ignored if the \"example\" page was requested after an \"enhanced navigation\" (ie. if a user initially loaded the \"home\" page and then navigated to the \"example\" page). Blazor Script Reload will ensure that these scripts are always executed as expected. You can test the difference in behavior by modifying the data-reload attribute value on the ```\u003cscript\u003e``` elements and observing the results.\n\n_Example1.razor_\n```\n@page \"/example1\"\n\n\u003cscript data-reload=\"always\"\u003econsole.log('Inline Script');\u003c/script\u003e\n\u003cscript src=\"Example1.js\" data-reload=\"always\"\u003e\u003c/script\u003e\n\n```\n_Example1.js_\n\n```\nconsole.log('External Script');\n```\n\nThe example below is a standard Blazor page component which contains three ```\u003cscript\u003e``` elements. The first two elements are external JavaScript libraries (requiring integrity and crossorigin attributes for security) which only need to be loaded once. The third element is a local script which displays a gallery of images and needs to be executed on every enhanced navigation to the page. Note that the third script is dependent upon the capabilities of the first two scripts and therefore needs to be loaded last. \n\n```\n@page \"/example2\"\n\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/masonry-layout@4.2.2/dist/masonry.pkgd.min.js\" data-reload=\"once\" integrity=\"sha384-GNFwBvfVxBkLMJpYMOABq3c+d3KnQxudP/mGPkzpZSTYykLBNsZEnG2D9G/X/+7D\" crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://unpkg.com/imagesloaded@5.0.0/imagesloaded.pkgd.min.js\" data-reload=\"once\" integrity=\"sha384-e3sbGkYzJZpi7OdZc2eUoj7saI8K/Qbn+kPTdWyUQloiKIc9HRH4RUWFVxTonzTg\" crossorigin=\"anonymous\"\u003e\u003c/script\u003e\n\u003cscript src=\"gallery.js\" data-reload=\"always\"\u003e\u003c/script\u003e\n```\n\nTake a look at the `samples` folder in this repository for more advanced usage examples.\n\n## BasicSample\n\nThe BasicSample project in the `samples` folder can be used for reference. Make sure you set BasicSample as the Startup Project for your solution before you run the project. The BasicSample has a number of different scenarios and it allows you to toggle the Blazor Script Reload option at run-time to view the differences in behavior.\n\n![image](https://github.com/user-attachments/assets/65ecc9d0-3d82-4c7d-95d3-42130580b9f0)\n\n## Notes\n\nThis solution does not actually \"load\" JavaScript - it simply replaces the ```\u003cscript\u003e``` element in the DOM and relies on the browser to load the script using its standard behavior (ie. taking into consideration caching, etc...).\n\nExternal scripts are identified using their \"src\" attribute. In-line scripts are identified by their \"id\" attribute, or if it is not specified, by their content. \n\nThis solution DOES support Stream Rendering however due to the fact that Stream Rendering refreshes the UI multiple times as content is streamed to the browser, your script may be executed multiple times. ** Note that in .NET 9 there is a new event 'enhancednavigationend' which is triggered after all stream rendering has completed and would be a better option for ensuring script reloads only occur once per enhanced navigation. This event is not utilized currently as BlazorScriptReload needs to support applications using .NET 8 (LTS).\n\nThis solution DOES support Interactive components within Static Blazor Web Applications. The BasicSample project includes an Interactive page to demonstrate that BlazorScriptReload supports interactive components.\n\nThis solution does NOT support Globally Interactive Blazor Applications. Globally Interactive Blazor Applications use a completely different approach for managing JavaScript integration (ie. JS Interop). \n\nThis solution does NOT support _document.write_. This is because BlazorScriptReload executes after the page has been rendered, which means _document.write_ will overwrite the entire document's content. Note that standard Blazor Web Applications also do not support _document.write_ as it is ignored on enhanced navigations. So the recommended solution is to replace _document.write_ logic with alternatives which target specific DOM elements (see the BasicSample application for reference). \n\nThis solution is NOT intended to solve every challenge related to JavaScript and Blazor Web Applications. There are scenarios where this solution is not appropriate and developers will need to explore alternative solutions such as [Blazor Page Script](https://github.com/MackinnonBuck/blazor-page-script) or [BlazorJsComponents](https://github.com/MackinnonBuck/blazor-js-components).\n\nThis solution was originally created for [Oqtane](https://www.oqtane.org) - a CMS and Application Framework for Blazor and .NET MAUI. Oqtane is a modern development platform which solves many challenging problems for developers (ie. multi-tenancy, modularity, etc...) allowing them to focus on building applications rather than infrastructure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevessenceinc%2FBlazorScriptReload","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevessenceinc%2FBlazorScriptReload","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevessenceinc%2FBlazorScriptReload/lists"}