🔗 Custom Links – Nextcloud App

Add custom navigation links with SVG icons directly to the Nextcloud main menu.

---

📦 Overview

Custom Links is a lightweight Nextcloud app that allows administrators to add external or internal links to the main navigation menu.

Each link can include:

• ✅ A custom caption
• ✅ A descriptive tooltip
• ✅ A custom SVG icon
• ✅ A configurable target (_self or _blank)

Perfect for integrating external tools such as:

• CRM systems
• Webmail
• Intranet
• Admin dashboards
• E-commerce back office
• Documentation portals

---

✅ Compatibility

Component	Version
Nextcloud	≥ 32 and ≤ 33
License	AGPL
Version	1.0.0

---

🚀 Installation

1️⃣ Copy the app

Place the app inside your Nextcloud apps/ directory:

nextcloud/apps/customlinks

2️⃣ Enable the app

From the Nextcloud admin interface:

Apps → Disabled apps → Custom Links → Enable

Or via CLI:

php occ app:enable customlinks

---

⚙️ Configuration

All links are defined in:

customlinks/config/links.json

Example configuration

[
    {
        "id": "manager",
        "caption": "Manager",
        "title": "gestion CRM, abo, stats, etc",
        "url": "https://manager.example.com",
        "target": "_blank"
    }
]

---

🧩 Configuration Options

Field	Required	Description
id	✅	Unique identifier (also used for the SVG icon filename)
caption	✅	Text shown in the navigation menu
title	❌	Tooltip text (hover description)
url	✅	Destination URL
target	❌	_self (default) or _blank

---

🎨 Adding Icons

Each link requires an SVG icon.

Icons must be placed in:

customlinks/img/

The filename must match the id value:

Example:

If:

"id": "manager"

Then the icon must be:

img/manager.svg

✅ Only SVG format is supported.

---

🏗 How It Works

At runtime:

1. The app loads config/links.json
2. Each entry is registered with INavigationManager
3. Icons are resolved using IURLGenerator
4. Links appear in the main Nextcloud navigation menu

Internally:

$navManager->add(function () {
    return [
        'id' => 'customlinks_<id>',
        'order' => 50,
        'href' => '<url>',
        'icon' => '<svg path>',
        'target' => '_blank',
        'name' => '<caption>',
        'title' => '<tooltip>'
    ];
});

---

📂 Project Structure

customlinks/
│
├── appinfo/
│   └── info.xml
│
├── config/
│   └── links.json
│
├── img/
│   └── *.svg
│
├── lib/
│   └── AppInfo/
│       └── Application.php
│
└── css/
    └── customlinks.css

---

🛠 Example Use Case

For a coworking space setup:

[
    {
        "id": "manager",
        "caption": "Manager",
        "title": "CRM & statistics",
        "url": "https://manager.coworking-metz.fr",
        "target": "_blank"
    },
    {
        "id": "mail",
        "caption": "Mail",
        "title": "Association emails",
        "url": "https://email.coworking-metz.fr",
        "target": "_blank"
    },
    {
        "id": "shop",
        "caption": "Orders",
        "title": "Today's orders",
        "url": "https://www.example.com/wp-admin/",
        "target": "_blank"
    }
]

This will generate three new menu entries in Nextcloud.

---

🔐 Security Considerations

• Only administrators should modify links.json
• Ensure external links use HTTPS
• SVG icons should be sanitized and trusted

---

🎯 Customization

Change menu order

Edit in Application.php:

'order' => 50,

Lower number = higher position in menu.

---

🧪 Troubleshooting

Problem	Solution
Link does not appear	Check JSON syntax validity
Icon missing	Ensure SVG filename matches id
App not visible	Confirm compatibility with Nextcloud 32–33
Changes not applied	Clear cache or reload page

---

📌 Notes

• The app reads the JSON file at runtime.
• No database entries are created.
• No user-specific settings (global configuration only).

---

🧑‍💻 Author

Your Name

---

📜 License

AGPL v3

---

⭐ Why Use This App?

✔ Simple
✔ Lightweight
✔ No database
✔ Fully customizable
✔ Perfect for organizations integrating multiple tools