-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Magento module README.md
Magento is a modular system and any external developer would like to have at least a short overview of each module explaining the module's functionality and details that the developer should know about it.
This article contains recommendations for Magento contributors about typical README.md content.
Each README.md will be published in Module Reference Guide (MRG) without changes. The Documentation team uses Markdown-based software to generate the documentation website, which is why special formatting must be followed (headings, lists, etc).
Each Magento module must contain README.md.
Each README must follow the formatting described in this article.
Each README must contain the informational structure described in this article.
Heading 1 shows the name of the module.
# Magento_ConfigurableProductStaging module
Para #1. Add a short description of a module's purpose.
The Magento_ConfigurableProductStaging module enables you to add the Configurable Product updates to the existing store campaigns.
Para #2. Add short description of features that the module adds to Magento.
The Magento_ConfigurableProductStaging module is a part of the staging functionality in Commerce. The module adds the “Configurations” tab and the configuration wizard to the Schedule Update form of a product. You can change the Configurable Product attributes in campaigns. These updates are shown on the campaign dashboard.
Describe important installation or uninstallation details that an external developer should be aware of.
If there is nothing to tell about, skip this section.
## Installation details
The Magento_ConfigurableProductStaging module makes irreversible changes in a database during installation. You cannot disable or uninstall this module.
For information about a module installation, see [Enable or disable modules](https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/tutorials/manage-modules.html).
Describe components that are not typical for a Magento module, if available.
Add a link to developer documentation describing the typical file structure of a module.
If there is nothing to tell about, skip this section.
## Structure
`Customers/` - the directory that declares Customers' metadata used by the module.
For information about a typical file structure of a module in Magento 2, see [Module file structure](https://developer.adobe.com/commerce/php/development/build/component-file-structure/#module-file-structure).
Describe extension points of the module and add links to the corresponding documentation.
If there is nothing to tell about, skip this section.
## Extensibility
Extension developers can interact with the Magento_ConfigurableProductStaging module. For more information about the Magento extension mechanism, see [Magento plug-ins](https://developer.adobe.com/commerce/php/development/components/plugins/).
[The Magento dependency injection mechanism](https://developer.adobe.com/commerce/php/development/components/plugins/) enables you to override the functionality of the Magento_ConfigurableProductStaging module.
Add a list of events dispatched by the module.
If there is nothing to tell about, skip this section.
### Events
The module dispatches the following events:
- `catalog_category_prepare_save` event in the `\Magento\CatalogStaging\Model\Category\Hydrator::hydrate()` method. Parameters:
- `category` is a category to be saved (`\Magento\Catalog\Model\Category` class).
- `request` is a request object with the `\Magento\Framework\App\RequestInterface` interface.
- `controller_action_catalog_product_save_entity_after` event in the `\Magento\CatalogStaging\Model\Product\Hydrator::hydrate()` method. Parameters:
- `controller` is a hydrator object (`\Magento\CatalogStaging\Model\Product\Hydrator`).
- `product` is a product object (`\Magento\Catalog\Model\Product` class.
For information about an event in Magento 2, see [Events and observers](https://developer.adobe.com/commerce/php/development/components/events-and-observers/#events).
Tell whether the module introduces layouts or layout handles, and where to find them in the module.
If the module introduces a basic layout handle that includes many layout handles, add its module relative path with a short description of a basic layout handle.
If there is nothing to tell about, skip this section.
### Layouts
The module introduces layout handles in the `view/adminhtml/layout` directory.
For more information about a layout in Magento 2, see the [Layout documentation](https://developer.adobe.com/commerce/frontend-core/guide/layouts/).
Tell whether the module introduces UI components or the configuration files, and where to find them in the module.
If there is nothing to tell about, skip this section.
### UI components
You can extend product and category updates using the configuration files located in the `view/adminhtml/ui_component` directory.
For information about a UI component in Magento 2, see [Overview of UI components](https://developer.adobe.com/commerce/frontend-core/ui-components/).
If the module introduces public API, describe what services are introduced.
If there is nothing to tell about, skip this section.
### Public APIs
`\Magento\Sales\Api\InvoiceOrderInterface`:
- create an invoice document (full or partial)
- capture money placed with order payment
- notify a customer about document creation
- change order status and state
`\Magento\Sales\Api\RefundInvoiceInterface`:
- create a Credit Memo (complete or partial) for a particular Invoice
- add details about refunded items to an Order
- change the status and state of an Order according to performed actions
- notify a customer about performed refund operation
`\Magento\Sales\Api\RefundOrderInterface`:
- create a Credit Memo (complete or partial) for a particular Order
- add details about refunded items to an Order
- change the status and state of an Order according to performed actions
- notify a customer about performed refund operation
`\Magento\Sales\Api\ShipOrderInterface`:
- create a shipment document (full or partial)
- add details about shipped items into an order
- change the status and state of an order according to performed actions
- notify the customer of a new shipment document
[Learn a detailed description of the Magento_Sales API.](https://developer.adobe.com/commerce/php/module-reference/module-sales/)
For information about a public API in Magento 2, see [Public interfaces & APIs](https://developer.adobe.com/commerce/php/development/components/api-concepts/).
Add any important details that cannot be added to previous sections.
If there is nothing to tell about, skip this section.
## Additional information
For information about significant changes in patch releases, see [Release information](https://experienceleague.adobe.com/docs/commerce-operations/release/notes/overview.html).
### cron options
cron group configuration can be set in `etc/crontab.xml`.
- `staging_apply_version` – each period of time checks in a table of updates if any [campaign](#campaign) has been started and if yes, it applies all [scheduled updates](#scheduled-update) for the campaign.
- `staging_remove_updates` – each period of time checks if a campaign contains any update, and if it is empty, deletes the campaign.
- `staging_synchronize_entities_period` – each period of time checks if the start or end dates of a campaign have been changed. If it finds any changes, it applies the same changes to all updates dependent on the campaign.
[Learn how to configure and run cron in Magento.](https://experienceleague.adobe.com/docs/commerce-operations/configuration-guide/cli/configure-cron-jobs.html)
### Indexes and indexing modes
When an update is applied, the indexer handles it according to the actual indexing mode. In a preview mode, indexing is not applied. Data is loaded for the open page only.
[Learn more about indexing in Magento.](https://developer.adobe.com/commerce/php/development/components/indexing/)
### Data migration
The Magento_Staging module uses the `\Magento\Staging\Setup\BasicSetup` class during installation. This class changes the database schema and migrates data.
#### Migration of attributes with a range
Each update attribute that contains a time range is synchronized with the dates of the campaign. Attributes with time range are removed from the UI.
The following example is a complete README for a module:
# Magento_ConfigurableProductStaging module
The Magento_ConfigurableProductStaging module enables you to add the Configurable Product updates to the existing store campaigns.
The Magento_ConfigurableProductStaging module is a part of the staging functionality in Magento EE. The module adds the “Configurations” tab and the configuration wizard to the Schedule Update form of a product. You can change the Configurable Product attributes in campaigns. These updates are shown on the campaign dashboard.
## Installation details
The Magento_ConfigurableProductStaging module makes irreversible changes in a database during installation. You cannot disable or uninstall this module.
For information about a module installation in Magento 2, see [Enable or disable modules](https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/tutorials/manage-modules.html).
## Extensibility
Extension developers can interact with the Magento_ConfigurableProductStaging module. For more information about the Magento extension mechanism, see [Magento plug-ins](https://developer.adobe.com/commerce/php/development/components/plugins/).
[The Magento dependency injection mechanism](https://developer.adobe.com/commerce/php/development/components/dependency-injection/) enables you to override the functionality of the Magento_ConfigurableProductStaging module.
### Layouts
The module introduces layout handles in the `view/adminhtml/layout` directory.
For more information about a layout in Magento 2, see the [Layout documentation](https://developer.adobe.com/commerce/frontend-core/guide/layouts/).
### UI components
You can extend product and category updates using the UI components located in the `view/adminhtml/ui_component` directory.
For information about a UI component in Magento 2, see [Overview of UI components](https://developer.adobe.com/commerce/frontend-core/ui-components/).
## Additional information
For information about significant changes in patch releases, see [Release information](https://experienceleague.adobe.com/docs/commerce-operations/release/notes/overview.html).
### Events
You can use the following events:
- `catalog_category_prepare_save` event in the `\Magento\CatalogStaging\Model\Category\Hydrator::hydrate()` method. Parameters:
- `category` is a category to be saved (`\Magento\Catalog\Model\Category` class).
- `request` is a request object with the `\Magento\Framework\App\RequestInterface` interface.
- `controller_action_catalog_product_save_entity_after` event in the `\Magento\CatalogStaging\Model\Product\Hydrator::hydrate()` method. Parameters:
- `controller` is a hydrator object (`\Magento\CatalogStaging\Model\Product\Hydrator`).
- `product` is a product object (`\Magento\Catalog\Model\Product` class.