List

A List page; These are the basic pages where you can perform operations such as pagination, sorting, filtering and exporting. You can easily create a server-side data table with a VaList component and a VaDataTableServer component to use list options.

/olobase-demo-ui/src/resources/Employees/List.vue

<template>
  <va-list
    disable-create
    enable-save-dialog
    :filters="filters"
    :fields="fields"
    :items-per-page="10"
  >
   <va-data-table-server
     row-show
     row-save-dialog
     row-save-dialog-width="1024"
     row-save-dialog-height="600"
     disable-clone
     disable-show
   >
   </va-data-table-server>
  </va-list>
</template>

Page Customization

Note that you are free to put whatever you want for each CRUD page and you do not have to use the optimized components provided. Since all data provider methods are available in a dedicated storage module for each source, it's not that complicated to create your own list components that will fetch your data. You can of course use the existing global $axios instance if you need to fetch any custom data coming out of the data provider logic. See usage in the store section.

VaList

The List component allows displaying the settings, filters and parent options of the data table.

<va-list
  :filters="filters"
  :fields="fields"
  disable-settings
  hide-header
>
  <va-data-table-server></data-va-data-table-server>
</va-list>

Options

Slots

Data Table Server

VaDataTableServer is used for pagination of a list that fits the grid structure and for browsing and listing any resources. It includes features such as sorting, search, pagination, filtering and selection. The list layout in the default slot is fully customizable.

Mixins

• Resource
• Search

Options

Slots

Events

Columns

Use the fields attribute to define all columns. You need to at least set the source property that defines the source field you want to fetch, then the type of data formatter if it is different from simple text format. Check fields for all supported fields.

/olobase-demo-ui/src/resources/Employees/List.vue

<template>
  <va-list
    disable-create
    enable-save-dialog
   :filters="filters"
   :fields="fields"
   :items-per-page="10"  
  >
   <va-data-table-server
     row-show
     row-save-dialog
     row-save-dialog-width="1024"
     row-save-dialog-height="600"
     disable-clone
     disable-show
   >
   </va-data-table-server>
  </va-list>
</template>

<script>
import { required } from "@vuelidate/validators";

export default {
  props: ["resource", "title"],
  provide() {
    return {
      validations: {
        form: {
          companyId: {
            required
          },
          employeeNumber: {
            required
          },
          name: {
            required
          },
          surname: {
            required
          },
        }
      },
      errors: {
        companyIdErrors: (v$) => {
          const errors = [];
          if (!v$['form'].companyId.$dirty) return errors;
          v$['form'].companyId.required.$invalid &&
            errors.push(this.$t("v.text.required"));
          return errors;
        },
        employeeNumberErrors: (v$) => {
          const errors = [];
          if (!v$['form'].employeeNumber.$dirty) return errors;
          v$['form'].employeeNumber.required.$invalid &&
            errors.push(this.$t("v.text.required"));
          return errors;
        },
        nameErrors: (v$) => {
          const errors = [];
          if (!v$['form'].name.$dirty) return errors;
          v$['form'].name.required.$invalid &&
            errors.push(this.$t("v.text.required"));
          return errors;
        },
        surnameErrors: (v$) => {
          const errors = [];
          if (!v$['form'].surname.$dirty) return errors;
          v$['form'].surname.required.$invalid &&
            errors.push(this.$t("v.text.required"));
          return errors;
        }
      }
    };
  },
  data() {
    return {
      loading: false,
      yearId: new Date().getFullYear(),
      filters: [
        {
          source: "companyId",
          type: "select",
          attributes: {
            optionText: "name",
            multiple: true,
            reference: "companies",
          }
        },
        {
          source: "jobTitleId",
          type: "select",
          attributes: {
            optionText: "name",
            multiple: true,
            reference: "jobtitles",
          }
        },
        {
          source: "gradeId",
          type: "select",
          attributes: {
            optionText: "name",
            multiple: true,
            reference: "employeegrades",
          }
        },
      ],
      fields: [
        {
          source: "companyId",
          type: "select",
          attributes: {
            reference: "companies",
          },
          sortable: true,
          width: "10%"
        },
        {
          source: "employeeNumber",
          sortable: true,
          width: "10%"
        },
        {
          source: "name",
          sortable: true,
          width: "10%"
        },
        {
          source: "surname",
          sortable: true,
          width: "10%"
        },
        {
          source: "jobTitleId",
          type: "select",
          attributes: {
            reference: "jobtitles",
          },
          sortable: true,
          width: "20%"
        },
        {
          source: "gradeId",
          type: "select",
          attributes: {
            reference: "employeegrades",
          },
          sortable: true,
          width: "10%"
        },
      ],
    };
  }
};
</script>

