agorum.grid

Dieses Widget stellt eine tabellarische Liste mit Spalten und Zeilen dar. agorum.grid dient zur Darstellung von großen Datenmengen, die serverseitig gruppiert und sortiert werden. Für die Sortierung der Daten ist immer die serverseitige widget-Implementierung verantwortlich, siehe Suche und Gruppieren/Sortieren der Ergebnisse. Wenn Sie zusätzllich die Ergebnisse paginiert darstellen wollen, müssen Sie dies ebenfalls serverseitig implementieren.

Im Gegensatz zu agorum.grid wird agorum.basicGrid verwendet, um eine Datenmenge direkt vollständig darzustellen.

Die Liste besteht aus zwei Elementen:

• den Spaltenüberschriften (columns)
• den Zeilen / Daten (rows)

Verwendung

Screenshot zum Verwendungsbeispiel

let aguila = require('common/aguila');

let widget = aguila.create({
  type: 'agorum.grid',
  width: 800,
  height: 600,
  sortable: true,
  groupable: true,
  group: { property: 'col1', descending: false },
  sort: { property: 'col2', descending: false },
  columns: [
    {
      name: 'col1',
      text: 'Column 1',
      width: 100,
      hidden: false,
    },
    {
      name: 'col2',
      text: 'Column 2',
    },
  ],
});

let rows = [];

for (let i = 0; i < 100; ++i) {
  rows[i] = {
    // string
    id: i.toFixed(0),
    // row class
    cls: 'row-' + i.toFixed(0),
    // string
    col1: {
      value: 'test a ' + (i / 2).toFixed(0),
      // cell class
      cls: 'col-1-row-' + i.toFixed(0),
    },
    col2: 'test b' + (-i).toFixed(0),
  };
}

widget.rows = rows;

widget.on('selectionChanged', selection => console.log('selectionChanged', selection));

widget;

Events

groupChanged

Das Event groupChanged wird ausgelöst, wenn sich die Gruppierung der Listeneinträge ändert. Dies kann durch den Benutzer ausgelöst werden, indem er die Gruppierung in der Bedienoberfläche verändert (wenn groupable den Wert true hat). Bei agorum.grid ist immer die serverseitige Widget-Implementierung für die Gruppierung/Sortierung verantwortlich. Das Event ermöglicht es, diese Änderungen zu erkennen und die Datenstruktur sowie die Bedienoberfläche entsprechend anzupassen.

Das System gibt die Gruppiereigenschaft bzw. Spalte und die Sortierreihenfolge zurück.

widget.on('groupChanged', group => console.log('groupChanged', group));

itemClicked

Das Event itemClicked wird ausgelöst, wenn ein Benutzer mit der linken Maustaste auf ein Element in der Liste klickt. Dies ist nützlich für Szenarien, in denen eine spezifische Aktion durchgeführt werden muss, wenn der Benutzer eine Auswahl trifft.

Das System gibt als Parameter die selektierte Zeilennummer zurück, beginnend mit 0.

Beispiel

widget.on('itemClicked', itemId => {
  // Search row based on specified ID, find the clicked row
  let item = rows.find(row => row.id === itemId);
  if (item) {
    console.log('itemClicked: ' + itemId + ', col1: ' + item.col1.value);
  }
});

itemDblClicked

Das Event itemDblClicked wird ausgelöst, wenn ein Benutzer auf ein Element in der Liste doppelklickt. Das Event kann verwendet werden, um erweiterte Funktionen zu starten, wie etwa das Öffenen eines detaillierten Ansichtsfensters oder als Übergang zur Bearbeitungsansicht eines Items.

Das System gibt als Parameter die selektierte Zeilennummer zurück, beginnend mit 0.

Beispiel

widget.on('itemDblClicked', itemId => {
  // Search row based on specified ID, find the clicked row
  let item = rows.find(row => row.id === itemId);
  if (item) {
    console.log('itemDblClicked: ' + itemId + ', col1: ' + item.col1.value);
  }
});

itemRightClicked

Das Event itemRightClicked wird ausgelöst, wenn ein Benutzer mit der rechten Maustaste auf ein Element in der Liste klickt. Dies ist nützlich für Szenarien, in denen eine spezifische Aktion durchgeführt werden muss, wenn der Benutzer eine Auswahl trifft.

Das System gibt als Parameter die selektierte Zeilennummer zurück, beginnend mit 0.

Beispiel

widget.on('itemRightClicked', itemId => {
  //  Search row based on specified ID, find the clicked row
  let item = rows.find(row => row.id === itemId);
  if (item) {
    console.log('itemRightClicked: ' + itemId + ', col1: ' + item.col1.value);
  }
});

selectionChanged

