Skip to main content

Tasklist Widget

The Tasklist widget is a component that displays a list of tasks. Each task can be marked as done. The widget can render existing tasks and allows for adding new tasks, as well as deleting or editing previously created tasks. It operates entirely on the client side and can integrate with any backend service.

This widget is licensed under the MIT license.

Quick start​

First steps​

To start with the widget, you need to add the necessary package to your project first.

npm install wx-svelte-core
npm install wx-svelte-tasklist

or

yarn add wx-svelte-core
yarn add wx-svelte-tasklist

Now, you can import the widget into your project.

<script>
  import { Willow } from 'wx-svelte-core';
  import { Tasklist } from 'wx-svelte-tasklist';
</script>

<Willow>
  <Tasklist />
</Willow>

The Willow component is a default theme wrapper that will add necessary styles for all SVAR widgets. The Tasklist component may work without it, but it will not have any styles, and it will be your task to add them. It is a common approach when the Willow tag is added once at the top level of your application.

Full init code​

To see the widget in action, you need to provide some tasks to the widget.

Init tasklist widget with data​

<script>
  import { Tasklist } from 'wx-svelte-tasklist';

  const value = [
        {
            id: 7,
            content: "Optimize performance in Svelte applications",
            status: 1,
        },
        {
            id: 8,
            content:
                "Work with API requests and data handling in Svelte applications",
            status: 0,
        }
  ];
</script>

<Tasklist {value} />

Visual Themes​

The widget is provided in two visual styles - Light and Dark, which are controlled by the theme tag.

<script>
import { Willow, WillowDark } from "wx-svelte-core";
</script>

<!-- Light -->
<Willow>
  <Tasklist />
</Willow>

<!-- Dark -->
<WillowDark>
  <Tasklist />
</WillowDark>

Initialization​

The tasklist widget can be initialized in various ways depending on the requirements. It supports loading tasks dynamically from an API, starting with an empty list, or initializing with predefined data. Below are the detailed options for setting up the widget.

Initializing the Widget and Loading Tasks Dynamically​

<script>
  import { Tasklist } from 'wx-svelte-tasklist';

  let value = [];

  fetch('/api/tasks')
    .then(r => r.json())
    .then(x => value = x);
</script>