Field Attributes

Custom Row Actions

Row actions can be customized using the row.actions slot. In the following example, a special delete button in a data table belonging to software developers is directed to a route named delete-developer with the developerId parameter.

<template>
  <div> 
    <va-list 
      disable-settings
      hide-bulk-copy
      :filters="filters"
      :fields="fields"
      :items-per-page="50"
      >
        <va-data-table-server
          disable-show
          disable-clone
          disable-delete
        >
          <template v-slot:row.actions="{ item }">
            <va-action-button
              icon="mdi-delete-forever"
              :color="color || 'red'"
              text
              :to="{ name: 'delete-developer', params: { developerId: item.id  } }"
            ></va-action-button>
          </template>
        </va-data-table-server>
    </va-list>
  </div>
</template>

Field Templating

In case all the slot options above do not meet your needs, you can use the advanced slot templating for each slot. You can even use all the Olobase Admin fields in it. This is very useful when you need to place the field component inside the parent component as shown below:

<template>
  <va-list
    :fields="fields"
  >
    <va-data-table-server
    >
      <template v-slot:[`field.authors`]="{ value }">
        <v-chip-group column>
          <va-reference-field
            reference="authors"
            v-for="(item, i) in value"
            :key="i"
            color="primary"
            small
            chip
            :item="item"
          >
          </va-reference-field>
        </v-chip-group>
      </template>
    </va-data-table-server>
  </va-list>
</template>

<script>
export default {
  props: ["resource", "title"],
  data() {
    return {
      fields: [
        //...
        "authors",
        //...
      ],
      //...
    };
  },
  //...
};
</script>

To do this, simply use a slot called field.{source}; where source is the name of the field. This slot will provide you with the full row source element and the value of the cell to render by default.

Another example:

<template>
  <va-list
    :fields="fields"
  >
    <va-data-table-server
    >
      <template v-slot:[`field.orderStatusId`]="{ item }">
        <v-chip 
          label
          :color="getOrderStatusColor(item.orderStatusId)"
          >
          <v-icon icon="mdi-label" start></v-icon>
          {{ $t("resources.orders.chips." + item.orderStatusId) }}
        </v-chip>
      </template>
    </va-data-table-server>
  </va-list>
</template>

<script>
export default {
  props: ["resource", "title"],
  methods: {
    getOrderStatusColor(val) {
      if (val == "waiting") {
        return 'orange-darken-1';
      }
      if (val == "canceled") {
        return 'red-darken-1';
      }
      if (val == "completed") {
        return 'green-darken-1';
      }
    },
  }
  //...
};
</script>

Expandable Row

You can use the extended element property with show-expand support for an additional full colspan cell below the element row. This method can be used when row data is long or for quick viewing.

<template>
  <va-list 
   :filters="filters"
   :fields="fields"
   >
    <va-data-table-server 
       disable-show
      :show-expand="true"
      :expand-on-click="true"
      :disable-actions="false"
    >
      <template v-slot:top>
        <v-toolbar flat>
          <v-toolbar-title>Expandable Table</v-toolbar-title>
        </v-toolbar>
      </template>
      <template v-slot:expanded-row="{ columns, item }">
        <tr>
          <td :colspan="columns.length">
            More info about {{ item.raw.roleName }}
          </td>
        </tr>
      </template>
    </va-data-table-server>
  </va-list>
</template>

Editable Rows

To create a data table with editable rows, you must use the following attributes in the VaDataTableServer component. When using these attributes, you must disable standard operations such as disable-edit, disable-show and disable-clone.

An editable table may include the following actions:

• row-create
• row-clone
• row-edit
• row-show
• row-delete

<template>
  <va-list 
      disable-create
      :fields="fields"
      :items-per-page="50"
    >
      <va-data-table-server
        row-create
        row-clone
        row-edit
        disable-edit
        disable-show
        disable-clone
        disable-create-redirect
      >
      </va-data-table-server>
  </va-list>
</template>

Editable Interactive Rows

If you want to change another selection field interactively after selecting a selection field, take a look at the code in the example below.

<script>
export default {
  props: ["resource", "title"],
  data() {
    return {
      fields: [
        {
          source: "companyId",
          type: "select",
          attributes: {
            reference: "companies",
          },
          sortable: true,
          width: "15%"
        },
        {
          source: "departmentId",
          type: "select",
          attributes: {
            reference: "departments",
          },
          key: "companyId",
          filters: ["companyId"],
          sortable: true,
          width: "15%"
        },
      ],
    };
  }
};
</script>

