# Bob

Bob is an HTML and HTML fragment builder

## Documentation

To check out docs and examples, visit [gitlab.schukai.com/oss/bob](https://gitlab.schukai.com/oss/bob)

## Installation

```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
```

### Nix/Flake Support

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

## Usage

### 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.
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>`                                         |

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

This will generate HTML files from the prepared templates and data YAML.
The YAML must be located in the input directory. Any file with `.yaml` extension
will be processed.


```bash
bob html generate --input ./input/ --output ./output/ --data-files ./pages/
```

If the `--data-files' attribute is not defined, the `--input' directory is used.

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
```

The translations are set in a json inside a script tag.


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


##### 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'
      selector: 'head'
    destination:
      path: './'
      exclude:
        - ./source.html
      keep:
        - title
```

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.


## Questions

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.

## Issues

Please make sure to read the Issue Reporting Checklist before opening an
issue. Issues not conforming to the guidelines may be closed immediately.

## License

© schukai GmbH, released under the AGPL 3.0 License.

[AGPL](https://www.gnu.org/licenses/agpl-3.0.de.html)

You can also purchase a commercial license.