Skip to content

Commit

Permalink
update
Browse files Browse the repository at this point in the history
  • Loading branch information
@dermatthes
dermatthes committed Nov 25, 2023
1 parent bce7dda commit 9d3b24a
Showing 1 changed file with 57 additions and 18 deletions.
75 changes: 57 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@

# JodaStyle Documentation

Welcome to the JodaStyle documentation. This guide is intended for developers who want to use or contribute to the JodaStyle project. JodaStyle is a library that enables you to render Markdown-style HTML in the browser and apply templates dynamically. It provides a set of tools for defining templates, restructuring HTML input, and implementing responsive design through the `layout=""` attribute.

## Table of Contents
- [Overview](#overview)
- [Installation](#installation)
Expand Down Expand Up @@ -39,15 +41,25 @@ Templates are registered using `Joda.registerTemplate`:
import { Joda } from "@leuffen/jodastyle";

Joda.registerTemplate("header1", `
<section class="tjs-header1">
...
<slot></slot>
<slot data-select="img" data-replace></slot>
...
<section class="tjs-header1 :: mobile :lg: ">
<div class="tjs-wrapper container-fluid">
<div class="tjs-header1__hero container">
<div class="tjs-header1__hero--row">
<div class="tjs-header1__hero--col tjs-header1__hero--col-text">
<slot></slot>
</div>
<div class="tjs-header1__hero--col tjs-header1__hero--col-image">
<slot data-select="img" data-replace></slot>
</div>
</div>
</div>
</div>
</section>
`);
```

In the example above, we define a template named `header1` that can be used to create a header section with text and an image. The `:: mobile :lg: ` syntax is used to apply responsive classes. The `<slot>` elements are placeholders that will be filled with content when the template is used.

#### Slot Attributes

| Attribute | Description | Example |
Expand All @@ -65,21 +77,27 @@ To apply a template, use the `layout` attribute:

```html
<div layout="use: #header1">
<img src="logo.webp" alt="Logo">
<p>Some text here</p>
<img src="/images/logo-systemwebsite.webp" alt="Logo"><!-- This image will be pulled to the image slot-->
<p>Text</p>
<blockquote>Text</blockquote>
<div>Sub Elements</div>
</div>
```

It's important to include the `#` symbol when referencing a template to avoid unexpected behavior.

In the example above, the `layout="use: #header1"` attribute tells JodaStyle to apply the `header1` template to the `div`. The `img` element will replace the first slot with `data-select="img"`, and the rest of the content will fill the default slot.

### Processing HTML Input with JodaSplit

JodaSplit reorganizes flat HTML into a structured tree:

```html
<joda-split>
<nav layout="use: #navbar"></nav>
<h1 layout="use: #header1">Page Title</h1>
<nav layout="use: #navbar-switch1" class="floating">
...
</nav>
<h1 layout="use: #header1" data-section-class="decreased-height">Kontakt</h1>
...
</joda-split>
```
Expand All @@ -88,16 +106,22 @@ JodaSplit transforms the input into a tree structure where `<h1>` and `<h2>` ele

You can use `<hr>` elements to insert sub-elements. Additional attributes and classes set on an element with the `layout=""` attribute will be preserved.

For a detailed example of how JodaSplit processes input, see the [jodasplit-output.html](/jodasplit/jodasplit-output.html) file.

### Responsive Design

JodaStyle includes a processor for responsive design, which applies classes based on the viewport size and custom responsive classes.

For more information on how to use responsive design with JodaStyle, refer to the [Jodaresponsive](/processor/jodaresponsive.ts) processor.

## API Reference

- `Joda.registerTemplate(name, template)`: Registers a new template.
- `Joda.getRegisteredTemplate(name)`: Retrieves a registered template.
- `JodaContentElement.setContent(content)`: Sets the content of a `JodaContentElement`.

For a complete API reference, please refer to the [index.ts](/index.ts) file.

## Configuration

JodaStyle can be configured using `jodaSiteConfig`:
Expand All @@ -110,28 +134,43 @@ jodaSiteConfig.disable_templates = true;

## Debugging

To enable debug visualization and see the processed content structure:
To enable debugging, set the appropriate flags in `jodaSiteConfig`. For example, to visualize the template structure, set `debug_visualize` to `true`:

```javascript
jodaSiteConfig.debug_visualize = true;
```

## Contributing

Contributions are welcome through standard GitHub pull requests. Please ensure you follow the project's coding standards and include tests for any new or changed functionality.
Contributions are welcome! If you would like to contribute to the project, please follow these steps:

1. Fork the repository on GitHub.
2. Clone your forked repository to your local machine.
3. Create a new branch for your feature or bug fix.
4. Make your changes and commit them to your branch.
5. Push your changes to your fork on GitHub.
6. Submit a pull request to the original repository.

Please make sure to write clear commit messages and include tests for your changes if applicable.

## License

JodaStyle is MIT licensed. See the LICENSE file for details.
JodaStyle is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.

## FAQs

**Q: How do I define a new template?**
A: Use the `Joda.registerTemplate` method to define a new template. Provide a unique name and the HTML structure for the template.
Q: How do I override a default template?
A: To override a default template, simply register a new template with the same name as the default template you wish to override.

Q: Can I use JodaStyle with a static site generator?
A: Yes, JodaStyle can be used with static site generators. You will need to ensure that the JodaStyle library is included in your build process.

Q: What should I do if I encounter unexpected behavior?
A: If you encounter unexpected behavior, please check the [debugging](#debugging) section for tips on how to diagnose the issue. If you're still unable to resolve the problem, feel free to [open an issue](https://github.com/leuffen/jodastyle/issues) on GitHub with a detailed description of the problem and steps to reproduce it.

**Q: Can I use JodaStyle for responsive design?**
A: Yes, JodaStyle includes a processor for responsive design that allows you to apply classes based on the viewport size.
Q: Where can I find examples of using JodaStyle?
A: You can find examples throughout this documentation. Additionally, the [example.html](/example.html) file provides a practical example of how to use JodaStyle in a project.

**Q: How can I contribute to JodaStyle?**
A: Contributions can be made via GitHub pull requests. Please ensure your code adheres to the project's standards and includes appropriate tests.
Q: How can I contribute to JodaStyle if I'm not a programmer?
A: Non-programmers can contribute to JodaStyle by providing feedback, reporting issues, and suggesting improvements. Documentation contributions are also welcome.

0 comments on commit 9d3b24a

Please sign in to comment.