Save in Dialog

If you want the update process to be done in a new window for each record listed in the data list, you should use the following attributes.

• rowSaveDialog
• rowSaveDialogWidth
• rowSaveDialogHeight

/olobase-demo-ui/src/resources/Employees/List.vue

<template>
  <va-list
    disable-create
    enable-save-dialog
   :filters="filters"
   :fields="fields"
   :items-per-page="10"
  >
   <va-data-table-server
     row-show
     row-save-dialog
     row-save-dialog-width="1024"
     row-save-dialog-height="600"
     disable-clone
     disable-show
   >
   </va-data-table-server>
  </va-list>
</template>

Data Iterator Server

The VaDataIteratorServer component is used to display data that does not fit into the grid structure or needs to be customized and is similar in functionality to the v-data-table component. It includes features such as sorting, search, pagination, filtering and selection. The list layout in the default slot is fully customizable.

Mixins:

• Resource
• Search

<template>
 <va-list
    :filters="filters"
    :fields="fields"
    disable-create
    disable-positioning
    disable-visibility
    :items-per-page="2"
  >
    <va-data-iterator-server
      :pagination="{ 
        density: 'default',
        activeColor: 'primary',
        top: false,
        bottom: true,
        rounded: 'pill',
      }"
    >
      <template v-slot:default="{ items }">
        <v-row no-gutters class="bordered pt-1 pb-1 justify-center" v-if="$store.state.api.loading">
          <v-progress-circular
            color="primary"
            indeterminate
          ></v-progress-circular>
        </v-row>
        <v-row no-gutters v-else>
          <v-col
            v-for="(item, i) in items"
            :key="i"
            cols="12"
            sm="6"
            xl="3"
            class="mb-3"
          >
            <v-sheet border rounded :class="(isOdd(i)) ? '' : 'mr-5'">
              <v-list-item
                :title="item.raw.username"
                :subtitle="item.raw.id"
                lines="two"
                density="comfortable"
              >
                <template v-slot:title>
                  <strong class="text-h6">
                    {{ item.raw.username }}
                  </strong>
                </template>
              </v-list-item>
              <v-table density="compact" class="text-caption">
                <tbody>
                  <tr align="right">
                    <th width="20%">{{ $t("resources.failedlogins.fields.attemptedAt") }}:</th>
                    <td>{{ item.raw.attemptedAt }}</td>
                  </tr>
                  <tr align="right">
                    <th>{{ $t("resources.failedlogins.fields.ip") }}:</th>
                    <td>{{ item.raw.ip }}</td>
                  </tr>
                  <tr align="right">
                    <th>{{ $t("resources.failedlogins.fields.userAgent") }}:</th>
                    <td>{{ item.raw.userAgent }}</td>
                  </tr>
                </tbody>
              </v-table>
            </v-sheet>
          </v-col>
        </v-row>              
      </template>
      <template v-slot:bottom.pagination.header="{ page, pageCount }">
        <v-footer class="text-body-3 mt-6 mb-2" style="padding:0;">
          <div>{{ $t("dataiterator.displaying_page", {page, pageCount}) }}</div>
        </v-footer>
      </template>
      <template v-slot:no-data>
        <v-row no-gutters class="bordered pt-1 pb-1 justify-center" v-if="$store.state.api.loading">
          <v-progress-circular
            color="primary"
            indeterminate
          ></v-progress-circular>
        </v-row>
        <v-row no-gutters class="bordered pt-2 pb-2 justify-center" v-else>
          {{ $t("va.datatable.nodata")}}
        </v-row>
      </template>
    </va-data-iterator-server>
  </va-list>
</template>

<script>
export default {
  props: ["resource", "title"],
  data() {
    return {
      filters: [
        {
          source: "username",
          type: "select",
          attributes: {
            reference: "failedloginusernames",
            multiple: true,  
          }
        },
        {
          source: "ip",
          type: "select",
          attributes: {
            reference: "failedloginips",
            multiple: true,  
          }
        },
        {
          source: "attemptedAtStart",
          type: "date",
        },
        {
          source: "attemptedAtEnd",
          type: "date",
        }
      ],
      fields: [
        {
          source: "username",
          type: "text",
          sortable: true,
          width: "10%"
        },
        {
          source: "attemptedAt",
          type: "date",
          sortable: true,
          width: "10%"
        },
        {
          source: "userAgent",
          sortable: true,
          width: "10%"
        },
        {
          source: "ip",
          sortable: true,
          width: "10%"
        },
      ],
    };
  },
  methods: {
    isOdd(number) {
      return (number & 1) === 1;
    }
  }
};
</script>

