DocOps Buttons

1. Introduction

The DocOps Button Extension allows you to create visually appealing and interactive buttons in your AsciiDoctor documents. Buttons are useful for creating navigation elements, call-to-action links, and organizing related resources.

This guide will help you understand the basic concepts of buttons, how to include them in your AsciiDoctor documents, and provide examples of different types of buttons.

2. Basic Concepts

2.1. What are Buttons?

Buttons in the DocOps extension are SVG-based interactive elements that can be included in your AsciiDoctor documents. Each button has:

A label (the text displayed on the button)
A link (the destination URL when clicked)
Optional description text
Optional metadata (type, date, author)
Optional embedded images
Customizable styling

The extension supports multiple button shapes, including:

Regular buttons
Pill-shaped buttons
Rectangle buttons
Round buttons
Circle buttons
Large buttons
Slim buttons
Oval buttons
Hexagonal buttons

Each type can be customized with various colors, gradients, and text styles.

2.2. Button Components

2.2.1. Individual Button Properties

An individual button includes:

label - The text displayed on the button
link - The destination URL when the button is clicked
description (optional) - Additional text describing the button
type (optional) - A category or classification for the button
date (optional) - A date associated with the button
author (optional) - A list of authors associated with the button
embeddedImage (optional) - An image to display on the button
color (optional) - A specific color for the button
Styling properties for customizing appearance

2.2.2. Button Collection Properties

Buttons are typically organized in collections with shared properties:

buttonType - The shape of all buttons in the collection
theme - Shared styling and layout settings including:
colors - A palette of colors for the buttons
columns - The number of columns in the button grid
scale - Size scaling factor
buttonStyle - Text styling for different elements
Shape-specific settings (e.g., hexLinesEnabled for hexagonal buttons)

3. AsciiDoctor Syntax for Buttons

To include buttons in your AsciiDoctor document, you use a special macro syntax. Here’s the basic format:

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Button Label",
      "link": "https://example.com",
      "description": "Button description",
      "type": "category"
    },
    {
      "label": "Another Button",
      "link": "https://example.org",
      "description": "Another description",
      "type": "another-category"
    }
    // More buttons...
  ],
  "buttonType": "REGULAR",
  "theme": {
    "colors": ["#003b6b", "#FF6F36", "#2C7865"],
    "columns": 2,
    "scale": 1.0,
    "buttonStyle": {
      "labelStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 12px; fill: #fcfcfc; font-weight: bold;"
    }
  }
}
----

The macro processes the JSON configuration and generates an SVG representation of the buttons that is embedded in your document.

3.1. Button Properties

3.1.1. Main Button Properties

label (required): The text displayed on the button
link (required): The destination URL when the button is clicked
description (optional): Additional text describing the button
type (optional): A category or classification for the button
date (optional): A date associated with the button (format: "MM/DD/YYYY")
author (optional): An array of authors associated with the button
embeddedImage (optional): An image to display on the button
color (optional): A specific color for the button (overrides theme colors)

3.1.2. Embedded Image Properties

The embeddedImage object has the following properties:

ref (required): The reference to the image, which can be:
A path to an image file (e.g., "images/logo.svg")
A predefined icon reference (e.g., "<Google>", "<Apple>")
type (optional): The MIME type of the image (default: "image/png")

3.1.3. Theme Properties

The theme object can have the following properties:

colors (optional): An array of color hex codes for the buttons
colorTypeMap (optional): A map associating button types with specific colors
scale (optional): A scaling factor for the buttons (default: 1.0)
columns (optional): The number of columns in the button grid (default: 3)
newWin (optional): Whether to open links in a new window (default: false)
useDark (optional): Whether to use dark mode (default: false)
strokeColor (optional): The color of the button borders
sortBy (optional): Configuration for sorting buttons
buttonStyle (optional): Styling for button text elements
hexLinesEnabled (optional): Whether to show connecting lines between hexagonal buttons (default: false)
raise (optional): Whether to apply a raised/3D effect to buttons (default: true)

3.1.4. Button Style Properties

The buttonStyle object can have the following properties:

labelStyle (optional): CSS styling for the button label text
descriptionStyle (optional): CSS styling for the description text
dateStyle (optional): CSS styling for the date text
typeStyle (optional): CSS styling for the type text
authorStyle (optional): CSS styling for the author text
linkStyle (optional): CSS styling for link text
fontSize (optional): Base font size for text elements (default: 12)

