diff --git a/changelog.md b/changelog.md index 8d625ca..bd9fea8 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,11 @@ # Changelog +## 2025-01-25 - 1.0.10 - fix(docs) +Updated handlebars template documentation and fixed repository process filtering. + +- Removed outdated smarthbs_readme and added updated documentation in smarthello_readme with enhanced usage instructions. +- Fixed process filtering in helpers.ts to skip 'smarthbs' repository. + ## 2025-01-24 - 1.0.9 - fix(core) Bump version to 1.0.9 to maintain compatibility diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 45abf63..a24dd3a 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -37,7 +37,7 @@ export default async () => { title: 'docs.foss.global', description: 'Vite & Vue powered static site generator.', ignoreDeadLinks: true, - metaChunk: true, + themeConfig: { outline: 'deep', nav: [], diff --git a/docs/.vitepress/helpers.ts b/docs/.vitepress/helpers.ts index e1dd0a6..03a9ad1 100644 --- a/docs/.vitepress/helpers.ts +++ b/docs/.vitepress/helpers.ts @@ -102,6 +102,9 @@ export async function downloadReadmes( for (const repo of repos) { const repoName: string = repo.name; + if(repoName === 'smarthbs') { + continue; + } console.log(`Processing repository: ${repoName}`); try { diff --git a/docs/push.rocks/smarthbs_readme.md b/docs/push.rocks/smarthbs_readme.md deleted file mode 100644 index f2e6fd6..0000000 --- a/docs/push.rocks/smarthbs_readme.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "@push.rocks/smarthbs" ---- -# @push.rocks/smarthbs -handlebars with better fs support - -## Install -To install `@push.rocks/smarthbs`, run the following command in your terminal: - -```bash -npm install @push.rocks/smarthbs --save -``` - -This will add `@push.rocks/smarthbs` to your project's dependencies. - -## Usage - -The `@push.rocks/smarthbs` package enhances Handlebars with improved filesystem support, making it easy to manage partials and compile directories with template files. Below is a comprehensive guide to utilizing its capabilities in your project. - -### Getting Started - -First, ensure you've imported `@push.rocks/smarthbs` using ECMAScript Module (ESM) syntax in TypeScript: - -```typescript -import * as smarthbs from '@push.rocks/smarthbs'; -``` - -### Registering Partials - -In Handlebars, *partials* are reusable templates that can be included within other templates. `@push.rocks/smarthbs` simplifies the process of registering all partials from a directory, enabling a more organized template structure. - -To register all `.hbs` files from a directory (and its subdirectories) as partials: - -```typescript -await smarthbs.registerPartialDir(pathToPartialsDirectory); -``` - -**Example:** - -```typescript -await smarthbs.registerPartialDir('./views/partials'); -``` - -This automatically registers each `.hbs` file in the directory as a partial that can be referenced by its path relative to the specified directory. - -### Compiling Templates - -`@push.rocks/smarthbs` allows you to compile an entire directory of Handlebars template files, outputting the rendered HTML to a specified directory. You can also provide a `.json` file containing data to be used by all templates during compilation. - -**Example:** - -```typescript -await smarthbs.compileDirectory(sourceDirectory, destinationDirectory, 'data.json'); -``` - -This reads all `.hbs` files in `sourceDirectory`, compiles them using the data from `data.json`, and writes the resulting HTML to `destinationDirectory`. - -### Finding Variables in Templates - -When working with complex templates, it might be useful to programmatically find all variables used within a template: - -```typescript -let varsInTemplate = await smarthbs.findVarsInHbsString(templateString); -console.log(varsInTemplate); // Outputs an array of variable names used in the template -``` - -### Checking Variables Satisfaction - -To ensure that the data provided to a template includes all necessary variables, you can compare a template against a data object: - -```typescript -let missingVars = await smarthbs.checkVarsSatisfaction(templateString, dataObject); -if(missingVars.length > 0) { - console.error('Some required variables are missing:', missingVars); -} -``` - -This function returns an array of missing variable names, allowing you to validate data completeness before rendering. - -### Templates and Strings - -You can also get templates directly from strings or files on disk, which can then be rendered with context data: - -```typescript -// From a string -let templateFromString = await smarthbs.getTemplateForString("Hello {{name}}!"); -let resultString = templateFromString({ name: "World" }); -console.log(resultString); // Outputs: Hello World! - -// From a file -let templateFromFile = await smarthbs.getTemplateForFile("./templates/greeting.hbs"); -let resultFileString = templateFromFile({ name: "File World" }); -console.log(resultFileString); // Outputs the rendered content of greeting.hbs with provided data -``` - -### Post-processing: Safe Syntax - -In scenarios where Handlebars syntax needs to be preserved during an intermediate step: - -```typescript -let safeString = await smarthbs.postprocess(yourTemplateString); -``` - -This method converts safe syntax markers (e.g., `{-{` and `}-}`) back into standard Handlebars syntax (`{{` and `}}`), useful if your templates go through multiple processing steps. - -### Advanced Usage and Helpers - -`@push.rocks/smarthbs` also supports advanced use cases and custom helpers. For example, registering a helper to log all available partials or to perform runtime template compilation based on dynamic data. - -### Conclusion - -`@push.rocks/smarthbs` provides a robust set of features to enhance your Handlebars templating, making it easier to manage and render complex templates with external data sources and organized partials. Whether you're building web applications, generating email templates, or any task involving templating, `@push.rocks/smarthbs` can simplify and streamline your workflow. - -## License and Legal Information - -This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. - -**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. - -### Trademarks - -This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH. - -### Company Information - -Task Venture Capital GmbH -Registered at District court Bremen HRB 35230 HB, Germany - -For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. - -By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works. diff --git a/docs/push.rocks/smarthello_readme.md b/docs/push.rocks/smarthello_readme.md new file mode 100644 index 0000000..a0fde78 --- /dev/null +++ b/docs/push.rocks/smarthello_readme.md @@ -0,0 +1,191 @@ +--- +title: "@push.rocks/smarthbs" +--- +# @push.rocks/smarthbs + +A library that enhances handlebars with better file system support, templates compilation, and partials registration. + +## Install + +To install `@push.rocks/smarthbs`, run the following command in your terminal: + +```bash +npm install @push.rocks/smarthbs --save +``` + +This will add `@push.rocks/smarthbs` as a dependency to your project, allowing you to leverage its enhanced Handlebars templating capabilities. + +## Usage + +The `@push.rocks/smarthbs` library extends Handlebars functionality by introducing better file system interaction, template compilation, and an easier way to manage partials. The following sections walk you through the various features and how you can utilize them for creating dynamic and organized templates. + +### Getting Started + +First, import the `@push.rocks/smarthbs` module using ECMAScript Module (ESM) syntax in a TypeScript file: + +```typescript +import * as smarthbs from '@push.rocks/smarthbs'; +``` + +### Managing Partials + +Handlebars' partials allow for embedding templates within other templates, making it simple to manage reusable pieces of template code. With `@push.rocks/smarthbs`, you can efficiently register an entire directory of partials. + +#### Registering a Directory of Partials + +To register all `.hbs` files in a directory, including those in subdirectories, as partials: + +```typescript +await smarthbs.registerPartialDir('./path/to/partials'); +``` + +Each `.hbs` file in the specified directory becomes available as a partial. Partials are identified by their paths relative to the specified directory. + +### Compiling Templates + +Compiling directories of Handlebars templates is seamless with `@push.rocks/smarthbs`. This feature reads templates from a source directory, compiles them using a specified data context, and writes the rendered output to a destination directory. + +#### Compile a Directory + +```typescript +await smarthbs.compileDirectory('./source/templates', './destination/html', 'data.json'); +``` + +Here, every `.hbs` file in `./source/templates` is compiled with data from `data.json`. The rendered outputs are saved as `.html` files in `./destination/html`. + +### Working with Variables + +When handling complex templates, you might want to analyze which variables are used, verify their satisfaction, and ensure data completeness. + +#### Finding Variables in Templates + +To extract all variables used within a Handlebars template string: + +```typescript +const templateVariables = await smarthbs.findVarsInHbsString("Your template {-{example}-} here."); +console.log(templateVariables); // Outputs an array of variable names: ['example'] +``` + +#### Ensuring Variables Satisfaction + +To check if a given data object satisfies all required variables in a template: + +```typescript +const missingVars = await smarthbs.checkVarsSatisfaction("Your template {-{example}-} here.", { anotherVar: "some value" }); +if(missingVars.length) { + console.error('Missing variables:', missingVars); +} +``` + +This function ensures the provided data object contains all variables used in the template. Otherwise, it returns an array with the names of the missing variables. + +### Rendering Templates + +You can use `@push.rocks/smarthbs` to compile Handlebars templates directly from strings or files: + +#### From a String + +```typescript +const stringTemplate = await smarthbs.getTemplateForString("Hello, {-{name}-}!"); +const renderedString = stringTemplate({ name: "World" }); +console.log(renderedString); // "Hello, World!" +``` + +#### From a File + +```typescript +const fileTemplate = await smarthbs.getTemplateForFile('./path/to/template.hbs'); +const renderedFileString = fileTemplate({ key: "value" }); +console.log(renderedFileString); // Outputs the processed template with provided data +``` + +### Ensuring Safe Syntax + +If your Handlebars templates go through multiple processing stages, you might need to protect and restore the syntax: + +```typescript +const processedString = await smarthbs.postprocess("This is {-{safe}-} syntax."); +console.log(processedString); // Restores to "This is {-{safe}-} syntax." +``` + +This approach allows you to keep placeholders intact during various stages, converting `{-{ ... }-}` syntax back to `{-{ ... }-}`. + +### Advanced Features and Helpers + +#### Custom Helpers + +Extend Handlebars with custom helpers to introduce new functionalities or debug existing templates. For instance: + +- **Analyze Helper**: Displays partials and their details. +- **Log Registered Partials**: Logs all registered partials, aiding in debugging. +- **Runtime Compilation**: Compile templates dynamically using the `__compile` helper. + +### Example: Building an HTML Page + +Suppose you are building a simple HTML page. First, define a partial for the header and a general layout: + +Create a new header partial: + +```hbs + +
+