Das Event selectionChanged wird ausgelöst, wenn sich die Auswahl in der Liste ändert, also immer dann, wenn der Benutzer einen neuen Eintrag aus der Liste wählt, unabhängig davon, wie er den Eintrag auswählt.

Das System gibt als Parameter ein Array der selektierten Zeilen zurück, beginnend mit 0. Für weitere Informationen siehe selection.

Beispiel

widget.on('selectionChanged', selection => console.log('selectionChanged', selection));

sortChanged

Das Event sortChanged wird ausgelöst, wenn sich die Sortierung der Listeneinträge ändert. Dies kann durch den Benutzer ausgelöst werden, indem er die Sortierung in der Bedienoberfläche (aufsteigend, absteigend) verändert (wenn sortable den Wert true hat). Bei agorum.grid ist immer die serverseitige Widget-Implementierung für die Sortierung verantwortlich. Das Event ermöglicht es, diese Änderungen zu erkennen und die Datenstruktur sowie die Bedienoberfläche entsprechend anzupassen.

Das System gibt die Gruppiereigenschaft bzw. Spalte und die Sortierreihenfolge zurück.

widget.on('sortChanged', sort => console.log('sortChanged', sort));

Parameter

columns (nur schreibend)

Definiert ein Array von Spalten mit folgenden Werten.

Beispiel

let grid = aguila.create({
  type: 'agorum.grid',
  columns: [
    { name: 'id', text: 'ID', width: 50 },
    { name: 'name', text: 'Name', width: 150 },
    { name: 'email', text: 'Email', width: 200, hidden: false }
  ]
});

Beispiel für columns

rows (nur schreibend)

Definiert ein Array von Daten, die in der Tabelle erscheinen.

• Die Daten müssen analog zu den definierten Spalten (columns) sein, wobei das System den Namen der Spalte verwendet, um diesem einen Wert zuzuordnen. Ein Array-Element entspricht genau einer Zeile.
• Legen Sie die Daten in einer separaten Variable ab und ordnen Sie diese dann, also rows, dem grid zu. So können Sie später wieder auf die Daten zugreifen, etwa in den Events.
• Sie können optional für jede Zeile und sogar jede Zelle eine CSS-Klasse mit der Property cls festlegen und in Kombination mit entsprechenden CSS-Stilen gezielt Einträge in der Liste hervorheben.

Beispiel für das Hinzufügen von rows

let aguila = require('common/aguila'); 

let grid = aguila.create({
  type: 'agorum.grid',
  width: 600,
  height: 400,
  columns: [
    {
      name: 'id',
      text: 'ID',
      // width: 50,
    },
    {
      name: 'name',
      text: 'Name',
      // width: 150,
    },
    {
      name: 'email',
      text: 'Email',
    },
  ],
});

// add sample rows with values added to the specified columns
grid.rows = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' },
  { id: '3', name: 'Charlie', email: 'charlie@example.com' },
];

grid;

Beispiels für rows

Beispiel für das Hinzufügen von rows mit cls-Klassen für Layoutangaben

let aguila = require('common/aguila'); // Stellen Sie sicher, dass die aguila-Bibliothek verfügbar ist.

// Erstellen des Grid-Widgets
let grid = aguila.create({
  type: 'agorum.grid',
  width: 600,
  height: 400,
  columns: [
    {
      name: 'id',
      text: 'ID',
      width: 50,
    },
    {
      name: 'name',
      text: 'Name',
      width: 150,
    },
    {
      name: 'email',
      text: 'Email',
      width: 150,
    },
  ],
});

// Beispielzeilen hinzufügen
grid.rows = [
  { id: '1', name: 'Alice', email: 'alice@example.com', cls: 'highlight-row' },
  { id: '2', name: {value: 'Bob', cls: 'highlight-cell'}, email: 'bob@example.com', cls: 'normal-row' },
  { id: '3', name: 'Charlie', email: 'charlie@example.com', cls: 'highlight-row' },
];

grid;

Mithilfe der hinzugefügten CSS-Klassen können Sie CSS-Layout-Anweisungen für Zeilen und sogar Zellen gezielt angeben. In diesem Beispiel ist die Textfarbe für die im Beispiel oben angegebenen CSS-Klassen 'hightlight-row' und 'highlight-cell' angegeben:

Beispiel für rows mit Angabe von CSS-Klassen

groupable

Boolescher Wert, der angibt, ob die Spalten gruppiert werden können. Wenn der Wert 'true' ist, können Benutzer die Gruppierung über die Bedienoberfläche angeben.

let aguila = require('common/aguila'); 

let grid = aguila.create({
  type: 'agorum.grid',
  width: 600,
  height: 400,
  groupable: true,
  columns: [
    {
      name: 'id',
      text: 'ID',
      width: 50,
    },
    {
      name: 'name',
      text: 'Name',
      width: 150,
    },
    {
      name: 'email',
      text: 'Email',
    },
  ],
});

