Bob

Bob is an HTML and HTML fragment builder

Documentation

To check out docs and examples, visit gitlab.schukai.com/oss/bob

Installation

First, clone this repository. Then change into the source directory and build the project.

git clone https://gitlab.schukai.com/oss/bob.git
cd bob/source
go build

Nix/Flake Support

This repository contains a file called flake.nix. You can install this program using the nix package manager.

nix build 

Devenv.nix

If you have devenv.nix in use, you can add bob to the devenv.yaml.

inputs:
  nixpkgs:
    url: github:nixos/nixpkgs/nixos-23.11

  bob:
    url: git+https://gitlab.schukai.com/oss/bob.git
    flake: true

In the devenv.nix file, you must then add bob under packages.

packages = [
   inputs.bob.packages."${builtins.currentSystem}".default
];

Usage

Template

Prepare

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.

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.

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

If you want to add Javascript translations, a consecutive ID is assigned if not specified separately. This is not ideal for several reasons. It is better to assign your own ID. To be independent of HTML, JavaScript and CSS selectors, there is a separate attribute data-bob-reference for this.

<script type="application/json"
        data-monster-role="translations"
        data-bob-reference="my-translation">
{
     "key1": "value1",
     "key2": "value2",
     "key3": {
          "one": "value3",
          "two": "value4"
     }
}

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.

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:

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.

bob html sync --specification ./specification.yaml

The structure of the specification file is as follows:

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.

bob template cut --specification ./specification.yaml

The structure of the specification file is as follows:

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.

Contributing

The bob command line tool is written in Go. The environment is defined in the flake.nix file.

If you want to build the project, you can use the nix build or use the task build.

task build

To update the version and get the vendor hash, the task task update-code must be called.

The hash is currently always null, as a vendor directory is used in the project. This is created with go mod vendor.

Questions

For questions and commercial support, please contact schukai GmbH. 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

You can also purchase a commercial license.