ÃÛ¶¹ÊÓƵ

DocumentationCommerceAdmin Systems Guide

Developer tools

Last update: Thu Jul 13 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Beginner
  • Intermediate
  • Admin
  • Developer

Use the advanced developer tools to determine the compilation mode during frontend development, create an allowlist of IP addresses, and display template path hints. There is also tooling to easily make spot changes to text in the interface of the storefront and Admin.

Operation modes

Your ÃÛ¶¹ÊÓƵ Commerce or Magento Open Source instance can be deployed to run in either production or developer mode. The tools and configuration settings that are designed specifically for developers can be accessed only while the store is running in developer mode.

The operation mode can be changed only from the command line of the server by a user with appropriate permissions. See Set the operation mode in the Configuration Guide for more information.

Most topics in the merchant documentation apply to a Commerce instance that is running in production mode. However, the following configuration settings and tools can be used only when the installation is running in developer mode.

Frontend development workflow

The Frontend Development Workflow type determines if Less compilation takes place on the client- or server side during development. Less is an extension of CSS that has additional features and conventions, and that produces streamlined code. Client-side Less compilation is recommended for theme development. Server-side compilation is the default mode. The development workflow options are not available for stores in production mode.
See in the Commerce developer documentation.

NOTE
The frontend development workflow configuration is available in Developer mode only.

Advanced configuration - frontend development workflow {width="600" modal="regular"}

  1. On the Admin sidebar, go to Stores > Settings > Configuration.

  2. In the left panel, expand Advanced and choose Developer.

  3. Expand Expansion selector the Front-end Development Workflow section.

  4. Set Workflow Type to one of the following:

    • Client side less compilation - Compilation takes place in the browser using the native less.js library.
    • Server side less compilation - Compilation takes place on the server using the Less PHP library. This is the default mode for production.

  5. When complete, click Save Config.

Static file signatures

Adding a digital signature to the URL of static files makes it possible for browsers to detect when a newer version of the file is available. Static files that can be tracked with digital signatures include JavaScript, CSS, images, and fonts. The signature is appended to the path directly after the base URL. If a file’s signature differs from what is stored in the browser’s cache, then the newer version of the file is used.

See Static content signing in the Commerce developer documentation.

NOTE
The Static File Settings configuration is available only when working in developer mode.

Advanced configuration - static files settings {width="600" modal="regular"}

For a detailed list of the configuration settings, see Static File Settings in the Configuration Reference.

To enable signed static files:

  1. On the Admin sidebar, go to Stores > Settings > Configuration.

  2. In the left panel, expand Advanced and choose Developer.

  3. Expand Expansion selector the Static Files Settings section.

  4. Set Sign Static Files to Yes.

  5. When complete, click Save Config.

Resource file optimization

The time it takes to load resource files can be reduced by merging and bundling files, and by minimizing code.

  • Merging combines separate files of the same type into a single file.
  • Bundling is a technique that groups separate files in order to reduce the number of HTTP requests that are required to load a page.
  • Minification removes spaces, line breaks, and comments, but does not affect the functionality of the code. Because minimized files cannot be edited, the process should be applied only when you are ready to go into production.

By default, ÃÛ¶¹ÊÓƵ Commerce and Magento Open Source do not merge, bundle, or minimize files, and the project developer should determine which file optimization methods should be used.

See Performance best practices for more information.

NOTE
CSS and JavaScript files can be optimized in Developer Mode only.
File type
Supported operations
°ä³§³§Ìý¹ó¾±±ô±ð²õ
MergeMinify
JavaScript Files
MergeBundleMinify
Template Files
Minify

To optimize resource files:

  1. On the Admin sidebar, go to Stores > Settings > Configuration.

  2. In the left panel, expand Advanced and choose Developer.

  3. To optimize CSS files, expand Expansion selector the °ä³§³§Ìý³§±ð³Ù³Ù¾±²Ô²µ²õ section and do the following:

    • Set Merge CSS Files to Yes.
    • Set Minify CSS Files to Yes.

    Advanced configuration - CSS settings {width="600" modal="regular"}

    °ä³§³§Ìý³§±ð³Ù³Ù¾±²Ô²µ²õ

  4. To optimize JavaScript files, expand Expansion selector the JavaScript Settings section and do the following:

    • Set Merge JavaScript Files to Yes.
    • Set Minify JavaScript Files to Yes.

    Advanced configuration - JavaScript settings {width="600" modal="regular"}

  5. To minify PHTML template files, expand Expansion selector the Template Settings section and set Minify Html to Yes.

    Advanced configuration - template settings {width="600" modal="regular"}

  6. When complete, click Save Config.

Client restrictions

Before using a tool such as template path hints, make sure to add your IP address to the Developer Client Restrictions allowlist to avoid disrupting the shopping experience of customers in the store. If you don’t know your IP address, you can search for it online.

NOTE
Developer Client Restrictions can be set in Developer Mode only.

For technical information, see Custom VCL for allowing requests in the Commerce on Cloud Infrastructure Guide.

To add your IP address to the allowlist:

  1. On the Admin sidebar, go to Stores > Settings > Configuration.

  2. In the left panel, expand Advanced and choose Developer.

  3. Expand Expansion selector the Developer Client Restrictions section.

    Advanced configuration - developer client restrictions {width="600" modal="regular"}

  4. For Allow IPs, enter your IP address.

    If access is needed from multiple IP addresses, separate each with a comma.

  5. When complete, click Save Config.

  6. When prompted, refresh any invalid caches.

