Creating A Repository

A repository is a central interface, or set of functions, through which domain entity records may be managed. In Uniform we have standardized this interface in order to make components and pages highly reusable in order to maximize Rapid Application Development (RAD) principles.

Define The Entity Name

The entity name is used internally when referencing any meta data pertaining to the given entity like language translation key phrases. This is simply the name of the entity in camel casing, for example User Roles would have an entity name of userRoles.

const entity = 'userRoles';

Define The Entity Slug

The entity slug is used externally when calling the server-side RestFul API endpoint. This is simply the name of the entity in kebab casing, for example User Roles would have an entity slug of user-roles.

const slug = 'user-roles';

The RestFul API must abide to our Uniform API Standard Definition in order to work correctly.

Define The Entity Model

The entity model is used to encapsulate the data of individual entity records. It should normally have at least id: string, modifiedAt: Date and createdAt: Date fields. All fields must use camel casing for the naming convention, and types must be defined for each field.

export interface UserRole {
  id: string;
  status: string;
  name: string;
  description: string;
  super?: boolean;
  modifiedAt: Date;
  createdAt: Date;
}

We export the model for public reference and consumption.

Define The Repository

const repository = new Repository<UserRole>(slug, {}, {});

Define Fields

Though we have defined an entity model, we still need to define the specifics for each of the fields within that entity model (expect for id, modifiedAt, createdAt which are included by default). So the below will try to guide you through the basics of field definitions, but do read up more on this subject since there are way more advanced field definition possibilities than what we have outlined in the below examples.

This is where the magic of the system really happens, without field definitions the system doesn't know how to handle your entity at all. So do take time to ensure that these field definitions are correct as they are the basis of your entity going forward.

Example Enumeration Field

An enumeration field limits a users value to only a select few predefined values, which is the backbone of structured information. Using this type of field often will result in very well structured data. Here you can see we define a field called status which is limited to a value of either pending, approved or rejected.

repository.addField('status', {
  type: EnumValueType.Enumeration,
  defaultValue: 'pending',
  values: [
    'pending',
    'approved',
    'rejected',
  ]
});

Note that we also set a default value of pending for this field, but do be careful of setting default values as users may just hit enter instead of filling in the correct value, so only set default values when it is not going to cause logic or data issues.

Example Text Field

This is the most basic of all field types and should only be used to label data since it is completely unstructured and allows the user to type whatever they want. Never use this field type to infer logic or rely on it for reporting as an enumeration fields works best for such cases. This field type is ideal for short names, emails, phone numbers, headings, etc.

repository.addField('name', {
  type: EnumValueType.Text,
});

Note that you can use the pattern to define a Regular Expression in order to enforce some kind of structure onto this field, especially for emails and phone numbers. But by default the nature of the data one would capture in this field is unstructured or free-text form.

Example TextArea Field

This field is best used to capture meta free-text form data, or in other words, data that better describes the record/object to a human reader. It is typically only used in a description field.

repository.addField('description', {
  type: EnumValueType.TextArea,
  optional: true,
});

Note that this field type will span across multiple rows on the UI as it can contain content with multiple lines of text.

Example Boolean Field

repository.addField('super', {
  type: EnumValueType.Boolean,
  hint: `$vuetify.${entity}.hints.super`,
});

Example Attributes Field

repository.addField('permissions', {
  type: EnumValueType.Attributes,
  attributeRepository: permissions,
});

Define The Headers

repository.setHeaders([
  'status',
  'name',
  'description',
  'super',
  {
    fieldKey: 'createdAt',
    align: EnumHeaderAlign.End,
  },
]);

Define The Sections

repository.addSection(
    new Section(`$vuetify.${entity}.sections.general`, [
      'id',
      'status',
      'name',
      'description',
      'super',
      'modifiedAt',
      'createdAt',
    ])
);

Define The Custom Bulk Actions

repository.bulkActions = [
  {
    color: 'error',
    icon: 'mdi-delete',
    title: '$vuetify.entityList.delete',
    key: 'delete'
  }
];

Export The Repository Definition

The final step in creating a repository is to export the repository for public reference/consumption, this is so that other code routines may interact, by means of an import statement, with our newly created repository in their own unique ways.

export const userRoles = repository;