diff --git a/docs/administration/img/bundle_github_structure.png b/docs/administration/img/bundle_github_structure.png new file mode 100644 index 0000000000..36c22584f4 Binary files /dev/null and b/docs/administration/img/bundle_github_structure.png differ diff --git a/docs/administration/img/bundle_github_template.png b/docs/administration/img/bundle_github_template.png new file mode 100644 index 0000000000..5b8cccd779 Binary files /dev/null and b/docs/administration/img/bundle_github_template.png differ diff --git a/docs/administration/img/bundle_page_block.png b/docs/administration/img/bundle_page_block.png new file mode 100644 index 0000000000..afb9399ffa Binary files /dev/null and b/docs/administration/img/bundle_page_block.png differ diff --git a/docs/administration/project_organization/packages_and_bundles/create_bundle.md b/docs/administration/project_organization/bundle_extension/create_bundle.md similarity index 88% rename from docs/administration/project_organization/packages_and_bundles/create_bundle.md rename to docs/administration/project_organization/bundle_extension/create_bundle.md index c15cbc98e4..5d862b6898 100644 --- a/docs/administration/project_organization/packages_and_bundles/create_bundle.md +++ b/docs/administration/project_organization/bundle_extension/create_bundle.md @@ -1,13 +1,12 @@ --- -description: All code contributions to Ibexa DXP must follow package and bundle structure and namespace standards. +description: Create a bundle extension for Ibexa DXP. --- # Create bundle -The following section explains the whole process from creating a bundle from scratch to uploading it on the [packagist.org](https://packagist.org/) website. - -A bundle is modular structure that contain related functionality and can be integrated into an application. -[Follow specific strucutre](package_structure.md/#package-and-bundle-structure-and-namespaces). +A bundle is a reusable [[= product_name =]] extension that can be integrated. +To ensure full compatibility, follow the structure specifications described in the +[package strucutre](package_structure.md/#package-and-bundle-structure-and-namespaces) section. The bundle extension described here is called `AcmeCurrencyExchangeRate` and enables a new page block which displays a currency exchange rate on your site. @@ -70,20 +69,23 @@ php bin/ibexa-bundle-generator currency-exchange-rate currency-exchange-rate-di ## Use GitHub template -https://github.com/ibexa/bundle-template +1\. Go to the [[= product_name_base =]] [GitHub repository](https://github.com/ibexa/bundle-template). + +2\. In the upper-right corner, click the **Use this template** button, and select **Create a new repository**. + +3\. Provide repository name. Optionally, you can add description for the bundle. +Next, click **Create repository**. -Directory structure for AcmeCurrencyExchangeRate -podac url -button use template - - +![GitHub template](bundle_github_template.png) Once the repository is created, a workflow starts which generates a bundle structure. -- Vendor namespace is generated from the orgnization name: github/github user name. + +Vendor namespace is generated from the orgnization name: github/github username. Package and bundle name inherits from repository name. - +![GitHub template](bundle_github_structure.png) + ### Bundle directory structure @@ -122,16 +124,14 @@ Generated bundle consists of the following structure: Where: -- LICENSE - a license file, GPL v2 by default -- README.md - a readme file with bundle description, its version and install instructions +- `LICENSE` - a license file, GPL v2 by default +- `README.md` - a readme file with bundle description, its version and install instructions - `composer.json` - a package definition - `deptrac.yaml` - a tool for static code analysis for PHP, checks the coherence of package architecture, for more information see [deptrac](https://qossmic.github.io/deptrac/) documentation. - `package.json` - frontend dependencies, for more information, see [about packages and modules](https://docs.npmjs.com/about-packages-and-modules). - `phpstan.neon` - phpstan configuration, a tool for static code analysis for PHP, scans, and evaluates codebase to find errors, and bugs, for more information, see the [documentation](https://phpstan.org/user-guide/getting-started). - `phpunit.xml.dist` - config for phpunit, unit and integration tests - see [documentation](https://phpunit.de/getting-started/phpunit-10.html). - src and tests follow the base catalog structure, according to [package structure](https://phpunit.de/getting-started/phpunit-10.html) docs. - To fully use the possibilities of the bundle, get familiar with the structure: @@ -191,7 +191,7 @@ For more information, see [bundles](../../../administration/project_organization !!! note - Make sure you follow naming convention to ensure clarity. + Make sure you follow naming convention to ensure clarity. In the `/src` create a ACMECurrencyExchangeRateBundle class: diff --git a/docs/administration/project_organization/packages_and_bundles/install_package.md b/docs/administration/project_organization/bundle_extension/install_package.md similarity index 86% rename from docs/administration/project_organization/packages_and_bundles/install_package.md rename to docs/administration/project_organization/bundle_extension/install_package.md index f13480cb4c..18c8f5391e 100644 --- a/docs/administration/project_organization/packages_and_bundles/install_package.md +++ b/docs/administration/project_organization/bundle_extension/install_package.md @@ -1,7 +1,9 @@ +--- +description: Install created bundle extension into Ibexa DXP. +--- + # Install bundle   - - ## Add repository to composer To be able to install the bundle to your [[= product_name_base =]] project, first, update the requirements. @@ -33,6 +35,7 @@ Next, add the repository to the `composer.json`: } ``` +## Install bundle into application On your [[= product_name_base =]] root project run:   @@ -71,4 +74,7 @@ The newly installed bundle should be visible in the **Composer** tab in **Admin* ## Add currency exchange page block +Go to Page Builder edit mode. The Currency exchange block should be visible and available in the **Elements** panel. + +![Currency exchange page block](bundle_page_block.png) diff --git a/docs/administration/project_organization/packages_and_bundles/package_structure.md b/docs/administration/project_organization/bundle_extension/package_structure.md similarity index 100% rename from docs/administration/project_organization/packages_and_bundles/package_structure.md rename to docs/administration/project_organization/bundle_extension/package_structure.md diff --git a/docs/administration/project_organization/bundle_extension/upload_packagist.md b/docs/administration/project_organization/bundle_extension/upload_packagist.md new file mode 100644 index 0000000000..b96c758c14 --- /dev/null +++ b/docs/administration/project_organization/bundle_extension/upload_packagist.md @@ -0,0 +1,42 @@ +--- +description: Upload created bundle extension to Packagist. +--- + +# Upload bundle to Packagist + +The following section explains how to upload created bundle on the [packagist.org](https://packagist.org/) website. + +1\. Go to the Packagist website and click **Submit**. + +2\. Provide the repository URL to your package, for example, +`https://github.com/githubusername/example-3rd-party-extension` + + +!!! note + When you add a new feature, you need to create a tag. + + +3\. In PHPStorm or other PHP IntelliJ editor, go to **Commits** -> **Log** and create a new tag. + +4\. Link your bundle repository with Packagist. +Make sure the repository is set to public. +Each time you add a new feature to your bundle, you need to also add a new tag. + +5\. Click the **Check** button to verify the bundle completeness. + +In `composer.json` in the `repositories` indicate the type and bundle URL: + +```json +"repositories": { + "ibexa": { + "type": "composer", + "url": "https://updates.ibexa.co" + }, + "acme/currency-exchange-rate":{ + "type": "vcs", + "url": "https://github.com/githubusername/example-3rd-party-extension" + } + } +``` + +Any change in repository immediately affects the other bundle so you can see the changes. \ No newline at end of file diff --git a/docs/administration/project_organization/packages_and_bundles/upload_packagist.md b/docs/administration/project_organization/packages_and_bundles/upload_packagist.md deleted file mode 100644 index fe2397c55e..0000000000 --- a/docs/administration/project_organization/packages_and_bundles/upload_packagist.md +++ /dev/null @@ -1,29 +0,0 @@ -# Upload bundle to Packagist - -1\. Go to the Packagist website. Click submit. -1\. Provide the repository url to your package. - -1\. When you add a new feature, you need to create a tag. -In PHPStorm or other PHP IntelliJ editor, go to commits, Log and create a new tag. -Then a new version will be published on packagist. - -1\. Link repo with packagist. -Make sure your repository is set to public. -Each time you add a new feature to your bundle, you need to also add a new tag. -New version will be released on Packagist. - -1\. Click the **Check** button to verify the completeness of the bundle. - -In `composer.json` in the repositories - -```json - "repositories": [ - { - "type": "composer", - "url": "https://updates.ibexa.co" - } -``` - -Indicate the type for path -and url - bundle name -Any change in repository immediately affects the other bundle so you can see the changes. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 4548a67578..40043a2e3d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,11 +90,11 @@ nav: - Project organization: administration/project_organization/project_organization.md - Architecture: administration/project_organization/architecture.md - Bundles: administration/project_organization/bundles.md - - Packages and bundles: - - Package structure: administration/project_organization/packages_and_bundles/package_structure.md - - Create bundle: administration/project_organization/packages_and_bundles/create_bundle.md - - Install bundle: administration/project_organization/packages_and_bundles/install_package.md - - Upload on Packagist: administration/project_organization/packages_and_bundles/upload_packagist.md + - Bundle extension: + - Package structure: administration/project_organization/bundle_extension/package_structure.md + - Create bundle: administration/project_organization/bundle_extension/create_bundle.md + - Install bundle: administration/project_organization/bundle_extension/install_package.md + - Upload on Packagist: administration/project_organization/bundle_extension/upload_packagist.md - Admin panel: - Admin panel: administration/admin_panel/admin_panel.md - Users: administration/admin_panel/users_admin_panel.md @@ -761,6 +761,7 @@ nav: - Ibexa DXP PhpStorm plugin: resources/phpstorm_plugin.md - New in documentation: resources/new_in_doc.md - Contributing: + - Report and follow issues: resources/contributing/report_and_follow_issues.md - Contribute translations: resources/contributing/contribute_translations.md - Release notes: diff --git a/plugins.yml b/plugins.yml index 69a6a42af9..8ed53a59cc 100644 --- a/plugins.yml +++ b/plugins.yml @@ -466,7 +466,7 @@ plugins: 'community_resources/phpstorm_plugin.md': 'resources/phpstorm_plugin.md' 'community_resources/report_follow_issues.md': 'resources/contributing/report_and_follow_issues.md' 'community_resources/translations.md': 'resources/contributing/contribute_translations.md' - 'community_resources/package_structure.md': 'resources/contributing/package_structure.md' + 'community_resources/package_structure.md': 'administration/project_organization/bundle_extension/package_structure.md' 'updating/update_ibexa_dxp.md': 'update_and_migration/update_ibexa_dxp.md' 'updating/from_1.x_2.x/update_from_1.x_2.x.md': 'update_and_migration/from_1.x_2.x/update_from_1.x_2.x.md'