Or with Vue for that matter.
One codebase, any platform!
tl;dr;#1— If you already understand the basics of composing a UI in Quasar or Vue and just want to see some of it in action with Quasar’s QBtn component, drop down to “Reasons for Change — SRP in components?”
tl;dr;#2 — If you don’t know about backend templating engines or don’t care about inheritance of template code compared to composition, drop down to “An example of component building with QBtn”.
tl;dr;#3 — If you just want to play with some code from this tutorial, check out the Sandbox demo (give the sandbox time to fire up). 😃
Repo: https://github.com/quasarframework/quasar
Before we begin, this article is going to assume you have some basic knowledge about how Vue works. If not, you might get a bit confused. If you are feeling confused after reading this article, you need to learn more about Vue. And please don’t be frustrated. If you don’t know React or reactive UI technologies, take a step back and learn what they are about. Then come back. You won’t be disappointed!
Ok. A long lead in that was… let’s get going.
The whole concept of Vue is the composition (as opposed to inheritance) of components. If you’ve come from a backend language, where you’ve used some sort of templating engine like Smarty, Twig, Blade, erubis, hero, Velocity (and the list goes on and on), then you probably already feel at home with Vue’s syntax and Single File Components. However, we need to understand this is still a different system compared to backend templating engines and their “way of thinking”.
Those back-end templating engines all have a top-down methodology with the capability to inherit template code. You build a page and try to think about what needs to be extracted to reduce code duplication and you try to use inheritance to extend those smaller templates, but only where their features differ slightly.
With Vue, the goal is to think of components first, i.e. the smallest reusable parts of an application, and build up from there.
From the VueJS website: “It’s common for an app to be organized into a tree of nested components.”
Also with Vue, and this point is the most important one, we are building the model inside these components. Whereas, in the world of server-side templating engines, we inject the model, which we built in some other part of the program. With server-side templating engines, we’re usually using an MVC architecture.
In Vue, the architecture is not MVC but rather MVVM architecture. We are building the model within each component, but only for that component.
If we start to make a complicated component in Vue or Quasar, our model gets complicated too. With composition, we can and should avoid that complication.
I’m going to put something out there that might be controversial. Any Vue component template should not be verbose! If you have more than 40 to 50 lines of template code, then your template or rather your component, is doing too much. This might expand to 100 lines or so, if you are using render functions. At any rate, if you’ve heard it before with MVC architecture, “thin controllers, thick models”, then I say something similar goes for the MVVM and SFC architecture.
It’s…
You should have thin structures and thick models.
Theoretically, with thin structures, i.e. small templates, we don’t need the inheritance of template code between components. Still, inheritance of template code between components makes for a heated topic of discussion in Vue circles. It’s been suggested more than a couple of times to get template extension through inheritance in Vue, like in this issue. And every time a suggestion like that comes up Evan You, the creator of Vue, doesn’t bite. He says an additional extension system for just the template syntax would make Vue’s current system unnecessarily harder to reason about. I agree.
Composition for the win! 😏
Code reuse with Vue’s composition techniques (i.e. the slot system, mixins, component elements/objects, etc.) do seem a just bit laborious at times. And some of it, like slots, is so different to what was previously known, it catches beginners to Vue a bit off guard. I was in this boat too.
Nonetheless, if you think about what you want to get accomplished and then “build out” or compose your version of components, understanding the DOM hierarchy rules (Parent / Child relationships) and keeping SRP and “thin structure/ thick models” in mind, that is all you really need to achieve code reuse (which is the goal of inheritance too). The DRY principle of programming, i.e. “code smartly once and reuse it often”, can be relatively easily achieved with Vue’s composition facilities.
The aim of this tutorial is to get you thinking (more) along those lines.
An example of component building with QBtn
I’m repeating this again, because it is vital to understanding how to work with both Quasar and Vue. Vue’s core premise is built on_composition_, which means the action of putting things together. These “things” in Vue are components. Check out the meaning of the word “component”.
It’s Latin for “Putting together” 😁
This may be a no-brainer but, it is easy to start building components that aren’t components. They are more like in the world of OOP, god components, doing a lot of stuff and breaking easily. It can happen quickly and why I keep mentioning SRP. Take advantage of Vue’s composition facilities and remember SRP……always!
As you know, Vue takes your components, your compositions and smartly puts them in a virtual DOM hierarchy, then renders that to your users and makes it all reactive. It’s why we can’t “unthink” hierarchies with components, because the DOM is a hierarchy. And this hierarchy doesn’t matter for interactivity with the user, because when components are done right, the data manipulations, the bindings, are directly visible within the DOM, at the right place at the right time. This “reactive” system is what makes reactive UI libraries like Vue world’s better than you having to find the data in the DOM to then manipulate it (ehem, like in jQuery).
Remember the other core concept of Vue and reactive programming is…
“Let your data do the walking!”
😏 Ok. I made that up……. But, it’s true! 😄
Reasons for Change — SRP in Single File Components?
There are five possible “responsibilities” or reasons why we may be touching a component to change it. Now you might be saying, um, but the “S” in SRP is for “Single”. Yup, and theoretically, we can separate these 5 responsibilities into their own modules/ files for change. More importantly, a Vue component can hold them all. These reasons for change or responsibilities are also the sources as to why we would want to “compose” them differently. They are:
- Styling/ Design (CSS)
- Structure (HTML)
- Behavior (JavaScript)
- the all important — Data Model or Model
- and the (hopefully)single goal of the component
If you are going, “um, say what?” right now. Now worries. Hopefully, you’ll get an understanding of what is meant above, as we go through the tutorial.
The Plan
Like with any type of creation, there needs to be a plan in place for our new button to end up as we intend it to be. You may think, “Hey, it’s just a little ol’ button.” Well. This tutorial will show you a custom button component in Quasar (or Vue) can be quite powerful and intricate. So, having a plan - an idea of what you want the button to do or be - is really important.
There are so many possibilities with just this one component that composing it to be something more with other Q-components or logic/ behavior, and even only using it as a stock button without having a plan, will most likely end up in a crazy, maybe even frustrating, mess.
The power of Vue lies in your easily keeping a mental model of what you want a component to do. However, that mental model also needs to be formulated before you begin “composing”.
So, this is what our button should do, when it is finished (noting the top 4 “reasons for change” mentioned above in parenthesis). The plan itself is the 5th reason. It’s our final objective. And yes, this example is a bit contrived, but let’s just have some fun with making new button components. 😄
This is the plan for our button(s):
- The button should be able to have an image (styling/design).
- If there is no image, it will return to being a “normal” Quasar button automatically (behavior, styling/design).
- It should have a tooltip option, no matter what form it is in (regular or with an image) (structure, behavior).
- The tooltip will be controlled via data input only (data model). That means, if a tooltip text is in the data, a tooltip will show up, automatically.
- The tooltip will either be at the top of the button or at the bottom (styling/ design).
- We’ll also offset the tooltip with 5 pixels above or below the button as standard and fixed, simply because we think it looks better (styling/ design).
- From the Quasar Btn component, our button should have a (styling/design):
- Label — for text in the button.
- Color — for coloring the button.
- Icon — to add an icon.
- Size — to control the size of the button ,when it is a normal button. We’ll only use the pixel values for now for the image type button.
- Flat — for a flat button.
- Round — for round buttons (think about avatars, where you need a link to a profile, etc.).
- Outline — for adding an outline.
With the QBtn props, we could go on and on. There are 29! However, we’ll stop here. Your decisions for your new component will determine the props to take over.
- Additionally to the Quasar Btn props, our button will have:
- Outline Color — since the Quasar Btn has only one color and we are using that currently for our background, we need a different prop for the image button’s border color.
- Image URL — for optionally adding an image for our image button (structure).
- Tooltip Text — if our button should have a tooltip (behavior, data model).
- Tooltip Location — either “top” or “bottom”. “Top” is the default. Yeah, we are reducing the feature set of QTooltip, but for our use case with buttons, we only want this behavior.
- Visibility Control — to show only when it should be shown (behavior , see point 10).
- We know our image buttons will always be flat and should be outlined in the color selected in the color prop(styling/design). The text is the same color too (styling/design). This is simply how QBtn works.
- The button should have a visibility prop. If it is true, the button is visible. If false, it is not there (data model, behavior).
- As a last objective and not part of our button composition, we’ll put together a “button bar” demonstrating the compositional ability of the “slot” in Vue.
You must admit, that is a lot of things to consider. We are making a “super duper power button”. 😁 And, maybe we will want to have button components that only do some of these things, right? Or, well, maybe not. No matter. We’ll build out the different buttons for the sake of demonstrating composition.
So, with that in mind, let’s compose 4 different buttons and our button bar.
Button #1 — Styling/ Design with an Image
Please note that the /components directory is our own component code and our /pages directory is where the components are consumed and demonstrated in this example.
Ok. That said….
Although we can argue about this, adding an image to a button is a design / styling decision. Think of the places we would like to make an image “button-like” in a website. How about those avatar buttons you see so often in chats or forums, which link to a profile page, or even offer a context menu? I’m sure your imagination is filling up with ideas, right?
Have a look at thebtn-image.vuecomponent in the components section of our sandbox(give the sandbox some time to fire up). This is a button element with an image.
Our btn-image template.
If you look into the model of the component, you’ll notice we’re high-jacking some q-btn functionality. Note: this component is NOT finished!
Some familiar CSS from Quasar.
If you also look at the model (the code in the