Blade Macros
A Blade macro is a <script> or <style> block inside a view that has a data-macro attribute. Windwalker moves the script out of the page and registers it as a named module. Blade passes PHP values to it as props.
Script Macros
Macros are removed from the page after compilation, so they can sit anywhere in the view:
{{-- src/Module/Front/Home/views/home.blade.php --}}
<script data-macro="home" lang="ts" type="module">
import { onMacroReady, useMacroProps } from '@windwalker-io/core/app';
export default function () {
const props = useMacroProps();
onMacroReady(() => {
console.log(props.title);
});
}
</script>TIP
Wrapping a macro in @push('macro') is optional. It works as a visual marker and guards against leaking code into the page if a macro is accidentally left outside its block.
The macro is loaded when the view renders its <script> block with lang="ts" and content. You do not call it yourself.
Passing Props
Pass props as attributes on the script tag:
data-prop:name="php expression": adds one prop namedname.data-props="php expression": spreads an array of props.
<script
data-macro="user-card"
lang="ts"
data-prop:user-id="$user->getId()"
data-prop:title="__('app.user.title')"
data-props="$extraProps"
type="module"
>
import { useMacroProps } from '@windwalker-io/core/app';
export default function () {
const { userId, title } = useMacroProps();
}
</script>Prop names are passed through as written. Use the same key in JavaScript that you wrote in the attribute.
WARNING
Props are PHP expressions. Do not put untrusted user input directly into data-prop:* or data-props. Escape or validate it first.
Prop Name Case
HTML attribute names are case-insensitive. The HTML parser lowercases them before Windwalker reads the attribute, so camelCase names are lost:
<script
data-macro="user-card"
lang="ts"
data-prop:userId="$user->getId()"
type="module"
>// Received as "userid" in the props, not "userId"
const { userid } = useMacroProps();Write the prop name in kebab-case. Windwalker converts it to camelCase:
<script
data-macro="user-card"
lang="ts"
data-prop:user-id="$user->getId()"
>const { userId } = useMacroProps();WARNING
Do not rely on camelCase in data-prop:* names. A name such as data-prop:userId silently produces a different key, and the JavaScript gets undefined without an error.
Macros Included More Than Once
A macro's top-level code runs only once per page, because the module is cached after its first load. If a view with the macro is included several times, only the first include runs top-level code. To run the code on every include, and to receive each include's own props, put it in a function:
export default: the runtime calls the default export on every include.
{{-- views/partials/foo-runner.blade.php --}}
<script
data-macro="foo-runner"
lang="ts"
type="module"
data-prop:foo="$foo"
data-prop:options="$options"
>
import { useMacroProps } from '@windwalker-io/core/app';
export default async function () {
// Call useMacroProps() before the first await
const { foo, options } = useMacroProps<{
foo: string;
options: { a: number; b: number };
}>();
console.log(foo);
await new Foo(options).run();
}
</script>{{-- Each include receives its own props --}}
@include('partials.foo-runner', [
'foo' => 'first',
'options' => ['a' => 1, 'b' => 2],
])
@include('partials.foo-runner', [
'foo' => 'second',
'options' => ['a' => 3, 'b' => 4],
])onMacroReady(): registers a handler that runs after each include.
{{-- views/partials/foo-runner.blade.php --}}
<script
data-macro="foo-runner"
lang="ts"
type="module"
data-prop:foo="$foo"
data-prop:options="$options"
>
import { onMacroReady, useMacroProps } from '@windwalker-io/core/app';
onMacroReady(async () => {
const { foo, options } = useMacroProps<{
foo: string;
options: { a: number; b: number };
}>();
console.log(foo);
await new Foo(options).run();
});
</script>WARNING
Call useMacroProps() before the first await. It reads the props of the include that is loading, so read them before the code yields.
Style Macros
A <style data-macro> block is compiled as SCSS or CSS and removed from the page body:
<style data-macro type="text/scss">
.home-hero {
padding: 4rem 0;
}
</style>Style macros are collected by cssModulizeDeep(). See Styles and Assets.
INFO
Use a data-scope attribute on a style macro to limit its selectors to a scope in the compiled CSS.
How Macros Are Built
A script macro goes through four steps:
- Scan:
jsModulizeDeep()reads the Blade files in the scan directories (see below) and collects every non-empty<script data-macro lang="ts">block. - Write: each block is saved as a TypeScript file in the tmp folder, named
<blade-file>__<macro-id>.ts. Dots in the id become dashes. - Bundle: the file is bundled under the key
inline:<macro-id>. - Compile: when Blade renders the view, the
<script data-macro>tag is replaced with a call that loads the module under the keyinline:<macro-id>. Thedata-prop:*attributes become the props object.
At runtime, the module runs its export default or onMacroReady() handlers.
Default Scan Directories
Macros are found in these locations by default:
src/Module/<Stage>/**/*.blade.php: views in each module.views/**/*.blade.php: views at the project root and in each Windwalker package.- Packages listed in
composer.jsonunderextra.windwalker.modules, plus thesrc/Module/folder of the project.
The <Stage> name is Front or Admin, matching the stage passed to jsModulizeDeep() in fusionfile.ts.
Adding Scan Directories
Add extra patterns on the processor returned by jsModulizeDeep(). Patterns are glob strings relative to the project root:
import { jsModulizeDeep } from '@windwalker-io/core/next';
jsModulizeDeep(
'Front',
'resources/assets/src/front/main.ts',
'js/front/main.js',
{ parseBlades: false },
)
.parseBlades('src/Shared/**/*.blade.php')
.parseBlades('src/Components/**/*.blade.php');parseBlades: false: turns off the default Blade scan.mergeScripts: false: turns off the defaultassets/*.tsmerge..mergeScripts(pattern): adds more.tsfiles to merge.
WARNING
A macro is bundled only when its Blade file matches a scan pattern. If a macro in another folder does not run, add its folder as a pattern.
Where Compiled Files Are Stored
Each part of the build writes to its own folder:
- Macro TypeScript files:
./tmp/fusion/jsmodules/. The folder is removed after each build and when the dev server stops. Change the path withtmpPath. - Bundled JavaScript: the
destof the Fusion file, under the output folder. For example,js/front/main.jsis written towww/assets/js/front/main.js. - Compiled Blade views: the
cache_pathfolder. It defaults tocache/renderer/, using theCACHE_PATHenvironment variable when it is set. Files are named~<hash>.php. In debug mode the name also starts with the view name, for example~home-<hash>.php.
Debugging Macros
To inspect the generated TypeScript for a macro, keep the tmp folder:
jsModulizeDeep(
'Front',
'resources/assets/src/front/main.ts',
'js/front/main.js',
{ cleanTmp: false },
);Then open the matching file in tmp/fusion/jsmodules/. Check it for the code that Fusion bundled.
To see the PHP that Blade generated, open the file in cache/renderer/ that matches the view. Search for inline:<macro-id> to confirm the key and props. If a change does not appear, delete the cached file, or the whole folder, so Blade compiles it again.
TIP
Set cleanTmp: false only while debugging, and remove the setting afterwards. The default setting keeps the tmp folder clean.