grid.rows = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' },
  { id: '3', name: 'Charlie', email: 'charlie@example.com' },
];

grid;

Möglichkeit zur Gruppierung in einer Bedienoberfläche

group

Die Parameter group und sort dienen dazu, Datenansichten zu organisieren und zu verwalten. Der group-Parameter wird verwendet, um die Daten nach den Werten in einer oder mehreren Spalte(n) zu gruppieren. Dies kann nützlich sein, um Elemente mit ähnlichen Eigenschaften zusammenzufassen und eine strukturierte Darstellung der Daten zu erschaffen. Für die Sortierung der Daten selbst ist die serverseitige widget-Implementierung verantwortlich.

Das group-Objekt hat folgende Eigenschaften:

• property: Der Name der Spalte, nach der sortiert werden soll.
• descending: Boolescher Wert, der angibt, ob die Sortierung absteigend (true) oder aufsteigend (false) erfolgen soll.

Bei Angabe von group werden die Daten nach dem Gruppentitel optisch getrennt dargestellt. 

Im folgenden Beispiel wird die Liste nach Namen gruppiert:

let aguila = require('common/aguila');

let grid = aguila.create({
  type: 'agorum.grid',
  width: 600,
  height: 400,
  group: { property: 'name', descending: false },
  columns: [
    {
      name: 'id',
      text: 'ID',
      width: 50,
    },
    {
      name: 'name',
      text: 'Name',
      width: 150,
    },
    {
      name: 'email',
      text: 'Email',
    },
  ],
});

grid.rows = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' },
  { id: '3', name: 'Charlie', email: 'charlie@example.com' },
  { id: '4', name: 'Charlie', email: 'charlie@example.com' },
  { id: '5', name: 'Alice', email: 'alice@example.com' },
  { id: '6', name: 'Bob', email: 'bob@example.com' },
];

grid;

Gruppierte Daten in einem Grid

selection

[ 0 ]

grid.selection = [ 0 ];

Das folgende Beispiel zeigt, wie selection verwendet werden kann, um Informationen in einer Zeile oder einer Zelle zu ermitteln. In diesem Fall werden die Zeilennummer und der Wert in der Spalte name zurückgegeben:

let aguila = require('common/aguila');

let rowData = [
  { id: '1', name: 'Alice', familyname: 'Parker', email: 'alice@example.com' },
  { id: '2', name: 'Bob', familyname: 'Jones', email: 'bob@example.com' },
  { id: '3', name: 'Charlie', familyname: 'Smith', email: 'charlie@example.com' },
  { id: '4', name: 'Charlie', familyname: 'Jones', email: 'charlie@example.com' },
  { id: '5', name: 'Alice', familyname: 'Parker', email: 'alice@example.com' },
  { id: '6', name: 'Bob', familyname: 'Smith', email: 'bob@example.com' },
];

let grid = aguila.create({
  type: 'agorum.grid',
  width: 600,
  height: 400,
  columns: [
    {
      name: 'id',
      text: 'ID',
      width: 50,
    },
    {
      name: 'name',
      text: 'Name',
      width: 150,
    },
    {
      name: 'familyname',
      text: 'Family Name',
      width: 150,
    },
    {
      name: 'email',
      text: 'Email',
    },
  ],
  rows: rowData,
});

grid.on('selectionChanged', item => {
  let rowNumber = item[0];
  console.log('selectionChanged: ' + rowNumber + ', ' + rowData[rowNumber - 1].name);
});

grid;

sortable

Boolescher Wert, der angibt, ob die Spalten sortiert werden können. Wenn der Wert 'true' ist, können Benutzer die Sortierung über die Bedienoberfläche angeben.

Möglichkeit zur Sortierung in einer Bedienoberfläche

sort

Die Parameter group und sort dienen dazu, Datenansichten zu organisieren und zu verwalten. Der sort-Parameter gibt an, was dem Benutzer angezeigt wird bzw. was er ausgewählt hat. Für die Sortierung der Daten selbst ist die serverseitige widget-Implementierung verantwortlich. Für ein Beispiel siehe Suche und Gruppieren/Sortieren der Ergebnisse.

• property: Der Name der Spalte, nach der sortiert werden soll.
• descending: Boolescher Wert, der angibt, ob die Sortierung absteigend (true) oder aufsteigend (false) erfolgen soll.

Funktionen

reset

Die Funktion reset() setzt die Scrollposition der Liste auf den Anfang zurück.

widget.reset();

setTimeout

Die Funktion setTimeout() kann verwendet werden, um die Bedienoberfläche nach einem festgelegten Zeitraum wieder in den ursprünglichen Zustand zurückzuversetzen. 

