magento/devdocs

Magento Developer Documentation

devdocs's Issues

deploy:mode changed to setup:mode

Should be changed according to https://github.com/magento/magento2/blob/6ba36cff388d71e8031a144d45158ce896dd44cb/app/code/Magento/Deploy/README.md

Discovered by http://magento.stackexchange.com/questions/82166/clear-theme-css-cache-in-magento-2/82168#82168

Registration.php is not mentioned in theme documentation

I am working on my first magento 2 theme. I created all the required files defined by the documentation, but my theme did not show up under "Content => Design => Themes".

Using the luma theme as an example I created a registration.php file in the root of my theme. Now it shows up in the config.

Is this a temporary solution or is it just missing in the documentation?

Missing area from "Modules and Areas"

In /guides/v1.0/architecture/modules/mod_and_areas.md, it mentions that "In Magento there are six Areas". However it only lists 5 areas? I presume the missing one is "crontab"?

Although this is at odds as to what is stated about areas on /develop/guides/v1.0/architecture/areas/areas.md, this mentions "install" as an area, but mod_and_areas.md has "doc"?!

There is no documentation available for Source Models, Backend Models, and Frontend Models

It would be great if there was documentation on what Source Models, Backend Models, and Frontend Models existed within default Magento. I imagine this could be updated either manually or via a script by searching for classes that are not abstract and that implement the appropriate interface. I expect that this would be the case for more than just these models including things like models available through the service layer.

ServiceContracts DesignPatterns: Data now Mutable

In the Service Contracts sub page about Design Patterns there are references to Data Interfaces/Objects being immutable but the codebase and strategy has changed to allow for mutable Data. References to immutability and to builders need to be removed.

Incorrect Gist examples for "RSS feed assets" on "Introduction to page assets" page

The Gist examples on /guides/v1.0/architecture/view/page-assets.md for "RSS feed assets" are wrong, it is incorrectly repeating the "CSS assets" example.

New Issue

test

Old Dev Docs URLs in Search Engine

Today I was searching for some Magento 2 information -- and Google returned a result with the following URL

http://devdocs.magento.com/guides/v1.0/config-guide/config/plugins.html

However, this URL returned a 404. If the old versions of docs aren't going to stick around, there old URLs should redirect (301, permanent) to the current equivalent document, or an appropriate page if the old URLs are going away.

The <action> instruction is deprecated

There is an alert saying "The <action> instruction is deprecated. Do not use it." on the layout XML instructions page:
http://devdocs.magento.com/guides/v1.0/frontend-dev-guide/layouts/xml-instructions.html#fedg_layout_xml-instruc_ex_act

Why is that and is it possible to accomplish that another way?

I found another use example on this page:
http://devdocs.magento.com/guides/v1.0/frontend-dev-guide/layouts/xml-manage.html#layout_markup_block-properties

Slider for Magento 2

Hi,

I don't see ideas about Slider for Magento 2. For example, Javascript lib should be used and how to create an example slider. Any idea about my point? If I can, I will contribute to this point.

Thanks!

Incorrect gist in indexing guide

A gist intended to show an example of Merchandising/etc/indexer.xml is embedded on line 267 in /guides/v1.0/architecture/index-cache/indexing.md.

This is incorrectly displaying a duplicate example of the Merchandising/etc/mview.xml.

Struggling to contribute to the contribution guide.

The link to github ("Edit this page on GitHub") on http://devdocs.magento.com/guides/v1.0/contributor-guide/CONTRIBUTING.html / https://github.com/magento/devdocs/blob/master/guides/v1.0/contributor-guide/CONTRIBUTING.md is incorrect.

Rather than just fix it in a pull request I figured it's best to just raise an issue as the best fix may be to rename the file as it looks inconstant with a fully uppercase name.

Layout broken on /guides/v1.0/architecture/view/page-type.html

This page looks ok in Github, but at http://devdocs.magento.com/guides/v1.0/architecture/view/page-type.html the page layout is broken. It looks like this is due to line 25 where "<ModuleName>" is not escaped.

I didn't want to do a pull request as I cannot definitively test the change and see if it fixes the problem, reason being that http://devdocs.magento.com is converting the markdown and I cannot replicate that. Unless there is some way?

Static file creation tool table displayed in wrong position

In the Running the static file creation tool section the table is not displayed on the intended poisition but at the end of the page.

Additionally, the ordered list at the end of the page is not rendered correctly.

Suggestions to improve the Frontend Developer Guide content concerning blocks

