Skip to content

reposition EOL note, remove VR classroom note #593

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 14 commits into
base: master
Choose a base branch
from
Draft

reposition EOL note, remove VR classroom note #593

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
a6373bd
reposition EOL note, remove VR classroom note
filipKovachev Jul 4, 2024
3b9a58c
remove yarn snipets to fix rendering
filipKovachev Jul 7, 2024
2e89b60
address feedback
filipKovachev Jul 23, 2024
b8c029c
add snippets
filipKovachev Jul 26, 2024
d7fedfc
Final review of GS w. JS and options API
yordan-mitev Aug 1, 2024
7cf463c
Apply suggestions from code review
yordan-mitev Aug 5, 2024
5986749
Merge pull request #601 from telerik/edit-getting-started-articles
yordan-mitev Aug 5, 2024
641b36d
modify steps and code snippets
filipKovachev Aug 6, 2024
321802a
Edit get-started-nuxt-3.md part1
yordan-mitev Aug 7, 2024
200316b
Add script block instructions
yordan-mitev Aug 7, 2024
df44109
Remove duplicate instructions in typescript-options-api.md
yordan-mitev Aug 8, 2024
4a4c501
fix snippets
filipKovachev Aug 19, 2024
579650e
Adjust basic component setup in typescript-composition-api.md
yordan-mitev Aug 21, 2024
859afb3
Update typescript-composition-api.md
yordan-mitev Aug 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
274 changes: 196 additions & 78 deletions docs/getting-started/get-started-nuxt-3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,6 @@ position: 100

# Get Started with Kendo UI for Vue