Template path hints

Template path hints are a diagnostic tool that adds notation with the path to each template that is used on the page. Template path hints can be enabled for either the storefront or the Admin.

NOTE
Template Path Hints can be edited in developer mode only.

See in the Commerce developer documentation.

Example storefront - template path hints {width="700" modal="regular"}

Step 1: Add your IP address to the allowlist

Before using template path hints, add your IP address to the allowlist to avoid interference with customers who are shopping in the store. When you are finished, make sure to clear the Commerce cache to remove all hints from the store.

Advanced configuration - developer client restrictions {width="600" modal="regular"}

Step 2: Enable template path hints

  1. On the Admin sidebar, go to Stores > Settings > Configuration.

  2. In the left panel, expand Advanced and choose Developer.

  3. Expand Expansion selector ³Ù³ó±ðÌý Debug section and do the following:

    Advanced configuration - debug {width="600" modal="regular"}

    • To activate template path hints for the store, set Enabled Template Path Hints for Storefront to Yes.

    • To enable template path hints for the store only when the URL includes the templatehints parameter, set Enable Hints for Storefront with URL Parameter to Yes. Then set value for the parameter if needed. The default value is magento, but you can use a custom value. For example, if you change the value to lorem, you would use mymagento.com?templatehints=lorem to display template hints.

    • To activate template path hints for the Admin, set Enabled Template Path Hints for Admin to Yes.

    • To include the names of blocks, set Add Block Class Type to Hints to Yes.

  4. When complete, click Save Config.

Step 3: Clear the cache

  1. On the Admin sidebar, go to System > Tools > Cache Management.

  2. In the upper-right corner, click Flush Magento Cache.

Translate inline

You can use the Translate Inline tool in developer mode to touch up text in the interface to reflect your voice and brand. When the Translate Inline mode is activated, any text on the page that can be edited is outlined in red. It is easy to edit field labels, messages, and other text that appears throughout the storefront and Admin. For example, many themes use terminology such as My Account, My Wishlist, and My Dashboard, to help customers find their way around. However, you might prefer to simply use the words Account, Wishlist, and Dashboard.

NOTE
The Translate Inline tool is available only when working in developer mode.

See in the Commerce developer documentation.

Example storefront - translatable text {width="700" modal="regular"}

If your store is available in multiple languages, you can make fine adjustments to the translated text for the locale. On the server, interface text is maintained in a separate CSV file for each output block, and is organized by locale. As an alternate approach, rather than use the Translate Inline tool, you can also edit the CSV files directly on the server. Translation files are stored in app/code/Magento/<module_name>/i18n/<language_locale>.csv.

NOTE
To use the Translate Inline tool, your browser must allow pop-ups.

Step 1: Disable output caches

  1. On the Admin sidebar, go to System > Tools > Cache Management.

  2. Select the following checkboxes:

    • Blocks HTML output
    • Page Cache
    • Translations

  3. Set the Actions control to Disable and click Submit.

Step 2: Enable the Translate Inline tool

  1. On the Admin sidebar, go to Stores > Settings > Configuration.

  2. To work with a specific store view, set the Store View to be updated.

  3. In the left panel, expand Advanced and choose Developer.

  4. Expand Expansion selector the Translate Inline section.

    Clear the Use Website checkbox as needed to modify these settings.

    The Enabled for Admin option is not available when editing a specific store view.

    Advanced configuration - translate inline {width="600" modal="regular"}

  5. Set Enabled for Storefront to Yes.

  6. When complete, click Save Config.

  7. When prompted, refresh the invalid caches, but leave the disabled caches as they are for now.

Step 3: Update the Text

  1. Open your storefront in a browser and go to the page that you want to edit.

    If necessary, use the language chooser to change the store view. Each string of text that can be translated is outlined in red. When you hover over any text box, a book icon ( Book icon ) appears.

  2. Click the book icon to open the Translate window and do the following:

    • If the change is for the specific store view, select the Store View Specific checkbox.

    • Enter the new Custom text.

  3. When complete, click Submit.

    Enter Custom Text {width="700" modal="regular"}

  4. To see your changes in the store, refresh the browser.

  5. Repeat this process for any elements in the store to be changed.

Step 4: Restore the original settings

  1. Return to the Admin of your store.

  2. On the Admin sidebar, go to Stores > Settings > Configuration.

  3. Set Store View to the specific view that was edited.

  4. In the left panel, expand Advanced and choose Developer.

  5. Expand Expansion selector the Translate Inline section.

  6. Set Enabled for Frontend to No.

  7. When complete, click Save Config.

  8. On the Admin sidebar, go to System > Tools > Cache Management.

  9. Select the checkbox of the following output caches that were previously disabled:

    • Blocks HTML output
    • Page Cache
    • Translations

  10. Set the Actions control to Enable and click Submit.

  11. When prompted, refresh any invalid caches.

Step 5: Verify the changes in your store

Go to your storefront and examine each page that was updated to make sure that the changes are correct. In this example, Customer Login was changed to Customer Sign In. If changes were made to a specific view, use the Language Chooser to switch to the correct view.

Example storefront - translated customer sign in {width="700" modal="regular"}

recommendation-more-help
d3c62084-5181-43fb-bba6-1feb2fcc3ec1