Options

Slots

Search

The global search filter will be enabled by default. To disable this, use the disableGlobalSearch property. This filter will send the search query to the backend via the key configured in the globalSearchQuery variable, which is q by default. Then, on the backend side for SQL processing, for example, the multi-column LIKE search will be done automatically, thanks to the relevant model Olobase\Mezzio\ColumnFilters class.

<template>
  <va-list 
   :fields="fields"
   :filters="filters"
   >
    <va-data-table-server 
       disable-show
      :disable-actions="false"
    >
    </va-data-table-server>
  </va-list>
</template>

<script>
export default {
  props: ["resource"],
  data() {
    return {
      filters: [],
      fields: [
        {
          source: "roleName",
          sortable: true,
        },
        {
          source: "roleKey",
          sortable: true,
        },
        {
          source: "roleLevel",          
          sortable: true,
        },
      ],
    };
  }
};
</script>

<?php
namespace App\Model;

use Exception;
use Olobase\Mezzio\ColumnFiltersInterface;
use Laminas\Db\Sql\Sql;
use Laminas\Db\Sql\Expression;
use Laminas\Paginator\Paginator;
use Laminas\Paginator\Adapter\DbSelect;
use Laminas\Db\Adapter\AdapterInterface;
use Laminas\Cache\Storage\StorageInterface;
use Laminas\Db\TableGateway\TableGatewayInterface;

class RoleModel
{
    private $conn;
    private $roles;
    private $rolePermissions;
    private $cache;
    private $adapter;
    private $columnFilters;

    public function __construct(
        TableGatewayInterface $roles,
        TableGatewayInterface $rolePermissions,
        StorageInterface $cache,
        ColumnFiltersInterface $columnFilters
    )
    {
        $this->roles = $roles;
        $this->rolePermissions = $rolePermissions;
        $this->cache = $cache;
        $this->adapter = $roles->getAdapter();
        $this->columnFilters = $columnFilters;
        $this->conn = $this->adapter->getDriver()->getConnection();
    }

    public function findAllBySelect()
    {
        $sql = new Sql($this->adapter);
        $select = $sql->select();
        $select->columns([
            'id' => 'roleId',
            'roleKey',
            'roleName',
            'roleLevel',
        ]);
        $select->from(['r' => 'roles']);
        return $select;
    }

    public function findAllByPaging(array $get)
    {
        $select = $this->findAllBySelect();
        $this->columnFilters->clear();
        $this->columnFilters->setColumns([
            'roleKey',
            'roleName',
            'roleLevel',
        ]);
        $this->columnFilters->setData($get);
        $this->columnFilters->setSelect($select);

        if ($this->columnFilters->searchDataIsNotEmpty()) {
            $nest = $select->where->nest();
            foreach ($this->columnFilters->getSearchData() as $col => $words) {
                $nest = $nest->or->nest();
                foreach ($words as $str) {
                    $nest->or->like(new Expression($col), '%'.$str.'%');
                }
                $nest = $nest->unnest();
            }
            $nest->unnest();
        }
        if ($this->columnFilters->orderDataIsNotEmpty()) {
            foreach ($this->columnFilters->getOrderData() as $order) {
                $select->order(new Expression($order));
            }
        }
        // echo $select->getSqlString($this->adapter->getPlatform());
        // die;
        $paginatorAdapter = new DbSelect(
            $select,
            $this->adapter
        );
        $paginator = new Paginator($paginatorAdapter);
        return $paginator;
    }
}

In addition to the filters that appear by default, you may also need some built-in filters that the user cannot change through the user interface. Use the filter feature for this. This is a simple key/value object that will be automatically sent to your data provider and combined with other active filters.

Filters

Any filters you add are active by default. These active filters and columns can be customized by the user with show/hide actions in the settings tab. In addition to global search, VaDataTableServer also supports advanced custom filters with many supported entries as shown here:

Supported inputs for filtering are as follows:

• text
• number
• boolean
• date
• rating
• select (returns to object as default)
• autocompleter

Use filter properties to define new filters. Here's a code sample usage of these advanced filters:

