Knowledge Base (public)

Ukázka jednoduchého zásahu do designu:

V administraci addons máme Forge custom addon:

Níže je kompletní postup, jak dostat vlastní Forge addon s menu do tvého Confluence:

1. Připrava prostředí

Nainstaluj Node.js (doporučovaná verze 18 LTS nebo 20 LTS)
- https://nodejs.org
Nainstaluj Forge CLI (globálně)
V terminálu/spouštěcím okně:
```
npm install -g @forge/cli
```
Přihlas se do Atlassian pomocí účtu (stejného, kterým chodíš na dev site)
```
forge login
```
Otevře se prohlížeč, přihlásíš se, potvrdíš přístup.

2. Vytvoření nové Forge aplikace

V terminálu si vytvoř složku pro appku:


mkdir design-menu-forge
cd design-menu-forge

Spusť generátor Forge aplikace:
```
forge create
```
Odpovědi při vytváření:
- vyber typ: Confluence
- šablonu: např. Custom UI (Hello world) nebo nějakou simple Confluence šablonu
  (nevadí, že to není přesně byline item – manifest si ručně upravíme).
Po dovytvoření budeš mít projekt s manifest.yml a složkou static/… (Custom UI).

3. Úprava manifestu – přidání byline modulu

Otevři manifest.yml a nahraď (nebo doplň) obsah např. tímto:


modules:
  confluence:contentBylineItem:
    - key: confluence-design
      title: Confluence design
      resource: menu-ui
      resolver:
        function: handler

resources:
  - key: menu-ui
    path: static/menu-ui/build
    tunnel:
      port: 3000

function:
  - key: handler
    handler: index.handler

app:
  id: # will be filled by `forge register`
  runtime:
    name: nodejs24.x

permissions:
  scopes:
    - read:confluence-space.summary
    - read:confluence-content.summary

Space key zjistíš tak, že otevřeš jakoukoli stránku ze space Design a podíváš se do URL – např. .../wiki/spaces/Design/overview → key je Design.

4. Jednoduchý backend resolver (index.js)

V kořeni projektu (nebo podle šablony) uprav/src/index.js:


export const handler = async (request) => {
  // Pokud zatím nic nepotřebuješ z backendu, můžeš vrátit prázdný objekt
  return {
    body: JSON.stringify({ ok: true }),
  };
};

5. Frontend – jednoduché horizontální menu

Najdi složku s Custom UI (např. static/menu-ui/src/App.js)
a uprav ji zhruba takto:


import React, { useEffect, useState } from 'react';
import { view, router } from '@forge/bridge';

const App = () => {
  const [context, setContext] = useState(null);

  useEffect(() => {
    (async () => {
      const ctx = await view.getContext();
      setContext(ctx);
    })();
  }, []);

  if (!context) {
    return null;
  }

  const extension = context.extension || {};
  const spaceKey = extension.space?.key;
  const extensionType = extension.type; // 'contentBylineItem' nebo 'contentMacro'

  // zobrazovat jen ve space "Design"
  if (spaceKey !== 'Design') {
    return null;
  }

  const menuItems = [
    {
      label: 'Přehled',
      href: `/wiki/spaces/${spaceKey}/overview`,
    },
    {
      label: 'Page 1',
      href: `/wiki/spaces/${spaceKey}/pages/313065478/Page+1`,
    },
    {
      label: 'Page 11',
      href: `/wiki/spaces/${spaceKey}/pages/312836120/Page+11`,
    },
  ];

  const handleClick = (href) => {
    router.navigate(href);
  };

  const isByline = extensionType === 'contentBylineItem';
  const containerStyle = {
    display: 'flex',
    gap: '16px',
    borderBottom: isByline ? '1px solid #DFE1E6' : 'none',
    padding: isByline ? '8px 0 12px 0' : '4px 0 4px 0',
    fontSize: '14px',
  };

  return (
    <div style={containerStyle}>
      {menuItems.map((item) => (
        <button
          key={item.label}
          onClick={() => handleClick(item.href)}
          style={{
            border: 'none',
            background: 'none',
            padding: 0,
            margin: 0,
            cursor: 'pointer',
            textDecoration: 'none',
            color: '#0052CC',
            fontWeight: 500,
          }}
        >
          {item.label}
        </button>
      ))}
    </div>
  );
};

export default App;

Teď máš appku připravenou k nasazení.

6. Registrace a první deploy Forge app (ještě není instalováno)

V kořeni projektu:


# 1) Registrace aplikace (jen jednou na začátku)
forge register


# 2) Build UI
cd static/menu-ui
npm install        # pokud jsi ještě v UI neinstaloval závislosti
npm run build
cd ../..


# 3) Deploy backend + frontend do cloudu
forge deploy


# 4) Instalace appky do Confluence site
forge install --product confluence --site onlioaps-demo.atlassian.net

7. Běžný update (appka už je nainstalovaná)

Stačí zbuildit UI a znovu nasadit


# v kořeni projektu

cd static/menu-ui
npm run build
cd ../..

forge deploy

Tohle:

znovu zbuildí frontend,
nahraje změny backendu + frontendu do Cloudu,
není potřeba znovu instalovat, pokud:
- neměníš product,
- neměníš site,
- ani app.id.

8. Update se změnami manifestu


cd static/menu-ui
npm run build
cd ../..

forge deploy

forge install --upgrade --product confluence --site onlioaps-demo.atlassian.net

To:

provede nový deploy,
a aktualizuje už nainstalovanou appku na dané site

Pro rychlý vývoj

můžeš použít:


forge tunnel

Ten ti umožní vidět změny v UI v reálném čase (Custom UI běží lokálně na portu 3000).