Skip to main content

Qore Guidelines

Working within a large framework is always challenging. There have been made certain choices in Qore that are (mostly) only obvious to the creator. These choices could range from certain code styles, to certain structures, to certain stylings etc.

In this (ongoing) document, I'd like to write down some general things you should take in consideration.

Styling​

Fields​

Fields in Qore try to be consistent (in looks & feel) with other fields.

A good example is the basic Text/Field.vue:

<template>
  <q-input
    v-bind="fieldProps"
    :rules="rules"
    v-model="value"
    debounce="250"
    @input="onInput"
    :type="type"
  >
    <template v-slot:label>
      <field-label
        :field="field"
        :required="required"
      />
    </template>
    <template
      v-slot:hint
      v-if="field.hint"
    >
      {{ field.hint }}
    </template>
    <template
      v-if="field.tool_tip"
      v-slot:after
    >
      <field-tooltip :field="field" />
    </template>
  </q-input>
</template>

<script>
import Field from 'qore/mixins/resource/Field'

export default {
  mixins: [Field],
  methods: {
    onInput () {
      this.setState(this.field.name, this.value)
    }
  }
}
</script>

General field rules:

  • The root element should generally be a <q-field> or <q-input>, which binds fieldProps to it
  • Debouncing should be added whenever possible
  • The label should be a <field-label> because it adds a red asterisk when there is an error
  • There should be a slot for the field hint
  • There should be a <field-tooltip>
  • There should be support for validation errors

The fieldProps exist as a computed property in the Field mixin:

fieldProps () {
  return {
    label: this.label,
    style: this.style,
    hint: this.field.hint ? this.field.hint : undefined,
    error: this.errors.length > 0 ? true : undefined,
    'error-message': this.errors[0],
    'hide-bottom-space': this.errors.length === 0,
    readonly: this.readonly,
    disable: this.disabled,
    outlined: this.outlined,
    'stack-label': true,
    dense: this.dense,
    dusk: this.field.name,
    ...this.$attrs
  }
}

Buttons​

You are free to use the <q-btn /> in however way you want, however keep in mind that:

  • Generally try to always add the no-caps property, since that is added everywhere in Qore source
  • Primary submit buttons usually have color="primary"

Components​

Dialogs​

It is recommended to use the <base-dialog> from Qore, since it will:

  • Have a title
  • Have a card inside it
  • Have a max width of 90vw
  • Have a min width given via prop (:min-width="800")
  • Have a max height of: 75vh
  • Have buttons on the bottom which are always in view (even when you scroll the content)

Example:

<base-dialog 
    v-model="dialogShown"
    :title="$t('My title')"
    :minWidth="1200"
>
  content
</base-dialog>

Alerts / Messages​

Qore has a component to show simple alerts/messages:

<base-message
    class="bg-red-2"
    icon="error"
    iconColor="negative"
    :dismissable="false"
    :content="$t('Hello world)"
/>

It also supports a :html prop if you want to display HTML.

Creating a feature​

When you're creating a new feature in your Qore project, there is a chance that you could re-use something that has already been built in Qore. For example, let's say the client wants a reporting tool (like a graph or table).

Please consider the following things in this example.

Ask in Slack​

When you're not sure how to implement something, please ask in the #qore-discussion Slack channel.

Don't write from scratch​

You may prefer to write this feature from scratch, since Qore natively has no reporting functionality. However, for the filters and the request you could use the BaseForm component. This makes it possible for you to have all Qore fields already available. You can listen to e.g. the @ready and @fieldUpdated events if you need to do more custom things.

Try to improve Qore​

When you think your feature (in this case reports) is something that other projects might also need in the future, feel free to discuss it in #qore-discussion Slack channel. It may be better to add it to the Qore source, or as a module / plugin.