From 98c5ca65b38aa9c508c62d7db54ecbfb68c4309a Mon Sep 17 00:00:00 2001 From: Matthias Leuffen Date: Sat, 25 Nov 2023 03:59:45 +0100 Subject: [PATCH] update --- README.md | 125 +++++++++++---------- examples/jodaresponsive/jodaresponsive.txt | 19 ++++ examples/jodashorts/jodashorts.txt | 14 +++ examples/jodastyle/jodastyle.txt | 41 +++++++ 4 files changed, 140 insertions(+), 59 deletions(-) create mode 100644 examples/jodaresponsive/jodaresponsive.txt create mode 100644 examples/jodashorts/jodashorts.txt create mode 100644 examples/jodastyle/jodastyle.txt diff --git a/README.md b/README.md index 547285f..789fbeb 100755 --- a/README.md +++ b/README.md @@ -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) @@ -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 - - +```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 +
+
+
+``` + +```css +.box { + --joda-wrap: @row; +} +``` + +The resulting DOM: + +```html +
+
+
+
+
+``` + +#### Joda USE + +The `--joda-use` attribute allows the use of a template: + +```html +
+``` + +Is equivalent to: + +```html +
+``` + +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"; @@ -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 `` 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 | `` | -| `data-replace`| Indicates that the slot content should be replaced | `` | - -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 `` 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
@@ -84,47 +117,31 @@ To apply a template, use the `layout` attribute:
``` -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 - - -

Kontakt

- ... - +
``` -JodaSplit transforms the input into a tree structure where `

` and `

` elements become `
` elements, while `

` to `

` become nested elements. +Is equivalent to: -You can use `
` 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 +
+``` ## 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"; @@ -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 @@ -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. - diff --git a/examples/jodaresponsive/jodaresponsive.txt b/examples/jodaresponsive/jodaresponsive.txt new file mode 100644 index 0000000..76766a1 --- /dev/null +++ b/examples/jodaresponsive/jodaresponsive.txt @@ -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 :: :breakpoint: " +``` + +Beispiel: + +``` +
+``` + +entspricht: + +``` +
+``` diff --git a/examples/jodashorts/jodashorts.txt b/examples/jodashorts/jodashorts.txt new file mode 100644 index 0000000..4ee58de --- /dev/null +++ b/examples/jodashorts/jodashorts.txt @@ -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"] +``` + + diff --git a/examples/jodastyle/jodastyle.txt b/examples/jodastyle/jodastyle.txt new file mode 100644 index 0000000..1f67ea2 --- /dev/null +++ b/examples/jodastyle/jodastyle.txt @@ -0,0 +1,41 @@ +Jodastyle ermöglicht die Manipulation des DOM mittels CSS attributen: + +Wrap: + +```html +
+
+
+``` + +```css +.box { + --joda-wrap: @row; +} +``` + +Wrappt die eine oder mehrere aufeinander folgende Element in ein neues Element. Das DOM Ergebnis: + +```html +
+
+
+
+
+``` + +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 +
+``` + +ist das gleiche wie: + +```html +
+``` + +Beim use wird das das Template Element über das geuste element kopiert. (der Tag ändert sich ggf.)