{#await value}
  <Tasklist {value} />
{/await}

This method is used when tasks need to be fetched from a backend server or API. The fetch function retrieves the task data in JSON format and assigns it to the value variable. The Tasklist widget is rendered once the data is loaded. This approach is ideal for applications where the task list is stored in a database or provided by an external service. It's important to handle the promise using {#await} to ensure proper rendering while waiting for the data.

Initializing an Empty Tasklist Widget​

<script>
  import { Tasklist } from 'wx-svelte-tasklist';
</script>

<Tasklist />

This setup is used when starting with no predefined tasks. The widget initializes without any tasks, allowing users to add tasks manually. This is suitable for scenarios where the task list is built from scratch by the user during runtime. No data fetching or predefined task setup is required in this case.

Initializing the Widget with Predefined Task Data​

<script>
  import { Tasklist } from 'wx-svelte-tasklist';

  const value = [
        {
            id: 7,
            content: "Optimize performance in Svelte applications",
            status: 1,
        },
        {
            id: 8,
            content:
                "Work with API requests and data handling in Svelte applications",
            status: 0,
        }
  ];
</script>

<Tasklist {value} />

This method initializes the widget with a predefined list of tasks. The value array contains task objects, each with an id, content, and status. The status field indicates whether a task is completed (1) or not (0). This approach is suitable when there is a need to display an initial set of tasks, such as a default list or tasks saved locally. It eliminates the need for fetching data from an external source.

Data Management​

The Tasklist widget supports integration with different data sources for handling task data. Tasks can be loaded from a REST API or other data storage systems, saved back to these systems, and manipulated in various ways. These methods ensure flexibility, making the widget adaptable for diverse applications.

Loading Tasks from a REST API​

The widget can fetch tasks from a REST API using a helper method. This is useful when tasks are stored in a backend service that exposes a RESTful endpoint. The example below demonstrates how to configure the widget to load tasks from a specified URL.

<script>
  import { RestURL } from "wx-lib-data-provider";
  import { Tasklist } from 'wx-svelte-tasklist';

  const url = new RestURL("https://some.com/api/tasks");  
</script>

<Tasklist ondata={v => url.get(v)} />
  • The RestURL helper is used to define the API endpoint (https://some.com/api/tasks).
  • The ondata property of the Tasklist widget is set to fetch tasks using the get method of the RestURL.
  • This setup allows dynamic task loading whenever the widget is initialized or refreshed.

Saving Task Changes Locally​

The widget can save changes to tasks in local storage. This is suitable for scenarios where tasks are managed on the client side without involving a backend. The following example shows how to use local storage for saving task updates.

<script>
  import { Tasklist } from 'wx-svelte-tasklist';
</script>

<Tasklist
  value={1}
  ondata={v => localStorage.getItem(`tasks-${v}`)}
  onchange={({ value }) => 
    localStorage.setItem(`tasks-${value}`, JSON.stringify(value))}
/>
  • The value property specifies the identifier for the task list.
  • The ondata property retrieves tasks from local storage using the key tasks-{value}.
  • The onchange property saves changes back to local storage in JSON format when tasks are updated in the widget.

Loading and Saving Tasks via REST API with Comments​

The widget allows both loading tasks and saving changes, including handling comments, using a REST API. This is ideal when additional task metadata, such as comments, needs to be persisted on the backend.

<script>
  import { RestURL } from "wx-lib-data-provider";
  import { Tasklist } from 'wx-svelte-tasklist';

  const url = new RestURL("https://some.com/api/tasks");  
</script>

<Tasklist
  ondata={v => url.get(v)}
  onchange={({ action, task, id, originalValue: v }) => 
    url.path(v).save(action, task, id)}
/>
  • The ondata property fetches tasks from the API endpoint using the get method.
  • The onchange property handles saving task changes back to the API.
  • The save method in the onchange callback processes various actions (add, edit, delete) for tasks.
  • This setup ensures seamless synchronization between the client and backend.

Converting Task Stream ID to Data​

The widget can interpret a task stream ID and convert it into task data by fetching it from a backend service. This method is useful when tasks are identified by unique stream IDs, and the corresponding data is stored in the backend.

<script>
  import { Tasklist } from 'wx-svelte-tasklist';

  const ondata = (v) => {
    return fetch(`/api/tasks/${v}`).then(r => r.json());
  };
</script>

<Tasklist value={1} {ondata} />
  • The ondata function fetches task data from the backend using the stream ID (/api/tasks/{v}).
  • The fetch API is used to perform the HTTP GET request, and the response is parsed as JSON.
  • The ondata function can return either the data array or a promise resolving to the data array, allowing asynchronous handling.

Localization​

The widget supports localization, allowing developers to adapt the user interface to different languages. This is useful when the widget is used in applications targeting users from various regions or languages. Localization is achieved by providing translations for specific terms or phrases used in the widget.

Localizing the widget to another language​

<script>
    import { Locale } from "wx-svelte-core";
    import { Tasklist } from "wx-svelte-tasklist";
    
  const myLang = {
    "Add task": "Aufgabe hinzufügen",
    "Enter the task...": "Geben Sie die Aufgabe...",
  };
</script>

<Locale words={{ tasklist:myLang }}>
  <Tasklist />
</Locale>

This snippet demonstrates how to replace the default text in the Tasklist widget with translations for another language, in this case, German. The Locale component from wx-svelte-core is used to wrap the Tasklist widget and provide the localized text.

The myLang object contains key-value pairs where the keys are the default English phrases used in the widget, and the values are their respective translations. For example:

  • "Add task" is translated to "Aufgabe hinzufügen".
  • "Enter the task..." is translated to "Geben Sie die Aufgabe...".

This approach ensures that the widget displays the appropriate language for the target audience. Important to note:

  • The structure of the myLang object should match the keys used by the widget's internal localization system.
  • Ensure all necessary phrases are translated to avoid fallback to default text.
  • This functionality is entirely on the client side and does not require server interaction.

Event Handling​

The widget allows developers to manage events and states when tasks are added, updated, or deleted. It provides detailed information about each change, enabling precise control and tracking of task modifications. This functionality is essential for applications where task data needs to be monitored or synchronized with other systems.

Capturing Changes in Task Data​

The widget provides an event handler to detect and process changes in task data. This functionality can be used when the application needs to respond to additions, updates, or deletions in the task list. Each change action provides specific details about the modification, such as the type of action, the task data before and after changes, and the current state of the task list.

interface OnChange {
  // kind of change
  action: "add" | "update" | "delete";
  // id of changed task
  id?: number;
  // changed task
  task?: Task;
  // current tasks data
  data: Task[];
  // original tasks data
  originalValue: Task[] | number | string;
}
<script>
  import { Tasklist } from 'wx-svelte-tasklist';
  import { value } from './data.js';

  const onchange = ({ id, action, task, originalValue }) => {
    console.log(id, action, task, originalValue);
  };
</script>

<Tasklist {value} {onchange} />

The OnChange interface provides detailed information about the change:

  • action specifies the type of change ("add", "update", or "delete").
  • id contains the identifier of the task that was modified (not available for add operations).
  • task includes the task data that was changed (not available for delete operations).
  • data is the current state of the task list after the change.
  • originalValue reflects the initial state of the task list when it was first loaded into the widget. It can either be a task stream identifier or an array of task data.

This setup is useful in applications where task changes need to be logged, validated, or sent to a backend system for further processing. For example:

  • In "add" operations, the task property can be used to retrieve the newly created task details.
  • In "delete" operations, only the id of the removed task is provided.
  • The originalValue property helps compare the current state with the initial state, ensuring consistency or identifying discrepancies.

Display Options​

Options for displaying the widget.

Showing the Widget in Read-Only Mode​

<script>
  import { Tasklist } from 'wx-svelte-tasklist';
  import { value } from './data.js';
</script>

<Tasklist {value} readonly={true} />

This configuration is used when the task list should only be displayed without allowing any modifications. The readonly property is set to true, which disables editing, adding, or deleting tasks. This is useful for cases where the task list is meant to serve as a static reference, for example, when showing completed tasks in a report or when sharing a task list with users who should not have editing permissions. The value variable provides the data to be displayed in the widget.