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 9d3b24a commit 98c5ca6
Show file tree
Hide file tree
Showing 4 changed files with 140 additions and 59 deletions.
125 changes: 66 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@

# 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.
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 DOM manipulation using CSS attributes and provides a set of tools for defining templates, restructuring HTML input, and implementing responsive design through custom attributes and CSS variables.

## Table of Contents
- [Overview](#overview)
- [Installation](#installation)
- [Usage](#usage)
- [DOM Manipulation](#dom-manipulation)
- [Defining Templates](#defining-templates)
- [Using Templates](#using-templates)
- [Processing HTML Input with JodaSplit](#processing-html-input-with-jodasplit)
Expand All @@ -24,18 +25,63 @@ JodaStyle is a library designed to render Markdown-style HTML in the browser and

## Installation

To include JodaStyle in your project, add the following script and stylesheet to your HTML:
To install JodaStyle, run the following command in your project directory:

```html
<script src="path/to/jodastyle.js"></script>
<link rel="stylesheet" href="path/to/jodastyle.css">
```bash
npm install @leuffen/jodastyle
```

## Usage

### DOM Manipulation

JodaStyle allows for DOM manipulation using CSS attributes. Here are some examples:

#### Wrap

Wrap multiple consecutive elements in a new element using the `--joda-wrap` attribute:

```html
<div class="box"></div>
<div class="box"></div>
<div class="box"></div>
```

```css
.box {
--joda-wrap: @row;
}
```

The resulting DOM:

```html
<div class="row">
<div class="box"></div>
<div class="box"></div>
<div class="box"></div>
</div>
```

#### Joda USE

The `--joda-use` attribute allows the use of a template:

```html
<div class="box" style="--joda-use='box'; --layout-cols: 3"></div>
```

Is equivalent to:

```html
<div class="box" layout="use: box; cols: 3"></div>
```

The template element is copied over the host element, potentially changing the tag.

### Defining Templates

Templates are registered using `Joda.registerTemplate`:
Templates are defined using the `Joda.registerTemplate` method. Here's an example of defining a template:

```typescript
import { Joda } from "@leuffen/jodastyle";
Expand All @@ -58,22 +104,9 @@ Joda.registerTemplate("header1", `
`);
```

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 |
|---------------|--------------------------------------------------|-----------------------------------|
| `data-select` | Selector for the content to replace the slot with | `<slot data-select="img"></slot>` |
| `data-replace`| Indicates that the slot content should be replaced | `<slot data-replace></slot>` |

Slots are replaced in the order they are defined within the template. An element can only be selected once unless the `data-copy` attribute is set. If no `<slot>` element without a `data-select` attribute is found, elements that are not explicitly selected will be removed.

To add classes or wrap a sub-element of a slot into its own template, use the `data-child-class` attribute or the `--joda-wrap` command respectively.

### Using Templates

To apply a template, use the `layout` attribute:
To use a template, apply it using the `layout` attribute:

```html
<div layout="use: #header1">
Expand All @@ -84,47 +117,31 @@ To apply a template, use the `layout` attribute:
</div>
```

It's important to include the `#` symbol when referencing a template to avoid unexpected behavior.
### Processing HTML Input with JodaSplit

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.
JodaSplit reorganizes flat HTML into a structured tree. For detailed information about the structure of the output, refer to the [jodasplit-output.html](/jodasplit/jodasplit-output.html) file.

### Processing HTML Input with JodaSplit
### Responsive Design

JodaSplit reorganizes flat HTML into a structured tree:
Jodaresponsive replaces media queries in CSS files, drastically reducing file sizes. The syntax in the `class` attribute is as follows:

```html
<joda-split>
<nav layout="use: #navbar-switch1" class="floating">
...
</nav>
<h1 layout="use: #header1" data-section-class="decreased-height">Kontakt</h1>
...
</joda-split>
<div class="col :: col-6 :md: col-4 :lg: col-2"></div>
```

JodaSplit transforms the input into a tree structure where `<h1>` and `<h2>` elements become `<section>` elements, while `<h3>` to `<h6>` become nested elements.
Is equivalent to:

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.
```html
<div class="col col-6 col-md-4 col-lg-2"></div>
```

## 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.
The API reference is available in the [index.ts](/index.ts) file, which includes exported functions and classes from the JodaStyle library.

## Configuration

JodaStyle can be configured using `jodaSiteConfig`:
JodaStyle can be configured using `jodaSiteConfig`. For example, to disable the use of templates:

```javascript
import { jodaSiteConfig } from "@leuffen/jodastyle";
Expand All @@ -142,16 +159,7 @@ jodaSiteConfig.debug_visualize = true;

## Contributing

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.
Contributions are welcome! Please refer to the [Contributing](#contributing) section for guidelines on how to contribute to the project.

## License

Expand All @@ -166,11 +174,10 @@ 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.
A: If you encounter unexpected behavior, first ensure that you have followed the documentation correctly. Check for any typos or errors in your code. If the issue persists, enable debugging in `jodaSiteConfig` to get more insights. 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: 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 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.

19 changes: 19 additions & 0 deletions examples/jodaresponsive/jodaresponsive.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
Jodaresponsive ersetzt mediaQuerys in CSS Dateien. z.B. bei Bootstrap. Dadurch kann die Größe der CSS Dateien drastisch reduziert werden.

Die Syntax im class="" Attribut ist wie folgt:

```
class="classe :: <defaultClass> :breakpoint: <alternativeClass>"
```

Beispiel:

```
<div class="col :: col-6 :md: col-4 :lg: col-2">
```

entspricht:

```
<div class="col col-6 col-md-4 col-lg-2">
```
14 changes: 14 additions & 0 deletions examples/jodashorts/jodashorts.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Jodashorts ermöglichen im Text schnell ein HTML Element ohne unterelement anzulgen:

```html
[element attr="" attr2=""]
```

In der Regel genutzt, um Input-Element o.ä. zu erstellen.

```markdown
[input type="submit" class="btn btn-primary" value="Absenden"]
[input type="submit" class="btn btn-primary" value="Absenden"]
```


41 changes: 41 additions & 0 deletions examples/jodastyle/jodastyle.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
Jodastyle ermöglicht die Manipulation des DOM mittels CSS attributen:

Wrap:

```html
<div class=".box"></div>
<div class=".box"></div>
<div class=".box"></div>
```

```css
.box {
--joda-wrap: @row;
}
```

Wrappt die eine oder mehrere aufeinander folgende Element in ein neues Element. Das DOM Ergebnis:

```html
<div class="row">
<div class=".box"></div>
<div class=".box"></div>
<div class=".box"></div>
</div>
```

Joda USE:

Das wohl häufgste Element: --joda-use. Es ermöglicht die nutzung eines Templates. (Intern setzt das layout="use: xyz" Attribut lediglich --joda-use: xzy;)

```html
<div class="box" style="--joda-use='box'; --layout-cols: 3"></div>
```

ist das gleiche wie:

```html
<div class="box" layout="use: box; cols: 3"></div>
```

Beim use wird das das Template Element über das geuste element kopiert. (der Tag ändert sich ggf.)

0 comments on commit 98c5ca6

Please sign in to comment.