Skip to content
Snippets Groups Projects
README.md 7.43 KiB
Newer Older
Volker Schukai's avatar
Volker Schukai committed
# Bob

Volker Schukai's avatar
Volker Schukai committed
Bob is an HTML and HTML fragment builder
Volker Schukai's avatar
Volker Schukai committed

## Documentation
Volker Schukai's avatar
Volker Schukai committed

To check out docs and examples, visit [gitlab.schukai.com/oss/bob](https://gitlab.schukai.com/oss/bob)
Volker Schukai's avatar
Volker Schukai committed

## Installation
Volker Schukai's avatar
Volker Schukai committed

```bash
wget -O ~/.local/bin/bob http://download.schukai.com/tools/bob/bob-$( uname -s | tr [:upper:] [:lower:])-$(echo `uname -m | sed s/aarch64/arm64/ | sed s/x86_64/amd64/`) && chmod u+x ~/.local/bin/bob
```
Volker Schukai's avatar
Volker Schukai committed

Volker Schukai's avatar
Volker Schukai committed
### Nix/Flake Support

Volker Schukai's avatar
Volker Schukai committed
This repository contains a file called flake.nix. You can install this program 
using the [nix package manager](https://nixos.org/).
Volker Schukai's avatar
Volker Schukai committed

## Usage
Volker Schukai's avatar
Volker Schukai committed

### Template

#### Prepare

```bash
bob template prepare --input ./templates/ --output ./output/ --data-file ./data.yaml
This will create files in the `./output/` directory with all parsed templates from `./templates/` directory.
Volker Schukai's avatar
Volker Schukai committed
Also, a data YAML. This data YAML is used to generate the final files with the `bob html generate` command.

This command prepares the title, description, keywords, and other metadata for the templates.
Furthermore, it will parse the templates for images, anchors, and text.
If the argument `--data-file` is not set, the data YAML will be written to `./output/data.yaml`.

| Original                                                                      | Parsed                                                                                                                                          |
|-------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `<html lang="en"><head>`                                                      | `<html lang="en" data-attributes="lang path:lang"><head>`                                                                                       |
| `<title>Bob</title>`                                                          | `<title data-attributes="title path:title">Bob</title>`                                                                                         |
| `<meta name="description" content="Bob is a html and html fragment builder">` | `<meta name="description" content="Bob is a html and html fragment builder" data-attributes="description path:meta.description">`               |
| `<img alt="alt text" title="my title" src="..." `                             | `<img alt="alt text" title="my title" src="..." data-attributes="alt path:img.id1003.alt title path:img.id1003.title src path:img.id1003.src">` |
| `<a href="https://gitlab.schukai.com/oss/bob">`                               | `<a href="https://gitlab.schukai.com/oss/bob" data-attributes="href path:a.id1004.href">`                                                       |
| `<p>Bob is a html and html fragment builder</p>`                              | `<p><span data-attributes="text path:p.id1005.text">Bob is a html and html fragment builder</span></p>`                                         |

Volker Schukai's avatar
Volker Schukai committed
If you want to translate the text, you can copy the default `data.yaml` to a new file and translate the text there.

A good practice is to use the language code as the file name. 
For example, `de.yaml` for German, `en.yaml` for English, etc.

Beside text, images and metadata, special attributes are also extracted.
For example, the Monster datatable headers `data-monster-head` are extracted.

```html
<monster-datatable>
    <template id="datatable-order-list-row">
        <div data-monster-head="OID" ...></a></div>
    ...
``` 

#### HTML

##### Generate
Volker Schukai's avatar
Volker Schukai committed
This will generate HTML files from the prepared templates and data YAML.
Volker Schukai's avatar
Volker Schukai committed
The YAML must be located in the input directory. Any file with `.yaml` extension
will be processed.

Volker Schukai's avatar
Volker Schukai committed
bob html generate --input ./input/ --output ./output/ --data-files ./pages/
Volker Schukai's avatar
Volker Schukai committed
```

Volker Schukai's avatar
Volker Schukai committed
If the `--data-files' attribute is not defined, the `--input' directory is used.
Volker Schukai's avatar
Volker Schukai committed

The yaml looks like:

```yaml
test1.html:
    export: en/test1.html
    lang: en
    title: TEST
    meta:
        author: schukai GmbH
        description: 
    images:
        - id: tickyesdata-image-gi-4013311193
          source: |-
            data:image/gif;base64,R0lGODdhEAAQAMwAAPj7+FmhUYjNfGuxYYDJdYTIeanOpT+DOTuANXi/bGOrWj6CONzv2sPjv2Cm
              V1unU4zPgI/Sg6DJnJ3ImTh8Mtbs00aNP1CZSGy0YqLEn47RgXW8amasW7XWsmmvX2iuXiwAAAAAEAAQAAAFVyAgjmRpnihqGCkpDQ
              PbGkNUOFk6DZqgHCNGg2T4QAQBoIiRSAwBE4VA4FACKgkB5NGReASFZEmxsQ0whPDi9BiACYQAInXhwOUtgCUQoORFCGt/g4QAIQA7
          alt: tick
          title: "yes"
    anchors:
        - id: test-link-test-html
          href: /test.html
          hreflang: ""
          title: test-link
        - id: yes-a-html
          href: /a.html
          hreflang: ""
          title: "Yes"
    text:
        - text: The request was incorrect, the server could not process it.
          id: the-request-was-inco-2640993422
        - text: |-
            If you received this message as a result of a request to the server API, then check the structure
                            against the documentation.
          id: if-you-received-this-423958995
        - text: 'You   can   try    the following steps:'
          id: you-can-try-the-foll-3363859033
    translations:
        - id: translations
          type: application/json
          translations:
            key1: value1
            key2: value2
            key3:
                one: value3
                two: value4
    modifications:
        remove: 
          - .example1
        add: 
          - selector: .example2
            html: <b><span>New Content</span></b>
        attributes: 
          - selector: .example3
            name: data-example
            value: example
Volker Schukai's avatar
Volker Schukai committed
The translations are set in a json inside a script tag.


Volker Schukai's avatar
Volker Schukai committed
The `modifications' rules are executed last. Here you can remove tags, add content and set attributes.
Volker Schukai's avatar
Volker Schukai committed


##### Sync

This will sync HTML nodes from a source to a destination.

```bash
bob html sync --specification ./specification.yaml 
The structure of the specification file is as follows:

```yaml
sync:
  - source:
      path: './source.html'
    destination:
      path: './'
      exclude:
        - ./source.html
With the above specification, the `head` node from `./source.html` will be synced to all files in `./` except `./source.html`.
Furthermore, the `title` node will be kept.
Relative paths are relative to the specification file. Absolute paths are absolute, obviously.

#### Cut

This will cut a node from a source file and save it to a destination template file.

```bash
bob template cut --specification ./specification.yaml 
```

The structure of the specification file is as follows:

```yaml
snippet:
  -
    source: ./test.html
    selector: 'head'
    destination: ./snippets/container.html
    attribute:
      - selector: 'li'
        name: 'class'
        value: 'list-item'
    replacement:
      -
        selector: '#myid'
        content: 'replacement content'
```
Relative paths are relative to the specification file.
Volker Schukai's avatar
Volker Schukai committed

## Questions
Volker Schukai's avatar
Volker Schukai committed

For questions and commercial support, please contact [schukai GmbH](https://www.schukai.com/).
The issue list of this repo is exclusively for bug reports and feature requests.
Volker Schukai's avatar
Volker Schukai committed

## Issues
Volker Schukai's avatar
Volker Schukai committed

Please make sure to read the Issue Reporting Checklist before opening an
issue. Issues not conforming to the guidelines may be closed immediately.
Volker Schukai's avatar
Volker Schukai committed

## License
Volker Schukai's avatar
Volker Schukai committed

© schukai GmbH, released under the AGPL 3.0 License.
Volker Schukai's avatar
Volker Schukai committed

[AGPL](https://www.gnu.org/licenses/agpl-3.0.de.html)
Volker Schukai's avatar
Volker Schukai committed

You can also purchase a commercial license.