3.1.5. Sort Properties

The sortBy object can have the following properties:

sort (optional): The field to sort by ("LABEL", "TYPE", "DATE", "AUTHOR", or "ORDER")
direction (optional): The sort direction ("ASCENDING" or "DESCENDING")

4. Examples

4.1. Regular Buttons Example

Here’s a simple example of regular buttons:

[docops,buttons]
----
{
  "buttons": [
    {
      "link": "https://www.google.com",
      "label": "#[Google]",
      "description": "",
      "type": "search"
    },
    {
      "link": "https://www.apple.com",
      "label": "Apple",
      "description": "",
      "type": "hardware"
    },
    {
      "link": "https://www.microsoft.com",
      "label": "Microsoft",
      "description": "",
      "type": "software"
    },
    {
      "link": "https://www.amazon.com",
      "label": "Amazon",
      "description": "books",
      "type": "books"
    },
    {
      "link": "https://www.netflix.com",
      "label": "Netflix",
      "description": "movies",
      "type": "movies"
    }
  ],
  "buttonType": "REGULAR",
  "theme": {
    "colors": [
      "#003b6b",
      "#FF6F36",
      "#2C7865",
      "#C40C0C",
      "#45618E",
      "#FF5BAE"
    ],
    "strokeColor": "#111111",
    "columns": 2,
    "sortBy": {
      "sort": "ORDER"
    },
    "buttonStyle": {
      "labelStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 12px; fill: #fcfcfc; letter-spacing: normal;font-weight: bold;",
      "dateStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 12px; fill: #000000; letter-spacing: normal;font-weight: normal;",
      "descriptionStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 10px; fill: #fcfcfc; letter-spacing: normal;font-weight: normal;",
      "typeStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 12px; letter-spacing: normal;font-weight: bold; font-style: italic;",
      "authorStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 12px;  fill: #fcfcfc; letter-spacing: normal;font-weight: normal; font-style: italic;"
    },
    "scale": 1.0
  }
}
----

4.2. Pill Buttons Example

You can create pill-shaped buttons by setting the buttonType to "PILL":

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Amazon",
      "link": "https://www.amazon.com",
      "description": "Amazon.com, Inc. is an American multinational technology company which focuses on e-commerce, cloud computing, digital streaming, and artificial intelligence",
      "type": "storefront",
      "date": "",
      "author": [
        "Jeff Bezos"
      ]
    },
    {
      "label": "Apple",
      "link": "https://www.apple.com",
      "description": "Apple Inc. is an American multinational technology company that specializes in consumer electronics, computer software and online services. ",
      "type": "Hardware",
      "date": "01/30/1977",
      "author": [
        "Steve Jobs",
        "Steve Wozniak"
      ]
    },
    {
      "label": "DocOps.io",
      "link": "#[link-server]#[app]",
      "description": "Sharing documentation experience for developers to extend with AsciiDoctor",
      "type": "docs",
      "date": "",
      "author": [
        "Steve Roach",
        "Ian Rose"
      ]
    }
  ],
  "buttonType": "PILL",
  "theme": {
    "colors": [
      "#003b6b",
      "#FF6F36",
      "#2C7865",
      "#C40C0C",
      "#45618E",
      "#FF5BAE"
    ],
    "scale": 0.5,
    "columns": 3,
    "buttonStyle": {
      "labelStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 24px; fill: #fcfcfc; letter-spacing: normal;font-weight: bold;",
      "descriptionStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 10px; fill: #000000; letter-spacing: normal;font-weight: normal;",
      "authorStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 10px; fill: #000000; letter-spacing: normal;font-weight: bold; font-style: italic;",
      "dateStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 12px; fill: #000000; letter-spacing: normal;font-weight: bold; font-style: normal;"
    }
  }
}
----

4.3. Hexagonal Buttons Example

