Download the PHP package emaphp/magento2-module-vuewidget without Composer

VueWidget

Vue 2 widgets for Magento 2.

About

This is Magento 2 module skeleton for building and displaying widgets made with Vue.js v2. It comes with with a simple build simple to get you started.

Requirements

This module assumes you are running Magento >=2.2. You'll also need Rollup installed.

Quick start

Enter the app/code/ directory and clone the repo:

Install Node dependencies. You can use either npm or yarn:

Now do a first dev build. This will compile some generic components available on the assets/ folder along with its dependencies:

Go back to the main application folder and enable the module:

Clear cache:

Usage

Login as admin. Go to Stores > Settings > Configuration. You should be able to see a new option at the bottom called Vue Widget. Now, from the main menu, go to Content > Elements > Widgets. Click on Add Widget. On the Settings section, click on the Type field. A Vue Widget option should appear at the bottom. Then pick the area where the widget should be included (for example, within CMS Home Page).

Widgets are included by name; that is, the id used to register them on requirejs-config.js. Try entering VueHelloWorld on the Component field. Then, click on the Add button on the form below. This component supports a single prop called name. Entering a prop is pretty straighforward, just fill the Name and Value columns. Then, hit Save.

Clear cache and refresh the page. You should be able to view your widget on the page you selected.

In-Depth

Adding components

The process of adding components to your app will consist on these steps:

• Write the component using the .vue syntax. Put it inside the assets/frontend/components folder.
• Compile the component using rollup.
• Deploy assets and clear cache.

This module assumes you're already familiar with building Vue.js components, so we'll only cover the second step. By default, Magento is not able to understand files using the .vue extension (or anything using ES6/ES7). To solve this, this repo includes a build system that allows you to turn these files into something that can be included within the page through RequireJS. The process starts by defining which files need to be transpiled. That info can be found within rollup.config.js. The structure of this file is pretty straightforward: an array containing which files should be transpiled and what plugins are required to do so. Create a file inside assets/frontend/components/ called VueCounter.vue and put the following content:

Now, in order to transpile this file to plain Javascript we need to add an additional entry in rollup.config.js. It should look like this:

This entry tells rollup to transpile the file and put the resulting content in view/frontend/web/js/components/VueCounter.js. Open a terminal and run the following command (make sure you're on the module directory):

rollup will now run each entry and generate each bundle separately. This build system uses rollup-plugin-magento2 internally to wrap each bundle into something that can be imported using RequireJS. Once this process is finished, your module is compiled and can now be used as a widget.

We will create a new alias for this component by adding the following line in requirejs-config.js:

Now, login as admin and repeat the steps described in the Quick Start guide. When reaching the Widget Options section, simply enter VueCounter on the Component field. Clear cache and reload the page.

Vue blocks

Widgets are nice but they are kind of limited. For example, you are not able to pass a prop directly from PHP. Because of this, an extended script called vueapp is provided as an alternative. vueapp lets you inject Vue components into your regular HTML blocks. When used this way, the block acts as a component container. Any component that is displayed within must be listed inside the components property:

This example introduces a simple greeting component that reads a prop from PHP. The component should look like this:

We will register this component as VueCustomerGreeting:

The block class purpose is to initialize any values that need to be provided to your component.

Vue blocks are just regular .phtml blocks so they are included using the XML layout system. The example below will add this block to the front page.

Add this new component to the entry list in rollup.config.js. Run npm run build, rebuild the layout and clear cache. You should now be able to see the changes.

Data provider

There will be times that you'll need to pass data to a component as an array/object. Encoding them as props might work at first but doing that for each value it's kind of cumbersome. In order to pass complex data to a component we'll use a common pattern used in Vue components called Data Provider. A Data Provider is a form of dependency injection that will allow you to share a set of data across all components within a block. This object will be generated whenever you set a provider property on the vueapp initializer.

Both of these values will be provided by the block instance directly.

Now, to access these values from within our component we'll invoke the get method on the $provider property.

You can also specify a property key.

Keys can be expressed as paths.

Placeholders

Vue blocks can include a placeholder within their layout to provide a temporal UI. These will be removed automatically once the component is initialized. Placeholder elements have the following properties:

• They need to set their role attribute to placeholder.
• They must be a direct child of the app container.

There are scenarios in which you might want to delay the removal of a placeholder even more (for example, right after fetching data from the server). This can be done by adding the placeholderMixinmixin to your main component. This mixin injects a $placeholder property that provides 2 methods: hide and remove.

Since we're now dealing with the placeholder directly, we need to include an extra property on the vueapp initializer:

By setting this property, the app will now ignore any placeholder element within the block body, allowing you to handle it manually.

Events

Placeholders can also be affected by a given event. For that to happen we need to provide a placeholder value matching the event:action syntax:

When the loaded event is triggered, the component will call the hide method of the placeholder object. A remove method is also available.

You can also specify a custom method. That method needs to be declared within methods and accept a single argument representing the placeholder node.

Importing Magento modules

There will be times that you'll have to access Javascript modules already provided by Magento. For example, you might need to generate changes on the DOM using jQuery or do a calculation using Underscore. We can achieve this by providing an extra option to the transpilation process. The Magento plugin used in rollup.config.js supports an option called virtualDir that allow us to simulate a generic import to a Javascript module. No real import is performed. Instead, the script, once transpiled, will state that it depends on those imported modules. The example below shows an entry setting the virtualDir option:

Now, when importing a Javascript module, prefix the module's name with the virtual directory. You need to add an extra @ symbol at the beginning.

Once transpiled, the script will add any module you imported from the virtual directory to the list of dependencies. That way, we make sure the script will only run after those scripts are loaded.

Component libraries

Another clever technique is putting all you components within a single file. This is useful for cases when you are reusing a lot of components on different pages. A library script would look like this:

We then add the following entry in rollup.config.js:

Then, we create the following alias in requirejs-config.js:

In order to retrieve the components within a library we'll add a special syntax element to the mix. To retrieve the FancyButton component from Fancy_Lib we'll write Fancy_Lib::FancyButton. This rule applies both to widgets and apps.

Extras

Production builds

To produce an optimized build for all scripts (including Vue.js) run npm run prod. This will bundle all your assets using Tercer, which will reduce its size.

If you want to further customize your build process I would recommend checking this post.

Administration widgets

This module already comes with an administration widget called WidgetProps, which you can find in assets/adminhtml/components. This widget is the one responsible for storing the component props on the database. If you plan to change or add more administration widgets remember to properly clear the adminhtml cache as well (which will be located in pub/static/adminhtml/THEME_DIR). Otherwise you might not see any changes during development.

As an additional note, the Widget\Instance class on the Magento_Widget module is overriden to allow props to be provided as an object once they are pushed to frontend. Check out the Vue\Widget\Model\Widget\Intance class for details.

Logs

This module implements a simple logger class that can be injected into any block through dependency injection. Many of the examples use this class to generate debugging messages. You can find these messages on var/log/vuewidget.log. Remember to activate developer mode before starting.

Changelog

• 1.0.0: First release.
• 1.1.0: Added: support for production builds.

License

Vue.js is copyrighted by Evan You and distributed under the terms of the MIT license. Everything else included on this repo is distributed under the MIT license.