<script>
export default {
  props: ["resource", "title"],
  data() {
    return {
      loading: false,
      yearId: new Date().getFullYear(),
      filters: [
        {
          source: "companyId",
          type: "select",
          col: 2,
          attributes: {
            optionText: "name",
            multiple: true,
            reference: "companies",
          }
        },
        {
          source: "jobTitleId",
          type: "select",
          col: 2,
          attributes: {
            optionText: "name",
            multiple: true,
            reference: "jobtitles",
          }
        },
        {
          source: "gradeId",
          type: "select",
          returnObject: false, // sends ids as array
          col: 3,
          attributes: {
            optionText: "name",
            multiple: true,
            reference: "employeegrades",
          }
        },
      ],
    };
  }
};
</script>

For the input type, you should mainly use the type as well as the mandatory source attribute. Use the attributes property to combine specific attributes with the input component.

See all supported domain features:

Interactive Filters

If you want another filter(s) to change interactively after selecting a filter, take a look at the code in the following example.

<script>
export default {
  props: ["resource", "title"],
  data() {
    return {
      filters: [
        {
          source: "yearId",
          type: "select",
          attributes: {
            optionText: "name",
            multiple: false,
            reference: "years",
          },
          label: this.$t("employees.yearId"),
        },
        {
          source: "salaryListId",
          type: "select",
          attributes: {
            optionText: "name",
            multiple: false,
            reference: "salarylists",
          },
          key: "yearId",
          filters: ['yearId'],
          label: this.$t("salaries.salaryListId"),
        },
      ]
    };
  },
};
</script>

Filtering Between Two Date

If you want to filter a date column between two specified date columns, you must add Start and End to the end of the column name.

In the following example, two date filters named attemptedAtStart and attemptedAtEnd are added for the attemptedAt column name.

<script>
export default {
  props: ["resource", "title"],
  data() {
    return {
      filters: [
        {
          source: "username",
          type: "text",
        },
        {
          source: "attemptedAtStart",
          type: "date",
        },
        {
          source: "attemptedAtEnd",
          type: "date",
        }
      ],
      fields: [
        {
          source: "username",
          type: "text",
          sortable: true,
          width: "10%"
        },
        {
          source: "attemptedAt",
          type: "date",
          sortable: true,
          width: "10%"
        },
      ],
    };
  },
};
</script>

Universal Actions

This VaList component comes with only 1 global action called create. The Create button will only appear if the current resource has a create action and the authenticated user has create permission on that resource.

Action Events

You don't have to follow the default redirect behavior. If you prefer a create action, simply subscribe to the action event and disable redirect generation with the disableCreateRedirect property to prevent the create button from redirecting to the linked action page. The same behavior applies to the show, edit and clone actions inside the VaDataTableServer. If you need a custom behavior within an Aside or dialog, use the item-action event and disable the default redirect. Note that all these keys will be automatically hidden if no action is taken for the relevant keys. Disabling each relevant action redirect will force the keys to reappear.

These action events will always provide you with the adapted CRUD header as well as the refreshed element from the API.

Customizable Actions

If you need other item actions in addition to the standard actions, use the special item.actions slot. For an updatable data table, you should use the row.actions slot.

<template>
  <va-list
   :fields="fields"
  >
    <va-data-table-server>
      <template v-slot:[`item.actions`]="{ resource, item }">
        <va-my-custom-button
          :resource="resource"
          :item="item"
        ></va-my-custom-button>
      </template>
    </va-data-table-server>
  </va-list>
</template>

Class Actions

Data listing supports all kinds of bulk operations, whether copying or deleting. This feature will use your data provider's copyMany, updateMany and deleteMany methods. When you select some items, all available bulk actions will appear in the header.

Customizable Bulk Actions

By default Olobase Admin provides the bulk delete action, but you can add multiple bulk actions as required using the VaBulkActionButton which will use the bulk.actions slots and updateMany . This last component needs a necessary action prop that will be the object to send to your API. This object will contain all the properties you want to bulk update. The next example will show you an example of a bulk publish/unpublish bulk action:

<template>
  <va-list
    :filters="filters"
    :fields="fields"
    :items-per-page="10"          
  >
    <template v-slot:bulk.actions="{ selected }">
      <va-bulk-action-button
         :label="$t('users.enable')"
         icon="mdi-publish"
         color="success"
         :value="selected"
         :action="{ active: true }"
         text
      ></va-bulk-action-button>
       <va-bulk-action-button
         :label="$t('users.disable')"
         icon="mdi-download"
         color="orange"
         :value="selected"
         :action="{ active: false }"
         text
        ></va-bulk-action-button>
    </template>
    <va-data-table-server
      row-create
      row-show
      row-edit
      disable-clone
      disable-show
      disable-edit
    >
    </va-data-table-server>
  </va-list>
</template>