You can create hexagonal buttons with connecting lines by setting the buttonType to "HEX" and enabling hex lines:

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Amazon",
      "link": "https://www.amazon.com",
      "description": "Amazon.com, Inc. is an American multinational technology company which focuses on e-commerce, cloud computing, digital streaming, and artificial intelligence",
      "type": "storefront",
      "date": "",
      "author": [
        "Jeff Bezos"
      ],
      "embeddedImage": {
        "ref": "<Amazon>"
      }
    },
    {
      "label": "Apple",
      "link": "https://www.apple.com",
      "description": "Apple Inc. is an American multinational technology company that specializes in consumer electronics, computer software and online services. ",
      "type": "Hardware",
      "date": "01/30/1977",
      "embeddedImage": {
        "ref": "<Apple>"
      },
      "author": [
        "Steve Jobs",
        "Steve Wozniak"
      ]
    },
    {
      "label": "DocOps.io",
      "link": "#[link-server]#[app]",
      "description": "Sharing documentation experience for developers to extend with AsciiDoctor",
      "type": "docs",
      "embeddedImage": {
        "ref": "images/docops.svg"
      },
      "date": "",
      "author": [
        "Steve Roach",
        "Ian Rose"
      ]
    }
  ],
  "buttonType": "HEX",
  "theme": {
    "hexLinesEnabled": true,
    "strokeColor": "#7695FF",
    "colorTypeMap": {"software": "#058296", "social": "#3a3bf6"},
    "colors": [
      "#353d4b"
    ],
    "scale": 1,
    "columns": 3,
    "buttonStyle": {
      "labelStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 48px; font-weight: 700; font-style: normal; font-variant: small-caps; text-decoration: none;"
    }
  }
}
----

4.4. Buttons with Embedded Images

You can include images in your buttons using the embeddedImage property:

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Google",
      "link": "https://www.google.com",
      "description": "Google is is an American multinational technology company that specializes in Internet-related services and products ",
      "type": "advertisement",
      "date": "07/30/1998",
      "embeddedImage": {
        "ref": "<Google>"
      },
      "author": [
        "Sergey Brin",
        "Larry Page"
      ]
    },
    {
      "label": "Apple",
      "link": "https://www.apple.com",
      "description": "Apple Inc. is an American multinational technology company that specializes in consumer electronics, computer software and online services. ",
      "type": "Hardware",
      "date": "01/30/1977",
      "embeddedImage": {
        "ref": "<Apple>"
      },
      "author": [
        "Steve Jobs",
        "Steve Wozniak"
      ]
    }
  ],
  "buttonType": "CIRCLE",
  "theme": {
    "colors": [
      "#ffffff"
    ],
    "columns": 2,
    "scale": 1.0
  }
}
----

4.5. Buttons with Metadata

You can include additional metadata like dates and authors:

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Google",
      "link": "https://www.google.com",
      "description": "Google is is an American multinational technology company that specializes in Internet-related services and products ",
      "type": "advertisement",
      "date": "07/30/1998",
      "author": [
        "Sergey Brin",
        "Larry Page"
      ]
    },
    {
      "label": "Apple",
      "link": "https://www.apple.com",
      "description": "Apple Inc. is an American multinational technology company that specializes in consumer electronics, computer software and online services. ",
      "type": "Hardware",
      "date": "01/30/1977",
      "author": [
        "Steve Jobs",
        "Steve Wozniak"
      ]
    }
  ],
  "buttonType": "LARGE",
  "theme": {
    "colors": [
      "#003b6b",
      "#FF6F36",
      "#2C7865",
      "#C40C0C",
      "#45618E",
      "#FF5BAE"
    ],
    "buttonStyle": {
      "labelStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 12px; fill: #111111; letter-spacing: normal;font-weight: bold;",
      "descriptionStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 10px; fill: #000000; letter-spacing: normal;font-weight: normal;",
      "authorStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 10px; fill: #000000; letter-spacing: normal;font-weight: bold; font-style: italic;",
      "dateStyle": "font-family: Arial, Helvetica, sans-serif; font-size: 12px; fill: #000000; letter-spacing: normal;font-weight: bold; font-style: normal;"
    }
  }
}
----

5. Button Types

The DocOps Button Extension supports the following button types:

5.1. REGULAR

Standard rectangular buttons with slightly rounded corners.

5.2. PILL

Elongated buttons with fully rounded ends, resembling a pill shape.

5.3. RECTANGLE

Rectangular buttons with sharp corners.

5.4. ROUND

Buttons with significantly rounded corners.

5.5. CIRCLE