> Prefer video tutorials? How about a free Telerik UI onboarding course? Check out the [Kendo UI for Vue with TypeScript](https://learn.telerik.com/learn/course/internal/view/elearning/45/kendo-ui-for-vue-with-typescript) training in [Telerik Virtual Classroom](https://learn.telerik.com/learn).

This tutorial will help you develop a simple app that includes a native Vue Data Grid component. To achieve this, you will build a project using [Vite](https://vitejs.dev/) and the [Vue Composition API](https://vuejs.org/guide/introduction.html#composition-api) paired with [Nuxt 3](https://nuxt.com/docs/getting-started/introduction)


Expand All @@ -20,36 +18,37 @@ This tutorial will help you develop a simple app that includes a native Vue Data
>* [Kendo UI for Vue with JavaScript and the Options API](slug:getting_started_javascript_options_api)
>* [Kendo UI for Vue with TypeScript and the Options API](slug:getting_started_typescript_options_api)

> Historically, all Kendo UI for Vue Native components have supported both **Vue 2** and **Vue 3**. However, Kendo UI for Vue versions released after **November 2024** will no longer support Vue 2. For more information, see [Vue 2 End of Life](https://www.telerik.com/kendo-vue-ui/components/vue2-deprecation/).

## Create the Vue Project

1. Create a Nuxt project named `my-app`:

```sh
npx nuxi init my-app
```
```sh
npx nuxi init my-app
```

1. Select the NPM package manager.

> You can use both NPM and Yarn to create the project and import the Kendo UI for Vue components. This tutorial demonstrates only the NPM approach.

1. Run the newly created project by executing the following commands:

```
cd my-app
npm install
npm run dev
```
```
cd my-app
npm install
npm run dev
```

## Clean Up the Generated Project

Before you start playing with Kendo UI for Vue, clean up the sample app created by Nuxt:
Before you start playing with Kendo UI for Vue, clean up the Nuxt sample app:

1. Delete the `<NuxtWelcome />` line inside the `app.vue` file
1. Replace the `<NuxtWelcome />` line inside the `app.vue` file with `<NuxtPage/>`.
1. Delete everything in the `nuxt.config.ts` file.

## Add Application Data

Add dummy data needed by the components. Create folder `appdata` in the `src` folder. Add the following files to the `appdata` folder.

1. Create a new `appdata/categories.ts` file. Copy the content of [this GitHub file](https://github.com/telerik/kendo-vue/tree/master/getting-started-nuxt3/appdata/categories.ts) and paste it into the `categories.ts` file.

1. Create a new `appdata/products.ts` file. Copy the content of [this GitHub file](https://github.com/telerik/kendo-vue/tree/master/getting-started-nuxt3/appdata/products.ts) and paste it into the `products.ts` file.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As this is a single step where you add a single file, adjust the text so that it addresses this change:

Add the dummy data needed by the components:

  1. In the src folder, create a new folder called appdata.
  2. In the appdata folder, create a new file called products.ts.
  3. Copy the content of this GitHub file and paste it into the products.ts file.


## Install the Data Grid Component
Expand All @@ -59,11 +58,6 @@ Kendo UI for Vue is distributed as multiple NPM packages, scoped to `@progress`.
```sh
npm install --save @progress/kendo-vue-grid @progress/kendo-data-query @progress/kendo-licensing @progress/kendo-vue-animation @progress/kendo-vue-data-tools @progress/kendo-vue-dateinputs @progress/kendo-vue-dropdowns @progress/kendo-vue-inputs @progress/kendo-vue-indicators @progress/kendo-vue-intl @progress/kendo-vue-popup
```
<!---
```sh
yarn add @progress/kendo-vue-grid @progress/kendo-data-query @progress/kendo-licensing @progress/kendo-vue-animation @progress/kendo-vue-data-tools @progress/kendo-vue-dateinputs @progress/kendo-vue-dropdowns @progress/kendo-vue-inputs @progress/kendo-vue-indicators @progress/kendo-vue-intl @progress/kendo-vue-popup
```
--->

## Import the CSS Styles

Expand All @@ -74,94 +68,218 @@ Kendo UI for Vue includes [four artfully designed themes](slug:themesandstyles)
```sh
npm install --save @progress/kendo-theme-default
```
<!---
```sh
yarn add --save @progress/kendo-theme-default
```
--->

1. In the `nuxt.config.ts` file, import the CSS files provided by the installed theme package:

```js
import '@progress/kendo-theme-default/dist/all.css';
```ts
export default defineNuxtConfig({
css: [
'@progress/kendo-theme-default/dist/all.css',
],
})
```

>To add any custom styles to your app, insert a `<styles>` tag in the `src/App.vue` file and place your styles there.

## Add a Vue Data Grid Component


1. Now that you've installed all required packages, you are ready to add the Kendo UI for Vue Data Grid to the application.

```sh
npx nuxi add page KendoGrid
```

1. In the `pages/KendoGrid.vue` file, add a `<script>` block and import the Grid and its data:
```sh
npx nuxi add page KendoGrid
```

1. Add a `<script>` block to the `pages/KendoGrid.vue` file, import the Grid and its data. In addition, the `process` function from the [Data Query](https://www.telerik.com/kendo-vue-ui/components/dataquery/) package will allow you to apply data operations like sorting, paging, and filtering.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is an existing script tag in my version of the app. Maybe we need to add the new content inside the existing tags?


```js
import { productsData } from '../appdata/products';
import { process, DataResult, State, CompositeFilterDescriptor, SortDescriptor } from '@progress/kendo-data-query';
import { Grid as grid } from '@progress/kendo-vue-grid';
```
```js
<script>
import { productsData } from '../appdata/products';
import { process, type DataResult, type State, type SortDescriptor } from '@progress/kendo-data-query';
import { Grid as grid } from '@progress/kendo-vue-grid';
</script>
```

1. Add a `<template>` block with a simple heading and create a Data Grid. Bind it to the `products` data:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my version of the app, the template block exists and has some content. Should we add the new content in the existing block?

<template>
  <div>
    Page: KendoGrid
  </div>
</template>


```html
<grid
:data-items="products"
:columns="columns"
></grid>
```
```html
<template>
<h1>Hello Kendo UI for Vue with Nuxt 3!</h1>
<grid
:data-items="products"
:columns="columns"
></grid>
</template>
```

1. Add the Data Grid's data and columns in the `setup` section of the `KendoGrid.vue` file:
1. In the `<script>` section of the `pages\KendoGrid.vue` file:

```js
const products = productsData;
const columns = [
{ field: 'ProductName', title: 'Product Name' },
{ field: 'UnitPrice', title: 'Price' },
{ field: 'UnitsInStock', title: 'Units in Stock' },
{ field: 'Discontinued' }
] as GridColumnProps[];
```
* Load the `products` file.
* Define user friendly column names.

```js
const products = productsData;
const columns = [
{ field: 'ProductName', title: 'Product Name' },
{ field: 'UnitPrice', title: 'Price' },
{ field: 'UnitsInStock', title: 'Units in Stock' },
{ field: 'Discontinued' }
] as GridColumnProps[];
```

After completing all the steps above, your `KendoGrid.vue` will look like this:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • The first three imports should probably be in the <script> block.
  • The content of the code snippet must be indented because it isn't rendered as a code block.


```js
import { productsData } from '../appdata/products';
import { process, type DataResult, type State, type SortDescriptor } from '@progress/kendo-data-query';
import { Grid as grid, type GridColumnProps, type GridDataStateChangeEvent } from '@progress/kendo-vue-grid';

<script>
const products = productsData;
const columns = [
{ field: 'ProductName', title: 'Product Name' },
{ field: 'UnitPrice', title: 'Price' },
{ field: 'UnitsInStock', title: 'Units in Stock' },
{ field: 'Discontinued' }
] as GridColumnProps[];
</script>

<template>
<h1>Hello Kendo UI for Vue with Nuxt 3!</h1>
<grid :data-items="products" :columns="columns"></grid>
</template>
```

These steps let you render a very basic Grid by running `npm run dev` and navigating to the local URL displayed in the terminal.
This sample code lets you run an application with a very basic Grid:

1. Execute the `npm run dev` command.
1. Navigate to the local URL displayed in the terminal.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The app doesn't run with this code, multiple errors are thrown about KendoGrid.vue.


> Notice the `No valid license found` message and the watermark in the Grid. They are informational and encourage you to activate your trial or commercial license and to [add a license file to your application](slug:my_license_vue). Once you complete these licensing steps, the license message and the watermark will disappear.

Now that you have a running Grid, you are ready to use some of its basic features like sorting and paging:
## Configure the Vue Data Grid

Now that you have a running Grid, you are ready to use some of its basic features like sorting and paging.

1. In the Grid declaration, add [paging](slug:paging_grid), [sorting](slug:sorting_grid), and a height style that activates [scrolling](slug:scrollmmodes_grid).

```html
<template>
<h1>Hello Kendo UI for Vue!</h1>
<grid
:data-items="products"
:columns="columns"
:pageable="pageable"
:sortable="sortable"
:style="{ height: '400px' }"
></grid>
</template>
<template>
<h1>Hello Kendo UI for Vue with Nuxt 3!</h1>
<grid
:data-items="products"
:columns="columns"
:pageable="pageable"
:sortable="sortable"
:style="{ height: '400px' }"
></grid>
</template>
```


1. Implement the paging and sorting functionality in the `data` option:

* Set the [page size (`take`)](slug:api_grid_gridprops#toc-take) to 10.
* Set the initial [`skip`](slug:api_grid_gridprops#toc-skip) for the paging.
* Set the initial [sorting](slug:api_grid_gridprops#toc-sort) by Product name.
- Set the [page size (`take`)](slug:api_grid_gridprops#toc-take) to 10.
- Set the initial [`skip`](slug:api_grid_gridprops#toc-skip) for the paging.
- Set the initial [sorting](slug:api_grid_gridprops#toc-sort) by Product name.
- Set [`sortable`](slug:api_grid_gridprops#toc-sortable) to `true`.
- Set [`pageable`](slug:api_grid_gridprops#toc-pageable) to `true`.
- Initialize the `dataResult` empty array.

```js
const skip = ref<number | undefined>(0);
const take = ref<number | undefined>(10);
const sort = ref<SortDescriptor[] | undefined>([
{ field: "ProductName", dir: "asc" }
]);
```
```js
<script lang="ts">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The script tag changes its lang here. It is not consistent with the previous code snippets.

const skip = ref<number | undefined>(0);
const take = ref<number | undefined>(10);
const pageable = ref(true);
const sortable = ref(true);
const sort = ref<SortDescriptor[] | undefined>([
{ field: "ProductName", dir: "asc" }
]);
const columns = [
{ field: 'ProductName', title: 'Product Name' },
{ field: 'UnitPrice', title: 'Price' },
{ field: 'UnitsInStock', title: 'Units in Stock' },
{ field: 'Discontinued', cell: 'discontinuedTemplate' }
] as GridColumnProps[];
const dataResult = ref<DataResult>({ data: [] as any, total: 0 });
</script>
<template>
<grid
:data-items="dataResult"
:pageable="pageable"
:sortable="sortable"
:columns="columns"
:skip="skip"
:take="take"
:sort="sort"
></grid>
</template>
```

1. Inside the `onMounted` set the initial `dataState`. This allows the Grid to have the processed data ready for displaying when rendered for the first time.

```js
<script lang="ts" setup>
onMounted(() => {
const dataState: State = {
skip: skip.value,
take: take.value,
sort: sort.value,
};
dataResult.value = process(products, dataState);
});
```

1. Inside the `script` tag handle the `dataStateChange` event and implement a `createAppState` helper method:

* The `dataStateChange` event is triggered when the user interacts with the Grid and calls the `createAppState` helper method.
* The `createAppState` helper method will update the component's state based on the Grid's current data state (`skip`, `take`, `sort`).
* The `dataResult` is updated with the newly processed data and causes the Grid to re-render and display the data according to the new state.

```js
<script lang="ts" setup>

const createAppState = (dataState: State) => {
take.value = dataState.take;
skip.value = dataState.skip;
sort.value = dataState.sort;
};

const dataStateChange = (event: GridDataStateChangeEvent) => {
createAppState(event.data);
dataResult.value = process(products, {
skip: event.data.skip,
take: event.data.take,
sort: event.data.sort,
});
};

</script>
```

1. Re-define the Grid declaration to allow paging and sorting:

* Set Grid data to `data-items="dataResult"`&mdash;With paging enabled, the `data` option must contain only the items for the current page.
* Set the `pageable` and `sortable` props.
* Set the `skip`, `take`, and `sort` props that configure paging and sorting.
* Bind the `@datastatechange` event of the Grid to the `dataStateChange` method to handle the user interactions.

```html
<template>
<grid
:data-items="dataResult"
:pageable="pageable"
:sortable="sortable"
:columns="columns"
:skip="skip"
:take="take"
:sort="sort"
@datastatechange="dataStateChange"
></grid>
</template>
```

That's it. You now have a Data Grid configured for paging and sorting.

> Historically, all Kendo UI for Vue native components have supported both **Vue 2** and **Vue 3**. However, Kendo UI for Vue versions released after **November 2024** will no longer support Vue 2. For more information, see [Vue 2 End of Life](https://www.telerik.com/kendo-vue-ui/components/vue2-deprecation/).

## Get the Complete Source Code

Expand Down
Loading
Loading