mTools Docs

# Scripts

Here you can find several rules how to build, manage and extend scripts. Please read them all, check the existing components to follow the rules from references as well.

# Use Composition API

Originally application ware written with the Options API pattern. Right now we're trying to rewrite the whole logic to more reusable and functional based one. Every new feature and component should be build in the CAPI. If it's a possible try to rewrite existing ones as well. If the component or related module is complex try to mix both patterns but be aware the Composition API flow first.

Build composables.

The major and one of the most important things that Composition API allows is to split and move our common business logic into separated blocks (files) called composables. Then reuse them in the whole app. Check the existing ones in the codebase - useLeads, useNotes.

Composition API Guidelines can be found here (opens new window).

# Keep the Options API component flow

That's the paradox, even we're forcing rewriting whole scripts logic to Composition API we try to keep Options API related components flow. As with the Composition API the code structure is more "squeezed" in the setup hook it might be hard sometimes to follow the data flow. So to keep it clean try to keep well known SFC strcture.

<script lang="ts">
export default Vue.extend({
  setup() {
    // imports
    // data (refs, reactive, computed)
    // lifecycle hooks
    // methods
    // watchers
    // returns
  },
})
</script>

# Name your logic by the responsibility

Try to keep naming of the values, variables and methods with its destination. At the same time remember about simplicity and readability. Don't create all the world covering variables.

Use:

  • submitting not: formIsSubmitting
  • submit not: submitForm
  • submitted not: fromWasSubmitted

Be aware about code readability. Define names by logical connection between script and template. Try to not force jumping between parts of you components. When it's boolean, name it properly, when it's object do the same.

Use:

  • isWorkSchedule - boolean
  • workSchedule - object, array

# Use if, else notation properly

Try to use regular and common pattern of defining conditions. if else is good, efficient, performant and readable. Try to not use if guards if not needed. Don't use returns if not need.

Templates

<!-- Bad -->
<component v-if="user" />
<component v-if="!user" />

<!-- Good -->
<component v-if="user" />
<component v-else />

Scripts

<script lang="ts">
export default Vue.extend({
  setup() {
    // Bad
    const changeItem = ($value) => {
      if (item.value === $value) {
        return
      }
      const otherItem.value = $value
    }
    // Good
    const changeItem = ($value) => {
      if (item.value !== $value) {
        otherItem.value = $value
      }
    }
  },
})
</script>

# Avoid unclear prefixes for methods

Don't use on or so with your methods. This means nothing, we all know that there will ba some action ahead. handle is not good as well but saying a bit more about the action.

# Use computed

Building arrays from mappings, chaining the multiple data values, or maybe defining some numbers? Use computed property, it will keep you code cleaner, allow to save it in the memory and will be reactive. Computed values they will help you a lot.

# Split methods

Avoid building huge and flow-less methods. Try to split your actions logic to smaller pieces. Call them one by one with some consequence. For submits for instance.

# Don't divide if not needed

Your code should be divided naturally, you don't need "enters" especially with Options API. If you define a lot of data values for Composition API though try to split them somehow, maybe use comments, but don't break your code without any particle reasons. There are no existing real and applicable patterns for that.

# Use natural data flow

Try to build you components with natural data flow for Vue. Communicate them with emits, props and watchers. Avoid to call methods by references from the template. This way you will not have any control on them. Define props and emits by the parent/child connection.

Use:

<component @form-submitted="handleFormSubmitted" />

# Avoid complicated condition shorthands

Using condition shorthands? If you want, use one-liner for that, but if the construction is more complex define it with regular way, by using brackets.

<script lang="ts">
export default Vue.extend({
  setup() {
    const item = ref(10)
    // Good
    if (item.value) doSomething()
    item.value === 0 ? doSomething() : doSomethingElse()
    // Good
    if (item.value) {
      doSomething()
    }
    if (item.value === 0) {
      doSomething()
    } else {
      doSomethingElse()
    }
    // Bad
    item.value === 0 ? (item.value > 2 ? doSomething() : doSomethinElse()) : doSomethingElseThanElse()
  },
})
</script>

# Functions, methods definition

Writing new functions or methods i the components? Follow these simple rules.

  • use $ as prefix for you arguments, they will be better recognizable in the function body
  • type function body if possible
<script lang="ts">
export default Vue.extend({
  setup() {
    const myFunction: ($argument: string) => boolean = ($argument: string) => {
      return $argument === 'string'
    } 
  },
})
</script>

← Typescript →