Merge pull request #2 from Magento/pubs4009_Vendor

Component Registration Pubs4009_Vendor

Author: tdobbs

common/images/pdg-config-file-structure.png

@@ -2,28 +2,25 @@
 layout: default
 group: Contributor Guide
 subgroup: 
-title: Contribute to Magento DevDocs!
-menu_title: Contribute to Magento DevDocs!
+title: Contribute to Magento DevDocs
+menu_title: Contribute to Magento DevDocs
 menu_order: 100
+github_link: extension-dev-guide/Contribute_edg.md
 
 ---
 
-We encourage our community members to add content; either by writing a full topic, adding new sections to existing topic, or even just adding a few sentences about something you know on an existing topic. Don't worry about perfect grammar or form; just get your brilliance down!!
+We encourage our users to add or correct Magento DevDoc content. Write a full topic, add a new section to an existing topic, or even just add a few sentences about something you know on an existing topic. Don't worry about grammar or form; we can fix that for you!
 
-The files are mostly written in the markdown language (and HTML where needed). 
+Magento Devdocs site content is written in [Markdown](https://daringfireball.net/projects/markdown/), and is kept in Github. If you know how to use Github, you can contribute to our docs.
 
-To get started, review the <a href="{{ site.gdeurl }}contributor-guide/contributing.html">Contributor Guide</a> to learn about the process for code and doc contributions, including how to fork the repository and do a Pull Request to have your work submitted and reviewed.
+Review the Table of Contents in the left pane of the Guide, and determine which topic areas you can contribute to, or any that might be missing.
 
-Then, review the Table of Contents in the left pane of the Guide, and determine which topic areas you can contribute to, or any that might be missing.
-
-To add your knowledge to our Docs, you can:
+To add to Magento Docs:
 
 * edit your local version of an existing file
 * use the <a href="{{ site.githuburl }}template.md">generic template</a> and write a brand new topic, we will find the right home for it in the appropriate Guide.
 * use an existing, empty template to write about a topic that we know we need, but haven't yet gotten around to writing
+* Create a Pull Request to have your contribution reviewed by the DevDocs team. 
 
-
-Create a Pull Request to have your contribution reviewed by the DevDocs team. 
-
-Your contributions to our Docs and your experience with using Magento are very valued and appreciated. Let us know if you have any questions!
+Your contributions to Magento Docs informed by your experience with using Magento are highly valued and appreciated. Let us know if you have any questions!
 

guides/v2.0/extension-dev-guide/Contribute_edg.md

@@ -24,6 +24,7 @@ The following details the module building process:
 
 * [Module file structure](module-file-structure.html)
 * [Define your configuration files](required-configuration-files.html)
+* [Component registration](component-registration.html)
 * [Create your module](create_module.html)
 * [Module load order](module-load-order.html)
 * [Enable your module](enable-module.html)

guides/v2.0/extension-dev-guide/build.md

@@ -0,0 +1,91 @@
+---
+layout: default
+group: extension-dev-guide
+subgroup: 3_Build
+title: Component registration
+menu_title: Component registration
+menu_order: 4
+github_link: extension-dev-guide/composer-integration.md
+redirect_from: /guides/v1.0/extension-dev-guide/composer-integration.html
+
+---
+##{{page.menu_title}}
+
+
+Magento components, including modules, themes, and languages, must be registered in the Magento system through the Magento `ComponentRegistrar` class.
+
+Each component must have a file called `registration.php` in its root directory. For example, here is the `registration.php` file for Magento's [AdminNotification module](https://github.corp.ebay.com/magento2/magento2ce/blob/develop/app/code/Magento/AdminNotification/registration.php). Depending on the type of component, registration is performed through `registration.php` by adding to it as follows:
+
+###Modules
+
+Modules are registered with:
+
+     ComponentRegistrar::register(ComponentRegistrar::MODULE, '<VendorName_ModuleName>', __DIR__);
+
+where &lt;VendorName> is the name of the company providing the module and &lt;ModuleName> is the name of the module.
+     
+#####Example
+     ComponentRegistrar::register(ComponentRegistrar::MODULE, 'Magento_AdminNotification', __DIR__);
+<p>&nbsp;</p>
+
+
+###Themes
+
+Themes are registered with:
+
+     ComponentRegistrar::register(ComponentRegistrar::THEME, '<area>/<vendor>/<theme name>', __DIR__);
+
+where &lt;area> is the functional area of the module (frontend, controller, and so on.), &lt;vendor> is the name of the company providing the theme, and &lt;theme name> is the name of the theme.
+
+
+#####Example
+     ComponentRegistrar::register(ComponentRegistrar::THEME, 'frontend/Magento/luma', __DIR__);
+
+<p>&nbsp;</p>
+
+
+###Languages
+Languages are registered with:
+
+     ComponentRegistrar::register(ComponentRegistrar::LANGUAGE, '<VendorName>_<packageName>', __DIR__);
+
+where &lt;VendorName> is the name of the company providing the package and &lt;packageName> is the name of the package.
+
+#####Example
+     ComponentRegistrar::register(ComponentRegistrar::LANGUAGE, 'magento_de_de', __DIR__);
+
+<p>&nbsp;</p>
+
+###Invoke registration.php in composer.json
+
+After you create your `registration.php` file and you are creating [your module's composer.json file](create_module.html#add-the-module8217s-composerjson-file), remember to invoke your `registration.php` file in the autoload section of `composer.json`:
+
+     {
+    "name": "Acme-vendor/bar-component",
+    "autoload": {
+        "psr-4": { "AcmeVendor\\BarComponent\\": "" },
+        "files": [ "registration.php" ]
+    }
+}
+
+<p>&nbsp;</p>
+
+##Sample registration.php file
+
+{% highlight php startinline=true %}
+    <?php
+/**
+* Copyright © 2015 Magento. All rights reserved.
+* See COPYING.txt for license details.
+*/
+\Magento\Framework\Component\ComponentRegistrar::register(
+  \Magento\Framework\Component\ComponentRegistrar::MODULE,
+  'Magento_AdminNotification',
+  __DIR__
+);
+
+{%endhighlight %}
+
+##Next
+
+[Create a module](create_module.html)

guides/v2.0/extension-dev-guide/component-registration.md

@@ -4,13 +4,15 @@ group: extension-dev-guide
 subgroup: 3_Build
 title: Create a module
 menu_title: Create a module
-menu_order: 4
+menu_order: 5
 github_link: extension-dev-guide/create_module.md
 redirect_from: /guides/v1.0/extension-dev-guide/create_module.html
 ---
 ##{{page.menu_title}}
 
-Now that you have [determined your module’s initial file structure](module-file-structure.html) and have an idea of the [configuration files](required-configuration-files.html) you’ll need, you can create the module.
+Now that you have [determined your module’s initial file structure](module-file-structure.html), have an idea of the [configuration files](required-configuration-files.html) you’ll need, and you've [registered your module](component-registration.html), you can create the module.
+
+
 
 ##Add the module’s `module.xml` file
 Declare the module itself by adding a module.xml file in the `/etc` folder of your module.
@@ -31,7 +33,10 @@ The smallest working module.xml file would look something like this:
 
 
 	{
-    "name": "your-name/module-foobar",
+    "name": "your-name/module-Acme",
+    "autoload": {
+        "psr-4": { "AcmeVendor\\BarComponent\\": "" },
+        "files": [ "registration.php" ],
     "description": "Test module for Magento 2",
     "require": {
         "php": "~5.5.0|~5.6.0",

guides/v2.0/extension-dev-guide/create_module.md

@@ -4,7 +4,7 @@ group: extension-dev-guide
 subgroup: 3_Build
 title: Enable a module
 menu_title: Enable a module
-menu_order: 6
+menu_order: 7
 github_link: extension-dev-guide/enable-module.md
 
 ---

guides/v2.0/extension-dev-guide/enable-module.md

@@ -10,10 +10,14 @@ github_link: extension-dev-guide/module-file-structure.md
 ---
 ##{{page.menu_title}}
 
-Magento 2 looks for the files that make up a module, including configuration files, in particular places. Follow the predefined file structure to ensure that your module works as expected.
+Magento 2 looks for the files that make up a module, including configuration files, in particular places inside the module file structure. Follow the predefined file structure to ensure that your module works as expected.
 
+A module can live anywhere under the Magento root directory. Regardless of where you add it, you must [register the module's location](component-registration.html).
 
-###Magento 2 Module File Structure
+
+
+
+###Magento 2 Module File structure
 
 
 A typical file structure for a Magento 2 module:
@@ -60,7 +64,8 @@ You can add subfolders inside your module folder as you need them (Block, Contro
 
 Or, you could just add them at once:
 
-    mkdir Api && mkdir Block && mkdir Controller && mkdir etc && mkdir Helper && mkdir i18n && mkdir Model && mkdir view
+    mkdir Api Block Controller etc Helper i18n Model view
+
 
 Make sure you add the `etc` folder; it is required, and is where most of the configuration files, including `module.xml`, are kept.
 

guides/v2.0/extension-dev-guide/module-file-structure.md

@@ -4,7 +4,7 @@ group: extension-dev-guide
 subgroup: 3_Build
 title: Module load order
 menu_title: Module load order
-menu_order: 5
+menu_order: 6
 github_link: extension-dev-guide/module-load-order.md
 
 ---

guides/v2.0/extension-dev-guide/module-load-order.md

@@ -17,5 +17,6 @@ Before you start building Magento modules, make sure you’ve got Magento an
 
 * [Install Magento and any required dependencies]({{ site.gdeurl }}/install-gde/bk-install-guide.html)
 * [Composer integration](composer-integration.html)
+* [Component registration](component-resgistration.html)
 * [Set your mode to developer]({{ site.gdeurl }}/config-guide/bootstrap/magento-how-to-set.html)
 <!-- * [Determine your file structure](x) -->

guides/v2.0/extension-dev-guide/prepare.md

@@ -46,18 +46,10 @@ Magento 2 looks for configuration information for each module in that module&#82
 In addition to those files, a Magento 2 module also has nested configuration folders in the `etc` folder for any required administration html, frontend, API REST, or API SOAP specific configuration. Additions you make to files in these folders override the settings in the global configuration files for the respective functionality only. That is, if you add a `config.xml` file to `etc/frontend`, the settings you make in that file overrides the settings in `etc/config.xml` __only for frontend__ functionality.
 
 
-* _YourModule_/etc/adminhtml/
-* _YourModule_/etc/frontend/
-* _YourModule_/etc/webapi_rest/
-* _YourModule_/etc/webapi_soap/
-
-
-If you want to just create the basic set of folders and files in etc that you might need, you could enter the following at the command line:
-
-
-     cd etc 
-
-     mkdir adminhtml && mkdir frontend && mkdir webapi_rest && mkdir webapi_soap && touch acl.xml config.xml di.xml module.xml webapi.xml
+* <YourModule>/etc/adminhtml/
+* <YourModule>/etc/frontend/
+* <YourModule>/etc/webapi_rest/
+* <YourModule>/etc/webapi_soap/
 
 
 
@@ -74,18 +66,18 @@ If you want to just create the basic set of folders and files in etc that you mi
 
 The exact set of configuration files required for your module depends on what your new module does. The required configuration files depend on how you plan to use the module: will the module be manifested on the storefront UI, or in the Magento Admin panel, or as a backend extension that makes a service call? Or all of the above. For example, if your module performs a function in the Admin, you should add any necessary configuration files for those functions to `etc/adminhtml/`, like:
 
-* <code><em>YourModule</em>/etc/adminhtml/di.xml</code>
-* <code><em>YourModule</em>/etc/adminhtml/routes.xml</code>
+* <code>&lt;YourModule>/etc/adminhtml/di.xml</code>
+* <code>&lt;YourModule>/etc/adminhtml/routes.xml</code>
 
 Similarly, if your module changes the UI, you should add the needed configuration files to `~/etc/frontend/`. For example:
 
-* <code><em>YourModule</em>/etc/frontend/.xml</code>
-* <code><em>YourModule</em>/etc/frontend/page_types.xml</code>
+* <code>&lt;YourModule>/etc/frontend/.xml</code>
+* <code>&lt;YourModule>/etc/frontend/page_types.xml</code>
 
 If the module is a service that may call an API, or does some other work that is not manifested in the UI you should add any needed configuration files in the REST and/or SOAP webapi configuration folders, like this:
 
-* <code><em>YourModule</em>/etc/webapi_rest/di.xml</code>
-* <code><em>YourModule</em>/etc/webapi_soap/di.xml</code>
+* <code>&lt;YourModule>/etc/webapi_rest/di.xml</code>
+* <code>&lt;YourModule>/etc/webapi_soap/di.xml</code>
 
 Keep in mind that you may be able to handle your module&#8217;s configuration solely with configuration files at the top level of your module&#8217;s `etc` folder, but the nested folder is a useful way to keep the configuration neatly compartmentalized.
 
@@ -105,6 +97,6 @@ Keep in mind that you may be able to handle your module&#8217;s configuration so
 
 ##Next
 
-[Create a module](create_module.html)
+[Component Registration](component-registration.html)