|
|
@@ -0,0 +1,391 @@
|
|
|
+using Spry;
|
|
|
+using Inversion;
|
|
|
+
|
|
|
+/**
|
|
|
+ * ComponentsMkconstPage - Documentation for the spry-mkconst tool
|
|
|
+ *
|
|
|
+ * This page explains how to use spry-mkconst to convert HTML files
|
|
|
+ * to Vala string constants that can be referenced in component markup properties.
|
|
|
+ */
|
|
|
+public class ComponentsMkconstPage : PageComponent {
|
|
|
+
|
|
|
+ public const string ROUTE = "/components/spry-mkconst";
|
|
|
+
|
|
|
+ private ComponentFactory factory = inject<ComponentFactory>();
|
|
|
+
|
|
|
+ public override string markup { get {
|
|
|
+ return """
|
|
|
+ <div sid="page" class="doc-content">
|
|
|
+ <h1>spry-mkconst Tool</h1>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>What is spry-mkconst?</h2>
|
|
|
+ <p>
|
|
|
+ <code>spry-mkconst</code> is a command-line tool that converts file contents
|
|
|
+ (typically HTML templates) into Vala string constants. This allows you to:
|
|
|
+ </p>
|
|
|
+ <ul>
|
|
|
+ <li>Keep HTML templates in separate files for easier editing</li>
|
|
|
+ <li>Maintain valid Vala syntax that the Vala language server can recognize</li>
|
|
|
+ <li>Reference generated constants from your component's <code>markup</code> property</li>
|
|
|
+ </ul>
|
|
|
+ <p>
|
|
|
+ Unlike the previous <code>spry-mkcomponent</code> approach which modified Vala files,
|
|
|
+ <code>spry-mkconst</code> generates separate constant declarations, keeping your
|
|
|
+ original Vala files intact and recognizable by IDEs and language servers.
|
|
|
+ </p>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>Command-Line Usage</h2>
|
|
|
+
|
|
|
+ <spry-component name="CodeBlockComponent" sid="usage-code"/>
|
|
|
+
|
|
|
+ <h3>Options</h3>
|
|
|
+ <table class="doc-table">
|
|
|
+ <thead>
|
|
|
+ <tr>
|
|
|
+ <th>Option</th>
|
|
|
+ <th>Description</th>
|
|
|
+ </tr>
|
|
|
+ </thead>
|
|
|
+ <tbody>
|
|
|
+ <tr>
|
|
|
+ <td><code>-o, --output FILE</code></td>
|
|
|
+ <td>Output file path (default: stdout)</td>
|
|
|
+ </tr>
|
|
|
+ <tr>
|
|
|
+ <td><code>--ns NAMESPACE</code></td>
|
|
|
+ <td>Wrap const in a namespace</td>
|
|
|
+ </tr>
|
|
|
+ <tr>
|
|
|
+ <td><code>-n, --name NAME</code></td>
|
|
|
+ <td>Override const name (default: derived from filename)</td>
|
|
|
+ </tr>
|
|
|
+ <tr>
|
|
|
+ <td><code>-v, --version</code></td>
|
|
|
+ <td>Show version information</td>
|
|
|
+ </tr>
|
|
|
+ <tr>
|
|
|
+ <td><code>--help</code></td>
|
|
|
+ <td>Show help message</td>
|
|
|
+ </tr>
|
|
|
+ </tbody>
|
|
|
+ </table>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>How It Works</h2>
|
|
|
+ <p>
|
|
|
+ The tool takes a single input file and generates a Vala const declaration:
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <spry-component name="CodeBlockComponent" sid="workflow-diagram"/>
|
|
|
+
|
|
|
+ <div class="info-box">
|
|
|
+ <p>
|
|
|
+ <strong>💡 Key Concept:</strong> The const name is automatically derived from the
|
|
|
+ filename using CAPITAL_SNAKE_CASE. For example, <code>UserContentComponent.vala.html</code>
|
|
|
+ becomes <code>USER_CONTENT_COMPONENT_VALA_HTML</code>.
|
|
|
+ </p>
|
|
|
+ </div>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>Example Transformation</h2>
|
|
|
+ <p>
|
|
|
+ Here's a complete example showing how the tool works:
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <h3>Input HTML File (<code>UserContentComponent.vala.html</code>)</h3>
|
|
|
+ <spry-component name="CodeBlockComponent" sid="input-html"/>
|
|
|
+
|
|
|
+ <h3>Generated Output (stdout or file)</h3>
|
|
|
+ <spry-component name="CodeBlockComponent" sid="output-const"/>
|
|
|
+
|
|
|
+ <h3>Your Vala Component (unchanged, valid Vala)</h3>
|
|
|
+ <spry-component name="CodeBlockComponent" sid="vala-component"/>
|
|
|
+
|
|
|
+ <p>
|
|
|
+ The key advantage is that your Vala file remains valid, parseable Vala code.
|
|
|
+ The Vala language server can still recognize it, provide autocomplete, and
|
|
|
+ show errors. The generated constant is referenced via <code>return USER_CONTENT_COMPONENT_VALA_HTML;</code>
|
|
|
+ </p>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>Integrating with Meson</h2>
|
|
|
+ <p>
|
|
|
+ The recommended way to use spry-mkconst is with meson's build system.
|
|
|
+ You generate a separate Vala file containing the const declarations,
|
|
|
+ then include it in your build.
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <h3>Basic meson.build Setup</h3>
|
|
|
+ <spry-component name="CodeBlockComponent" sid="meson-basic"/>
|
|
|
+
|
|
|
+ <h3>With Namespace</h3>
|
|
|
+ <spry-component name="CodeBlockComponent" sid="meson-namespace"/>
|
|
|
+
|
|
|
+ <h3>Complete Example</h3>
|
|
|
+ <spry-component name="CodeBlockComponent" sid="meson-complete"/>
|
|
|
+
|
|
|
+ <div class="info-box">
|
|
|
+ <p>
|
|
|
+ <strong>💡 Tip:</strong> The generated file should be included in your
|
|
|
+ executable's sources. Meson will run spry-mkconst automatically before
|
|
|
+ compilation.
|
|
|
+ </p>
|
|
|
+ </div>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>HTML Template Guidelines</h2>
|
|
|
+ <p>
|
|
|
+ When creating HTML templates for use with spry-mkconst, follow these guidelines:
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <ul>
|
|
|
+ <li>
|
|
|
+ <strong>Use <code>sid</code> attributes</strong> - Add <code>sid="name"</code>
|
|
|
+ to elements you need to access from Vala code via <code>this["name"]</code>
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ <strong>Name templates consistently</strong> - Use <code>ComponentName.vala.html</code>
|
|
|
+ for clear association with the component
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ <strong>Use HTMX attributes</strong> - Add <code>hx-*</code> attributes for
|
|
|
+ interactivity without writing JavaScript
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ <strong>Avoid complex logic</strong> - Keep templates focused on structure;
|
|
|
+ use Vala for conditional rendering
|
|
|
+ </li>
|
|
|
+ </ul>
|
|
|
+
|
|
|
+ <spry-component name="CodeBlockComponent" sid="html-guidelines"/>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>Why spry-mkconst vs spry-mkcomponent?</h2>
|
|
|
+ <p>
|
|
|
+ The previous <code>spry-mkcomponent</code> tool modified Vala source files by
|
|
|
+ injecting HTML into the markup getter. This had a significant drawback:
|
|
|
+ the Vala language server couldn't recognize the modified files as valid Vala
|
|
|
+ during development.
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>
|
|
|
+ <code>spry-mkconst</code> solves this by:
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <ul>
|
|
|
+ <li>Keeping your Vala files as valid, parseable Vala code</li>
|
|
|
+ <li>Generating constants in a separate file that's included at build time</li>
|
|
|
+ <li>Allowing the language server to provide full IDE support</li>
|
|
|
+ <li>Using <code>public override string markup { get { return CONSTANT_NAME; } }</code>
|
|
|
+ which is valid Vala syntax</li>
|
|
|
+ </ul>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>Workflow Integration</h2>
|
|
|
+ <p>
|
|
|
+ A typical development workflow with spry-mkconst looks like this:
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <ol>
|
|
|
+ <li><strong>Create</strong> your HTML template file (e.g., <code>MyComponent.vala.html</code>)</li>
|
|
|
+ <li><strong>Write</strong> your Vala component referencing the generated constant name</li>
|
|
|
+ <li><strong>Configure</strong> meson to generate the const file</li>
|
|
|
+ <li><strong>Build</strong> your project - meson runs spry-mkconst automatically</li>
|
|
|
+ <li><strong>Iterate</strong> - Edit the HTML file; changes are picked up on rebuild</li>
|
|
|
+ </ol>
|
|
|
+
|
|
|
+ <p>
|
|
|
+ During development, you can run the tool manually to see the generated output:
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <spry-component name="CodeBlockComponent" sid="manual-run"/>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>When to Use spry-mkconst</h2>
|
|
|
+
|
|
|
+ <h3>✅ Good Use Cases</h3>
|
|
|
+ <ul>
|
|
|
+ <li>Components with substantial HTML markup</li>
|
|
|
+ <li>When you need Vala language server support (autocomplete, errors)</li>
|
|
|
+ <li>Teams where designers work on HTML separately from developers</li>
|
|
|
+ <li>Keeping Vala files focused on logic</li>
|
|
|
+ </ul>
|
|
|
+
|
|
|
+ <h3>❌ When to Skip It</h3>
|
|
|
+ <ul>
|
|
|
+ <li>Simple components with minimal markup (inline is fine)</li>
|
|
|
+ <li>Quick prototypes where separation isn't beneficial</li>
|
|
|
+ <li>Components with dynamically generated markup</li>
|
|
|
+ </ul>
|
|
|
+
|
|
|
+ <div class="info-box">
|
|
|
+ <p>
|
|
|
+ <strong>💡 Remember:</strong> You can always inline markup directly in your
|
|
|
+ Vala files using triple-quoted strings. spry-mkconst is opt-in - use it
|
|
|
+ when the separation provides value for your project.
|
|
|
+ </p>
|
|
|
+ </div>
|
|
|
+ </section>
|
|
|
+
|
|
|
+ <section class="doc-section">
|
|
|
+ <h2>Next Steps</h2>
|
|
|
+ <div class="nav-cards">
|
|
|
+ <a href="/components/template-syntax" class="nav-card">
|
|
|
+ <h3>← Template Syntax</h3>
|
|
|
+ <p>Learn about component template syntax</p>
|
|
|
+ </a>
|
|
|
+ <a href="/components/actions" class="nav-card">
|
|
|
+ <h3>Actions →</h3>
|
|
|
+ <p>Handle user interactions in components</p>
|
|
|
+ </a>
|
|
|
+ </div>
|
|
|
+ </section>
|
|
|
+ </div>
|
|
|
+ """;
|
|
|
+ }}
|
|
|
+
|
|
|
+ public override async void prepare() throws Error {
|
|
|
+ var usage_code = get_component_child<CodeBlockComponent>("usage-code");
|
|
|
+ usage_code.language = "Bash";
|
|
|
+ usage_code.code = "spry-mkconst [OPTIONS] <INPUT_FILE>\n\n" +
|
|
|
+ "# Examples:\n" +
|
|
|
+ "spry-mkconst Templates/UserContent.html\n" +
|
|
|
+ "spry-mkconst -o generated/constants.vala Templates/UserContent.html\n" +
|
|
|
+ "spry-mkconst --ns MyApp.Templates Templates/UserContent.html\n" +
|
|
|
+ "spry-mkconst -n CUSTOM_NAME Templates/UserContent.html";
|
|
|
+
|
|
|
+ var workflow_diagram = get_component_child<CodeBlockComponent>("workflow-diagram");
|
|
|
+ workflow_diagram.language = "Text";
|
|
|
+ workflow_diagram.code = "┌─────────────────────────────────────┐\n" +
|
|
|
+ "│ UserContentComponent.vala.html │\n" +
|
|
|
+ "│ (HTML template) │\n" +
|
|
|
+ "└─────────────┬───────────────────────┘\n" +
|
|
|
+ " │\n" +
|
|
|
+ " ▼\n" +
|
|
|
+ " ┌───────────────┐\n" +
|
|
|
+ " │ spry-mkconst │\n" +
|
|
|
+ " └───────┬───────┘\n" +
|
|
|
+ " │\n" +
|
|
|
+ " ▼\n" +
|
|
|
+ "┌─────────────────────────────────────────────────┐\n" +
|
|
|
+ "│ const string USER_CONTENT_COMPONENT_VALA_HTML │\n" +
|
|
|
+ "│ = \"\"\"<html>...</html>\"\"\"; │\n" +
|
|
|
+ "└─────────────────────────────────────────────────┘";
|
|
|
+
|
|
|
+ var input_html = get_component_child<CodeBlockComponent>("input-html");
|
|
|
+ input_html.language = "HTML";
|
|
|
+ input_html.code = "<p>You said: <strong sid=\"message\"></strong> <em>(via <span sid=\"action\"></span>)</em></p>";
|
|
|
+
|
|
|
+ var output_const = get_component_child<CodeBlockComponent>("output-const");
|
|
|
+ output_const.language = "Vala";
|
|
|
+ output_const.code = "const string USER_CONTENT_COMPONENT_VALA_HTML = \"\"\"\n" +
|
|
|
+ "<p>You said: <strong sid=\"message\"></strong> <em>(via <span sid=\"action\"></span>)</em></p>\n" +
|
|
|
+ "\"\"\";";
|
|
|
+
|
|
|
+ var vala_component = get_component_child<CodeBlockComponent>("vala-component");
|
|
|
+ vala_component.language = "Vala";
|
|
|
+ vala_component.code = "// This file is valid Vala - the language server recognizes it!\n" +
|
|
|
+ "class UserContentComponent : Component {\n" +
|
|
|
+ " public override string markup { get { return USER_CONTENT_COMPONENT_VALA_HTML; } }\n\n" +
|
|
|
+ " public async override void handle_action(string action) throws Error {\n" +
|
|
|
+ " this[\"message\"].text_content = \"Hello, World!\";\n" +
|
|
|
+ " }\n" +
|
|
|
+ "}";
|
|
|
+
|
|
|
+ var meson_basic = get_component_child<CodeBlockComponent>("meson-basic");
|
|
|
+ meson_basic.language = "Meson";
|
|
|
+ meson_basic.code = "# Find the tool\n" +
|
|
|
+ "spry_mkconst = find_program('spry-mkconst')\n\n" +
|
|
|
+ "# Generate constants from HTML templates\n" +
|
|
|
+ "markup_constants = custom_target('markup-constants',\n" +
|
|
|
+ " input: 'Templates/UserContentComponent.vala.html',\n" +
|
|
|
+ " output: 'UserContentConstants.vala',\n" +
|
|
|
+ " command: [spry_mkconst, '@INPUT@', '-o', '@OUTPUT@']\n" +
|
|
|
+ ")\n\n" +
|
|
|
+ "# Include in your executable\n" +
|
|
|
+ "executable('myapp',\n" +
|
|
|
+ " sources: ['Main.vala', 'UserContentComponent.vala', markup_constants],\n" +
|
|
|
+ " dependencies: [spry_dep]\n" +
|
|
|
+ ")";
|
|
|
+
|
|
|
+ var meson_namespace = get_component_child<CodeBlockComponent>("meson-namespace");
|
|
|
+ meson_namespace.language = "Meson";
|
|
|
+ meson_namespace.code = "# Generate constants with namespace\n" +
|
|
|
+ "spry_mkconst = find_program('spry-mkconst')\n\n" +
|
|
|
+ "markup_constants = custom_target('markup-constants',\n" +
|
|
|
+ " input: 'Templates/UserContentComponent.vala.html',\n" +
|
|
|
+ " output: 'UserContentConstants.vala',\n" +
|
|
|
+ " command: [spry_mkconst, '@INPUT@', '-o', '@OUTPUT@',\n" +
|
|
|
+ " '--ns', 'MyApp.Markup']\n" +
|
|
|
+ ")\n\n" +
|
|
|
+ "# In your Vala file, use:\n" +
|
|
|
+ "# public override string markup { get { return MyApp.Markup.USER_CONTENT_COMPONENT_VALA_HTML; } }";
|
|
|
+
|
|
|
+ var meson_complete = get_component_child<CodeBlockComponent>("meson-complete");
|
|
|
+ meson_complete.language = "Meson";
|
|
|
+ meson_complete.code = "# Find the spry-mkconst tool\n" +
|
|
|
+ "spry_mkconst = find_program('spry-mkconst')\n\n" +
|
|
|
+ "# Collect all HTML template files\n" +
|
|
|
+ "template_files = files(\n" +
|
|
|
+ " 'Templates/HeaderComponent.vala.html',\n" +
|
|
|
+ " 'Templates/FooterComponent.vala.html',\n" +
|
|
|
+ " 'Templates/UserContentComponent.vala.html',\n" +
|
|
|
+ ")\n\n" +
|
|
|
+ "# Generate a single constants file from all templates\n" +
|
|
|
+ "# Note: You can also generate separate files per template\n" +
|
|
|
+ "markup_constants = custom_target('markup-constants',\n" +
|
|
|
+ " input: template_files,\n" +
|
|
|
+ " output: 'MarkupConstants.vala',\n" +
|
|
|
+ " command: [spry_mkconst, '@INPUT@', '-o', '@OUTPUT@', '--ns', 'Markup']\n" +
|
|
|
+ ")\n\n" +
|
|
|
+ "# Component source files (reference the constants)\n" +
|
|
|
+ "component_sources = files(\n" +
|
|
|
+ " 'Components/HeaderComponent.vala',\n" +
|
|
|
+ " 'Components/FooterComponent.vala',\n" +
|
|
|
+ " 'Components/UserContentComponent.vala',\n" +
|
|
|
+ ")\n\n" +
|
|
|
+ "# Build executable\n" +
|
|
|
+ "executable('myapp',\n" +
|
|
|
+ " sources: ['Main.vala', component_sources, markup_constants],\n" +
|
|
|
+ " dependencies: [spry_dep],\n" +
|
|
|
+ ")";
|
|
|
+
|
|
|
+ var html_guidelines = get_component_child<CodeBlockComponent>("html-guidelines");
|
|
|
+ html_guidelines.language = "HTML";
|
|
|
+ html_guidelines.code = "<!-- Good: Use sid attributes for elements you need to access -->\n" +
|
|
|
+ "<div class=\"user-card\">\n" +
|
|
|
+ " <h2 sid=\"username\"></h2>\n" +
|
|
|
+ " <p sid=\"email\"></p>\n" +
|
|
|
+ " <button sid=\"delete-btn\" hx-post=\"/delete\" hx-target=\"closest .user-card\">\n" +
|
|
|
+ " Delete\n" +
|
|
|
+ " </button>\n" +
|
|
|
+ "</div>\n\n" +
|
|
|
+ "<!-- Good: Keep it simple and focused on structure -->\n" +
|
|
|
+ "<form sid=\"login-form\" hx-post=\"/login\">\n" +
|
|
|
+ " <input type=\"text\" name=\"username\" sid=\"username-input\"/>\n" +
|
|
|
+ " <input type=\"password\" name=\"password\" sid=\"password-input\"/>\n" +
|
|
|
+ " <button type=\"submit\">Login</button>\n" +
|
|
|
+ "</form>";
|
|
|
+
|
|
|
+ var manual_run = get_component_child<CodeBlockComponent>("manual-run");
|
|
|
+ manual_run.language = "Bash";
|
|
|
+ manual_run.code = "# Run manually to see generated output\n" +
|
|
|
+ "spry-mkconst Templates/MyComponent.vala.html\n\n" +
|
|
|
+ "# Save to a file\n" +
|
|
|
+ "spry-mkconst Templates/MyComponent.vala.html -o generated/MyComponentMarkup.vala\n\n" +
|
|
|
+ "# View the result\n" +
|
|
|
+ "cat generated/MyComponentMarkup.vala\n\n" +
|
|
|
+ "# Generate with namespace\n" +
|
|
|
+ "spry-mkconst Templates/MyComponent.vala.html --ns MyApp.Templates";
|
|
|
+ }
|
|
|
+}
|