Perfectly circular buttons, ideal for icon-based navigation.

5.6. LARGE

Larger rectangular buttons with more space for content.

5.7. SLIM

Thin rectangular buttons for compact layouts.

5.8. OVAL

Elliptical buttons with a distinctive curved shape.

5.9. HEX

Hexagonal buttons that can be connected with lines to form a honeycomb pattern.

6. Advanced Button Examples

6.1. Dark Mode Buttons

You can create buttons with a dark theme by setting the useDark property to true in the theme:

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "GitHub",
      "link": "https://github.com",
      "description": "Source code repository",
      "type": "development",
      "embeddedImage": {
        "ref": "<GitHub>"
      }
    },
    {
      "label": "GitLab",
      "link": "https://gitlab.com",
      "description": "DevOps platform",
      "type": "development",
      "embeddedImage": {
        "ref": "<GitLab>"
      }
    },
    {
      "label": "Bitbucket",
      "link": "https://bitbucket.org",
      "description": "Code collaboration",
      "type": "development",
      "embeddedImage": {
        "ref": "<Bitbucket>"
      }
    }
  ],
  "buttonType": "ROUND",
  "theme": {
    "colors": [
      "#2d333b",
      "#444c56",
      "#373e47"
    ],
    "useDark": true,
    "columns": 3,
    "buttonStyle": {
      "labelStyle": "font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 14px; fill: #adbac7; font-weight: bold;",
      "descriptionStyle": "font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 10px; fill: #768390;"
    }
  }
}
----

Create a social media dashboard with circle buttons and embedded icons:

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Twitter",
      "link": "https://twitter.com",
      "description": "Follow us",
      "type": "social",
      "embeddedImage": {
        "ref": "<Twitter>"
      }
    },
    {
      "label": "Facebook",
      "link": "https://facebook.com",
      "description": "Like our page",
      "type": "social",
      "embeddedImage": {
        "ref": "<Facebook>"
      }
    },
    {
      "label": "Instagram",
      "link": "https://instagram.com",
      "description": "See our photos",
      "type": "social",
      "embeddedImage": {
        "ref": "<Instagram>"
      }
    },
    {
      "label": "LinkedIn",
      "link": "https://linkedin.com",
      "description": "Connect with us",
      "type": "social",
      "embeddedImage": {
        "ref": "<LinkedIn>"
      }
    },
    {
      "label": "YouTube",
      "link": "https://youtube.com",
      "description": "Watch our videos",
      "type": "social",
      "embeddedImage": {
        "ref": "<YouTube>"
      }
    }
  ],
  "buttonType": "CIRCLE",
  "theme": {
    "colors": [
      "#1DA1F2",
      "#4267B2",
      "#E1306C",
      "#0077B5",
      "#FF0000"
    ],
    "colorTypeMap": {
      "social": "#333333"
    },
    "columns": 5,
    "scale": 0.8,
    "buttonStyle": {
      "labelStyle": "font-family: 'Roboto', sans-serif; font-size: 12px; fill: #ffffff; font-weight: bold; text-anchor: middle;",
      "descriptionStyle": "font-family: 'Roboto', sans-serif; font-size: 10px; fill: #ffffff; text-anchor: middle;"
    }
  }
}
----

Create navigation buttons with gradient styling using the PILL button type:

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Home",
      "link": "#home",
      "description": "Main page",
      "type": "navigation"
    },
    {
      "label": "Products",
      "link": "#products",
      "description": "Our offerings",
      "type": "navigation"
    },
    {
      "label": "Services",
      "link": "#services",
      "description": "What we do",
      "type": "navigation"
    },
    {
      "label": "About Us",
      "link": "#about",
      "description": "Our story",
      "type": "navigation"
    },
    {
      "label": "Contact",
      "link": "#contact",
      "description": "Get in touch",
      "type": "navigation"
    }
  ],
  "buttonType": "PILL",
  "theme": {
    "colors": [
      "linear-gradient(135deg, #6e8efb, #a777e3)",
      "linear-gradient(135deg, #05f, #09f)",
      "linear-gradient(135deg, #f83600, #f9d423)",
      "linear-gradient(135deg, #38ef7d, #11998e)",
      "linear-gradient(135deg, #ee0979, #ff6a00)"
    ],
    "columns": 1,
    "scale": 0.7,
    "strokeColor": "#ffffff",
    "buttonStyle": {
      "labelStyle": "font-family: 'Montserrat', sans-serif; font-size: 16px; fill: #ffffff; font-weight: bold;",
      "descriptionStyle": "font-family: 'Montserrat', sans-serif; font-size: 10px; fill: #ffffff; font-style: italic;"
    }
  }
}
----