I've been spending a lot of time this weekend with the Frontend Developer Guide - http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/bk-frontend-dev-guide.html - and I've noticed two areas that it could potentially be improved in that I wanted to suggest:

1. More content about Blocks - specifically, create a section about Blocks on the same level (and with the same details) as Layout and Templates. Right now there's content on Blocks scattered throughout the guide as it comes up. I think it would be helpful (especially for developers new to any version of Magento) to have Blocks called out in their own section before the Layout section.
2. I couldn't find any mention of CMS/static blocks and how to add those to themes and the fact that users can edit them from the admin panel.

Add quick start for module development to Extension Developers section

I'm sure you have this on your backlog, but adding a quick tutorial like the guest post on Alan Kents blog soon would be very important now that all developers are to play around with Magento 2 in the Dev Beta.

Allow me to quote myself:

Excellent post, Dale! Please add an introduction like this to the Extension Developers section of http://devdocs.magento.com/.
The documentation team pretty much could copy and paste the text as it covers the most important bits to get going. There’s always time to refine and expand on it later but most developers are checking the dev docs now and may be missing such a tutorial.

"Object that cannot be instantiated by the object manager."

On the Dependency Injection page, there is a section that says:

"Object that cannot be instantiated by the object manager."

Technically there is nothing in the code that prevents this. (e.g. You can instantiate some of the named types using the object manager). There are many reasons why you shouldn't (which are explained correctly on the page) but I wouldn't call them "non-injectable". I would try to expand on what the differences are between "injectable" and "non-injectable" because from the text, I wouldn't know when to use factories and when to use the type as a singleton itself.

Distinction Between Code Generation and Compiled Mode

Hey all -- just a few suggestions here based on some limited real world explorations. I'm not sure what "the right" answer is, but the current documentation about these subjects is/are a little confusing to an outsider.

This is regarding the documentation on "single-tenant" and "multi-tenant" compilation
http://devdocs.magento.com/guides/v2.0/config-guide/cli/config-cli-subcommands-compiler-single.html
http://devdocs.magento.com/guides/v2.0/config-guide/cli/config-cli-subcommands-compiler-multi.html

Each of these pages indicate (or imply heavily) that Magento 2 compilation is the the same thing as code generation

This section discusses the basics of code compilation (which is also referred to as code generation).

However, I'm not sure that's 100% true -- compilation seems to be something more.