{-{title}-}

+
+``` + +Define a base layout that includes the header and a body: + +```hbs + +{-{> header title=pageTitle}-} +
+

{-{subtitle}-}

+

{-{content}-}

+
+``` + +In your script, register partials and compile the layout: + +```typescript +import * as smarthbs from '@push.rocks/smarthbs'; + +// Register partials +await smarthbs.registerPartialDir('./partials'); + +// Prepare data for compilation +const data = { + pageTitle: "My Awesome Page", + subtitle: "Welcome to the world of dynamic templates!", + content: "Handlebars makes creating reusable templates easy." +}; + +// Compile and render the layout +const mainTemplate = await smarthbs.getTemplateForFile('./layouts/main.hbs'); +const renderedHtml = mainTemplate(data); + +console.log(renderedHtml); +// Outputs the full HTML replacing variables in the layout with data +``` + +### Conclusion + +The `@push.rocks/smarthbs` library enhances the already powerful Handlebars templating engine with capabilities that are crucial for modern development workflows, especially those involving complex template management and dynamic content generation. Whether managing large-scale projects with numerous reusable components or simply wanting a better way to handle templates and partials, this tool provides a robust solution to enhance your projects and improve productivity. + +## License and Legal Information + +This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. + +**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. + +### Trademarks + +This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH. + +### Company Information + +Task Venture Capital GmbH +Registered at District court Bremen HRB 35230 HB, Germany + +For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. + +By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.