Dazu wird eine Callback-Funktion, in diesem Fall reset(), nach der mit dem zweiten Parameter angegebenen Verzögerung aufgerufen. Die Verzögerung beträgt im folgenden Beispiel 1000 Millisekunden (1 Sekunde).

widget.setTimeout(() => widget.reset(), 1000);

Beispiele

Durchführen einer Suche und Gruppieren/Sortieren der Ergebnisse

let aguila = require('common/aguila');
let objects = require('common/objects');
let property = require('common/property');

// Define a query and set a limit for the maximum number of results
let LIMIT = 100;
let QUERY = 'contentsize:[1 TO *]';

// Create an agorum.grid widget with the specified columns and features (groupable, sortable)
let widget = aguila.create({
  type: 'agorum.grid',
  width: 800,
  height: 600,
  sortable: true,
  groupable: true,
  sort: { property: 'name', descending: false },
  columns: [
    {
      name: 'name',
      text: 'Name',
      width: 250,
    },
    {
      name: 'nameextension',
      text: 'Dateityp',
      width: 60,
    },
    {
      name: 'contentsize',
      text: 'Größe',
    },
  ],
});

// Define a function to update the widget's data
let update = () => {
  // Retrieve and unwrap the current group and sort clauses if they exist
  let clauses = [widget.group, widget.sort].filter(x => x).map(clause => property.unwrap(clause));

  aguila
    .fork(() => {
      // Initialize a query with the defined QUERY string
      let q = objects.query(QUERY); // Apply sorting clauses to the query

      q.sort.apply(
        q,
        clauses.map(clause => clause.property + (clause.descending ? ' desc' : ''))
      ); // Search for specified fields, limit the results, and map and assign row data, set an id

      return q
        .limit(LIMIT)
        .search('uuid', 'name', 'nameextension', 'contentsize')
        .rows.map(row => Object.assign({ id: row.uuid }, row));
    }) // Assign the fetched rows to the widget's rows
    .then(rows => (widget.rows = rows));
};

// Event listeners to update the widget when group or sort changes
widget.on('groupChanged', () => {
  console.log('Group changed:', widget.group);
  update();
});

widget.on('sortChanged', () => {
  console.log('Sort changed:', widget.sort);
  update();
});

// Initial update call to populate the widget with data
update();

widget;

Screencast zum Beispiel

Funktionsweise von setTimeout()

Das folgende Beispiel zeigt ein agorum.grid-Widget, das mit einer vorgegebenen Struktur, die drei Spalten umfasst, eingerichtet wird. Die Zeilen werden mit 1000 Einträgen initialisiert. Als Beispiel für eine Änderung der Daten werden die im Grid enthaltenen E-Mail-Adressen in einer Kopie der Originaldaten in Großbuchstaben konvertiert. Die Funktionsweise von setTimeout() wird gezeigt, indem die Originaldaten nach 5 Sekunden wieder geladen werden. Die ersten fünf Zeilen der geänderten Daten und die ersten fünf Zeilen der Originaldaten nach dem Wiederherstellen werden jeweils in die Konsole geschrieben:

let aguila = require('common/aguila');

// Initialize widget
let widget = aguila.create({
  type: 'agorum.grid',
  width: 800,
  height: 600,
  sortable: true,
  columns: [
    { name: 'id', text: 'ID', width: 80 },
    { name: 'name', text: 'Name', width: 200 },
    { name: 'email', text: 'Email', width: 300 },
  ],
});

// Generate data
function generateData(count) {
  const data = [];
  for (let i = 0; i < count; i++) {
    data.push({
      id: i.toString(),
      name: 'Person ' + i,
      email: 'user' + i + '@example.com',
    });
  }
  return data;
}

// Start data
let initialData = generateData(1000);
let currentData = initialData.map(e => Object.assign({}, e));

// Function for converting e-mail addresses to upper case
function updateEmailsToUpperCase(data) {
  for (let i = 0; i < data.length; i++) {
    data[i].email = data[i].email.toUpperCase();
  }
}

// Fill grid with values
widget.rows = currentData;

// Modify e-mail addresses and log the first rows of the modified data (upper case e-mail addresses)
widget.setTimeout(() => {
  updateEmailsToUpperCase(currentData);
  widget.rows = currentData;

  console.log('Modified data:');
  for (let i = 0; i < 5; i++) {
    console.log(currentData[i]);
  }

  // Reset data after 5 seconds and log the first rows of the original data
  widget.setTimeout(() => {
    widget.rows = initialData;

    console.log('Data after reset to original:');
    for (let i = 0; i < 5; i++) {
      console.log(initialData[i]);
    }
  }, 5000);
}, 2000);

widget.on('selectionChanged', selection => console.log('selectionChanged', selection));

widget;

Screencast zum Beispiel