6.4. Dashboard Hexagonal Buttons

Create an interconnected dashboard using hexagonal buttons:

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Analytics",
      "link": "#analytics",
      "description": "View performance metrics",
      "type": "dashboard",
      "embeddedImage": {
        "ref": "<Chart>"
      }
    },
    {
      "label": "Users",
      "link": "#users",
      "description": "Manage user accounts",
      "type": "dashboard",
      "embeddedImage": {
        "ref": "<User>"
      }
    },
    {
      "label": "Settings",
      "link": "#settings",
      "description": "Configure system",
      "type": "dashboard",
      "embeddedImage": {
        "ref": "<Gear>"
      }
    },
    {
      "label": "Reports",
      "link": "#reports",
      "description": "Generate reports",
      "type": "dashboard",
      "embeddedImage": {
        "ref": "<Document>"
      }
    },
    {
      "label": "Security",
      "link": "#security",
      "description": "Manage permissions",
      "type": "dashboard",
      "embeddedImage": {
        "ref": "<Lock>"
      }
    },
    {
      "label": "Notifications",
      "link": "#notifications",
      "description": "View alerts",
      "type": "dashboard",
      "embeddedImage": {
        "ref": "<Bell>"
      }
    }
  ],
  "buttonType": "HEX",
  "theme": {
    "colors": [
      "#2c3e50"
    ],
    "hexLinesEnabled": true,
    "strokeColor": "#3498db",
    "columns": 3,
    "scale": 0.9,
    "useDark": true,
    "buttonStyle": {
      "labelStyle": "font-family: 'Poppins', sans-serif; font-size: 14px; fill: #ecf0f1; font-weight: bold;",
      "descriptionStyle": "font-family: 'Poppins', sans-serif; font-size: 10px; fill: #bdc3c7;"
    }
  }
}
----

6.5. Timeline-Style Buttons

Create a timeline-like sequence of events using SLIM buttons:

[docops,buttons]
----
{
  "buttons": [
    {
      "label": "Project Start",
      "link": "#phase1",
      "description": "Initial planning",
      "type": "milestone",
      "date": "01/15/2023"
    },
    {
      "label": "Design Phase",
      "link": "#phase2",
      "description": "UI/UX development",
      "type": "milestone",
      "date": "03/01/2023"
    },
    {
      "label": "Development",
      "link": "#phase3",
      "description": "Core functionality",
      "type": "milestone",
      "date": "05/15/2023"
    },
    {
      "label": "Testing",
      "link": "#phase4",
      "description": "QA and bug fixes",
      "type": "milestone",
      "date": "07/30/2023"
    },
    {
      "label": "Launch",
      "link": "#phase5",
      "description": "Public release",
      "type": "milestone",
      "date": "09/15/2023"
    }
  ],
  "buttonType": "SLIM",
  "theme": {
    "colors": [
      "#8e44ad",
      "#9b59b6",
      "#2980b9",
      "#3498db",
      "#16a085"
    ],
    "columns": 1,
    "scale": 1.0,
    "sortBy": {
      "sort": "DATE",
      "direction": "ASCENDING"
    },
    "buttonStyle": {
      "labelStyle": "font-family: 'Open Sans', sans-serif; font-size: 14px; fill: #ffffff; font-weight: bold;",
      "descriptionStyle": "font-family: 'Open Sans', sans-serif; font-size: 10px; fill: #ffffff;",
      "dateStyle": "font-family: 'Open Sans', sans-serif; font-size: 12px; fill: #ffffff; font-weight: bold;"
    }
  }
}
----

7. Conclusion

The DocOps Button Extension provides a powerful way to enhance your AsciiDoctor documents with visually appealing and interactive buttons. By using the JSON configuration format, you can create customized buttons that match your document’s style and purpose.

The extension supports various button shapes, embedded images, metadata, and styling options, allowing for a wide range of design possibilities.