JCB Packaging Engine Documentation

[Llewellynvdm]

📦 Introduction

The JCB Packaging Engine is a powerful system for exporting, importing, and synchronizing component entities using Git-based repositories. It replaces the legacy ZIP-based packaging approach from Joomla 3 with a modular, repository-centric system that supports collaboration, versioning, and reuse.

This guide walks you through the entire process, from initializing repositories to pushing changes — tailored for both beginners and seasoned JCB developers.

---

🧱 Core Concepts

Entities That Can Be Packaged

You can package and version control the following entities:

• Fields
• Field Types
• Admin Views
• Site Views
• Custom Admin Views
• Components
• Snippets
• Powers (Superpowers)
• Joomla Powers
• Layouts
• Templates
• and more...

Target Contents (Packaging Channels)

To organize packaging logic, entities are grouped into six target content types:

1. Superpowers – PHP classes managed within JCB.
2. Joomla Powers – Links to core Joomla classes/services.
3. Field Types – Templates and logic for building fields.
4. Snippets – Reusable HTML/CSS/JS UI patterns.
5. Packages – All other entities (views, layouts, components).
6. Repositories – Controls repo metadata (for system initialization).

---

🚀 Getting Started with Repositories

Setting Up the Repo Index

To access the global demo repositories:

1. Navigate to Repositories in JCB.

2. Click New and fill in the following:

   • Organization: joomengine
   • Repository: repoindex
   • Read Branch: master
   • Type: GitHub
   • Target Content: repositories
   • Access: global
   • Name: Any descriptive label (e.g., "JoomEngine Repo Index")

3. Click Save & Close.

Initializing the Index

1. While still in the Repositories list, click the Init button.
2. Select the repoindex entry you just created.
3. You'll get a list of repositories — select them all.
4. Click Initialize Selected Repositories.

✔️ This pulls all the core repositories into your JCB environment.

---

📘 Demo Components Included

Once initialized, the following demo components become available:

• Joomla 4 Demo Component
• Joomla 5 Demo Component
• Hello World for Joomla 5
• Recipe Manager for Joomla 5
• E-Health Portal for Joomla 5

These demos showcase various real-world design patterns and advanced usage of JCB.

---

🛠 Button Flow: Init → Reset → Push

Each packagable entity has 3 control buttons:

🔹 Init

• Links an entity to a specific repository.
• Lists available items for import.

🔹 Reset

• Reverts an entity to the latest version from the repository.
• Prioritizes repositories by order unless filtered.
• To force pulling from one repo, unpublish or archive the others temporarily.

🔹 Push

• Sends your local version to the repository.

• Requires:

  • A valid repository entry.
  • Write access and write branch configured.
  • A valid GitHub token (can be global or per-repo override).

Note: JCB will push to all active repositories matching the entity's target content.
To restrict this:

• Unpublish or archive unwanted repositories.
• Or remove the write branch from them.

---

🔐 GitHub Token Setup

To push to GitHub:

Option 1: Global

• Go to JCB Options → GitHub Settings.
• Add your GitHub personal access token.

Option 2: Per-Repository Override

• Edit a repository.
• Toggle Override Global Settings.
• Enter GitHub token and details.

---

📂 Linking & Dependency Resolution

When importing or resetting:

• JCB resolves dependencies (e.g., a field uses a field type, or an admin view belongs to a component).
• Prioritization is based on repo order.

To control which version is used:

• Only publish the desired source repositories.
• Reorder repositories under the same target content.

---

🧰 Developer Workflow Example

Create a New Repository for Your Work

1. Go to Repositories → New.
2. Set target content (e.g., field_types, packages, etc.).
3. Set organization and repo details (GitHub or Gitea).
4. Set read and write branches.
5. Save.

Push Your Entity

1. Go to the entity (e.g., Admin View).
2. Click Push.
3. Confirm push to the active repositories.

✔️ You’ve now contributed your entity to version control.

---

📤 Fork & Pull Request Workflow (For Global Repos)

To contribute to global repositories:

1. Fork the official repo (e.g., joomengine/packages).
2. Make changes in your own fork.
3. Submit a pull request.
4. Optionally open an issue to explain the contribution.

---

⚙️ Tips & Best Practices

• Keep your repositories segmented by content type.
• Use descriptive repo names.
• Use clear system names for each repository.
• Use tokens and branches to fine-tune access and control.
• Always init before push when working on a new project.

---

✅ Conclusion

The JCB Packaging Engine is designed for collaborative development, version control, and simplified sharing of reusable Joomla component structures. It provides a future-proof and modular approach to extension development.

By using Init → Reset → Push along with the right repository setup, you can rapidly scale and share your work within teams, client contexts, and the Joomla community.

---

For more help, visit: https://github.com/joomengine/repoindex

Or join the discussion at: https://github.com/orgs/joomengine/discussions/995