While running either of the compiler commands will generate class files in var/generation, compiling also creates a number of .ser files in var/di/ (in this context .ser appears to be PHP's internal serialization format).

The purpose of these files isn't clear.

Also, if these .ser files are present, the framework seems to run in some sort of "Compiled" mode

#File: /lib/internal/Magento/Framework/App/EnvironmentFactory.php
private function getMode()
{
    if (file_exists(ConfigLoader\Compiled::getFilePath(Area::AREA_GLOBAL))) {
        return Compiled::MODE;
    }

    return Developer::MODE;
}

I found this out because removing the files in var/generation/ while in compiled mode appears to break the system. I needed to remove the .ser files as well to restore normal functionality.

If possible, it'd be great if the docs could explain how "compiled" code goes above and beyond simply pre-generating all generated code. This information is going to be of particular importance as developers start rolling out Magento 2 systems into production.

Redis - Suggestions on improving the documentation

Hi,

For the page: http://devdocs.magento.com/guides/v2.0/config-guide/redis/config-redis.html - I suggest we make the documentation more self-contained.

By this I mean, there are lots of links in the documentation of information that I believe should really be in the documentation itself.

Some examples are:

• The ECG PDF information about: Redis settings, information on how to calculate some of the Redis settings (like memory limit), cleaning old tags script (is it available for M2?), etc. This should be added to the documentation.
• From the digital ocean link: how to install Redis.
• From the further external links: installation procedure, command line usage, etc.
• Impacts of catalogue size (or other information) into the amount of memory used by Redis, etc.
• etc.

The external links for blog posts might not be available some time in the near future so I guess a more stand-alone communication is preferable. Links to official documentation are more reliable though.

Thanks!

Why restart Apache after installing Composer?

Why does the installation guide tell you to restart Apache after installing Composer? There does not seem to be anything in the composer install script that would make any difference to Apache.

composer.json example for Module dependencies question

Firstly in: /guides/v1.0/architecture/modules/mod_depend.html there is a problem on line 48 where <Vendor> is not being displayed due to not being escaped.

Although this calls into question whether <Vendor> should just be "Magento" anyway? Based on the content of the example? (name being magento/module-catalog)

Javascript dev guide link doesn't work

• Go to http://devdocs.magento.com/
• Click on JAVASCRIPT DEVELOPER GUIDE
• It goes to this page which gives a 404: http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/bk-javascript-dev-guide.html

Seems to exist just fine as markdown: https://github.com/magento/devdocs/blob/develop/guides/v2.0/javascript-dev-guide/bk-javascript-dev-guide.md

Change project's URL to devdocs.magento.com

On https://github.com/magento/devdocs, there is a link to "Magento developer resources
http://www.magento.com". Perhaps that should be changed to http://devdocs.magento.com/ to show the published website instead.

Configuring cron job - page is blank

https://github.com/magento/devdocs/blob/develop/guides/v1.0/install-gde/prereq/install-cron.md

Link "Installing required PHP extensions on Ubuntu" is broken

Clicking link "Installing required PHP extensions on Ubuntu" doesn't lead anywhere.

Community input: Most-needed tutorial

What one step-by-step tutorial would you benefit from the most right now?

Vote on it by replying to this issue.

Community input: Caching

http://devdocs.magento.com/guides/v1.0/config-guide/config/caching.html

If you'd know something about Magento 2 caching, please click Edit this page in GitHub and provide some details.

Can you upload the jekyll config file?

I want to translate the document into Chinese. Can you upload the jekyll config file?

Missing _config.yml breaks some links and images

After a fresh clone on my local machine (specifically, commit 814d69e at this time of writing), running $ bin/jekyll serve results in a semi-working docs site.

The Magento logo on the homepage is missing:

At least some of the links on the site are broken (notice the duplicated api in the URL):

The broken images and links in question require values from the recently deleted _config.yml file. Either the content should be updated to not require those configuration values anymore, or the _config.yml should be restored.

Page Cache

I'm not seeing much documentation regarding page caching and block caching in the documentation. There is also the topic of private data, and how private data is utilized surrounding caching.

There was a blog article by Alan Kent last December that provides some concepts and overview of what was in development at the time, but I'm looking for what the pieces are now, and how to use them.

In a layout block declaration you can define the block as cachable=false, but I've seen instances such as the product detail page where my additional blocks end up getting cached still even with that block declaration. It also looks like any page that has layout block elements with cachable=false will not utilize private block replacement.

I have a block on a product detail page that is rendered depending on if a custom product attribute exists, and the content in the block is different per visitor depending on the value of a cookie. The cookie value can change based on the visitor's preference, so the content in the block could change at any point, but is specific to the visitor.

Mobile view of devdocs.magento.com

Broken responsive design , hard to read and navigate. Screenshoots from Chrome on iphone 6.

add placeholders for new Topics

While the current documentation looks very clean and well structured, it is still missing a lot of parts.
That is not a problem, but it makes contribution of complete new parts harder, as there are not enough patterns to follow currently.

Examples:

• Where would I add a tutorial about replacing the default Search engine.
• What would be a good place to describe the Interval pattern, how to extend it and what problems it should resolve

Varnish documentation missing some points

Hi All,

Most of the doubts regarding FPC in general (and also Varnish now) are related to its usage and a page life-cycle in cache. I believe the current documentation is missing:

• How to purge data in Varnish from Magento admin.
• Which actions in the backend are likely to generate a purge, and to which URL.
• Static assets cached by Varnish: how to replace them?

Please let me know what are your thoughts on the above.

Thanks!

Formatting of "Introduction to page types" broken

It seems there is a formatting problem at http://devdocs.magento.com/guides/v1.0/architecture/view/page-type.html. After looking at https://github.com/magento/devdocs/blob/develop/guides/v1.0/architecture/view/page-type.md I assume the problem is the non-escaped <ModuleName> tag.

Community input: Extension developers

The following topics in the Extension Developer Guide are up for grabs. If you have input, click Edit this page on GitHub on any of the topics:

• Create the required config files
• Package a module
• Verify the new module

Path needs adjustment in Running Composer ...

In "Running Composer to update dependencies"
"Change to the Magento installation directory and run composer install. For example,
cd /var/www/html/magento2 && composer install"

/var/www/html/magento2 will apply for Centos but Ubuntu has /var/www/magento2

Small Padding to .page-intro

I suggest adding a small amount of padding (think a 14px padding-left) on the .page-intro class would make the headings look better.

Before:

After:

Thoughts?

Correct information

Change short description and link repository for similar in README.md file:

Magento developer resources http://www.magento.com

To:

Magento Developer Documentation http://devdocs.magento.com

Serving with jekyll

I'm trying to build the site with jekyll like it says in the readme. I'm running on windows 7 64 bit. I renamed _config.devdocs.yml to _config.yml. When I run "jekyll serve" I get the following output:

C:\Users\CNCOLE\Documents\GitHub\devdocs>jekyll serve
Configuration file: C:/Users/CNCOLE/Documents/GitHub/devdocs/_config.yml
Source: C:/Users/CNCOLE/Documents/GitHub/devdocs
Destination: C:/Users/CNCOLE/Documents/GitHub/devdocs/_site
Generating...
Liquid Exception: Failed to get header. in guides/v1.0/architecture/backward-compatibility.md
jekyll 2.5.3 | Error: Failed to get header.

Example for around-listener broken

On http://devdocs.magento.com/guides/v1.0/config-guide/config/plugins.html, the example for the around-listener shows the code for the before-listener. I didn't find a fitting example in the gists listed at https://gist.github.com/xcomSteveJohnson.

PDF Versions of the Devdocs should be made available

Creating from a discussion that started on Twitter: https://twitter.com/JoshuaSWarren/status/634727275452239872

Basically - a PDF version (either an on-the-fly PDF generation, or more likely, a pre-generated PDF that's refreshed periodically) of the devdocs would be great. It would allow the docs to be loaded onto ereaders, tablets, etc., and used in offline situations, or downloaded as a complete set before boarding a flight without wifi, etc.

There was a suggestion on Twitter at https://twitter.com/knowj/status/634729093016199168 - "You could clone the repo and build using jekyll as a stop gap. PDF's would be nice as well."

This got me to thinking that maybe there's a way to use Jekyll + https://github.com/pdfkit/PDFKit to automatically generate these PDFs. It wouldn't be the prettiest layout, but it'd be a start.

Architecture > Theme Overview incorrect statement

Currently /guides/v1.0/architecture/arch_themes.md states:

Each theme contains a theme.xml file, which defines the name and version of that theme, as well as the name of the parent theme, if any.

It is my understanding that this is incorrect and that the composer.json file in the theme is responsible for the version and parent information. According to magento/magento2#840 this may be changing but the docs as they stand are incorrect.

Scopes in which plugins can be used.

So reading the docs on plugins it says "Limitations: You cannot use plug-ins for: Non-public methods". However in my testing I was able to create a Plugin for a protected method without an issue, should this read private methods?

Sample

Issue on the README

Add favicon to the http://devdocs.magento.com/

It would be nice if http://devdocs.magento.com/ had a favicon specified. The default Magento icon is an obvious choice, but something more specific might be nice. 16x16 isn't much space to work with, but it would be cool if a document icon could somehow be merged with a Magento icon. Maybe the Magento logo inside of a document. Not sure if the Magento logo guidelines would allow for this usage, but if you think it might be a good idea, let me know and I'll mockup a concept in Photoshop.

SSL Certificate issue on devdocs.magento.com

https://devdocs.magento.com/guides/v2.0/howdoi/php/php_clear-dirs.html trying to use SSL certificate of GitHub which cause error and un-secure connection

Caching corrections

Entered on behalf if @mzeis per tweet to Alan Kent.

"Is there an up-to-date documentation on configuring cache backends in #magento2? http://devdocs.magento.com/guides/v1.0/config-guide/config/caching.html uses local.xml instead of config.php"

Imported CSS line very long restricting contributions

I was looking to make a contribution to resolve some issues with the site responsiveness but the majority of the css (160,000 characters) is on one line:

https://github.com/magento/devdocs/blob/develop/css/app.css#L275

I presume this is a side-effect of some import process from another site/repository.

Would you be able to import it so that it maintains formatting? I tried converters myself but I couldn't be sure that it wasn't introducing bugs.

Alternatively, can you can confirm that this is a long-term restriction and will be continually re-imported and therefore any contributions need to re-define selectors and overwrite any statements included here.

Thanks

Memory size limitted

I'm getting this error message when install sample data as below. Just wonder how much memory does it need to allocate?

Also, any way we can re-install data?

CLI >> bin/magento sampledata:install admin
Installing theme:
.
Installing customers:
.
Installing CMS pages:
....
Installing catalog attributes:
...........................
Installing categories:
.........................................
Installing simple products:
............................................
Installing bundle products:
PHP Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 72 bytes) in /var/www/shop.getbraise.com/html/lib/internal/Magento/Framework/ObjectManager/Factory/AbstractFactory.php on line 221

Amend technology stack

On Technology Stack, you could add these things mentioned by Max in presentations:

• Apache 2.2, 2.4
• Nginx 1.7
• PSR-3
• PSR-4
• Optional stack component: Varnish (Caching)