Skip to content

Commit

Permalink
documentation completed
Browse files Browse the repository at this point in the history
  • Loading branch information
Etienne Moureton committed Mar 11, 2024
1 parent 0e7fc3b commit 4128d05
Show file tree
Hide file tree
Showing 11 changed files with 271 additions and 153 deletions.
34 changes: 27 additions & 7 deletions docs/.vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,46 @@ import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: "Nuxt WP",
description: "nuxt-wp package description",
description: "Easy to use Nuxt 3 module to fetch data from WordPress REST API.",
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
nav: [
{ text: 'Home', link: '/' },
{ text: 'Examples', link: '/markdown-examples' }
{ text: 'Get started', link: '/introduction/getting-started' }
],

sidebar: [
{
text: 'Examples',
text: 'Introduction',
items: [
{ text: 'Markdown Examples', link: '/markdown-examples' },
{ text: 'Runtime API Examples', link: '/api-examples' }
{ text: 'Get started', items: [
{ text: "Prerequisites", link: '/introduction/getting-started#prerequisites' },
{ text: "Installation", link: '/introduction/getting-started#installation' },
] },
{ text: 'Options', items: [
{ text: "Available options", link: '/introduction/options#available-options' },
{ text: "Set options", link: '/introduction/options#set-options' }
] }
]
},
{
text: 'Composables',
items: [
{ text: 'useWpMenu', link: "composables/useWpMenu" },
{ text: 'useWpPage', link: "composables/useWpPage" },
{ text: 'useWpPost', link: "composables/useWpPost" },
{ text: 'useWpPosts', link: "composables/useWpPosts" },
]
},
{
text: 'Components',
items: [
{ text: 'WpCF7Form', link: "components/WpCF7Form" },
]
}
],

socialLinks: [
{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }
{ icon: 'github', link: 'https://github.com/YsarocK/nuxt-ws' }
]
}
})
49 changes: 0 additions & 49 deletions docs/api-examples.md

This file was deleted.

65 changes: 65 additions & 0 deletions docs/components/WpCF7Form.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# WpCF7Form

::: warning
Requires [Application Credentials](/introduction/getting-started.html#config)
:::

The `WpCF7Form` component is used to create a form using the Contact Form 7 plugin in WordPress.

### Usage

```vue
<WpCF7Form :id="formId" :wpcf7_unit_tag="unitTag" />
```

### Props

- `id` (string | number): The ID of the form to be fetched from the WordPress API.
- `wpcf7_unit_tag` (string): The unit tag for the form.

### Behavior

The `WpCF7Form` component fetches the form data from the WordPress API using the provided `id`. It then renders the form fields based on the fetched data. The form submission is handled by the `handleSubmit` function, which sends a POST request to the `/api/submit-form` endpoint with the form data.

### Error Handling

If there are any errors during the form submission, the error messages will be displayed next to the corresponding form fields.

### Styling

The `WpCF7Form` component uses the following CSS classes for styling:

- `wpcf`: This class is applied to the form element.
- `wpcf-field`: This class is applied to each form field.
- `wpcf-field--${field.type}`: This class is applied to each form field, where `${field.type}` is the type of the form field (e.g., `text`, `email`, `submit`, etc.).
- `wpcf-field-error`: This class is applied to the error message of each form field.

You can override these classes in your CSS to customize the appearance of the form. For example:

```css
.wpcf {
/* styles for the form */
}

.wpcf-field {
/* styles for the form fields */
}

.wpcf-field--text {
/* styles for text fields */
}

.wpcf-field--email {
/* styles for email fields */
}

.wpcf-field--submit {
/* styles for submit button */
}

.wpcf-field-error {
/* styles for error messages */
}
```

Please note that these styles should be scoped to the component where the `WpCF7Form` is used to avoid affecting other components.
16 changes: 16 additions & 0 deletions docs/composables/useWpMenu.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# useWpMenu

::: warning
Requires [Application Credentials](/introduction/getting-started.html#config)
:::

`useWpMenu` is a composable function that fetches a WordPress menu by its ID. It returns a Promise that resolves to a `Menu` object.

## Usage
```ts
const menu = await useWpMenu({ menuId })
```

## Parameters

- `menuId` (number): The ID of the WordPress menu to fetch.
12 changes: 12 additions & 0 deletions docs/composables/useWpPage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# useWpPage

`useWpPage` is a composable function that fetches a WordPress page by its slug. It returns a Promise that resolves to a `Page` object.

## Usage
```ts
const page = await useWpPage({ slug })
```

## Parameters

- `slug` (string, optional): The slug of the WordPress page to fetch. If not provided, the current route path will be used.
13 changes: 13 additions & 0 deletions docs/composables/useWpPost.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# useWpPost

`useWpPost` is a composable function that fetches a WordPress post by its slug. It returns a Promise that resolves to a `Post` object.

## Usage
```ts
const post = await useWpPost({ type, slug })
```

## Parameters

- `type` (string, optional): The type of the WordPress post to fetch. Defaults to 'posts'.
- `slug` (string, optional): The slug of the WordPress post to fetch. If not provided, the current route path will be used.
14 changes: 14 additions & 0 deletions docs/composables/useWpPosts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# useWpPosts

`useWpPosts` is a composable function that fetches a list of WordPress posts. It returns a Promise that resolves to an array of `Post` objects.

## Usage
```ts
const posts = await useWpPosts({ type, maxItems, categories })
```

## Parameters

- `type` (string, optional): The type of the WordPress posts to fetch. Defaults to 'posts'.
- `maxItems` (number, optional): The number of posts to fetch. Defaults to 6.
- `categories` (Array, optional): Array of categories to filter by.
27 changes: 15 additions & 12 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,25 @@ layout: home

hero:
name: "Nuxt WP"
text: "nuxt-wp package description"
tagline: My great project tagline
text: "Wordpress x Nuxt 3"
tagline: An easy way to query pages, posts or menu and to handle forms.
actions:
- theme: brand
text: Markdown Examples
link: /markdown-examples
text: Get started
link: /introduction/getting-started
- theme: alt
text: API Examples
link: /api-examples
text: Github
link: https://github.com/YsarocK/nuxt-wp

features:
- title: Feature A
details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
- title: Feature B
details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
- title: Feature C
details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
- title: Easy queries
icon: 💡
details: Get pages, posts data based on current or provided slug. Get posts by categories.
- title: Handles menu
icon: 🧭
details: Retrieves your menus.
- title: Contact Form 7 support
icon: ✉️
details: Displays a form based on your CF7 config and submit it automatically through API.
---

82 changes: 82 additions & 0 deletions docs/introduction/getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Getting Started

## Prerequisites

- [Node.js](https://nodejs.org/) version 18 or higher.
- An accessible Wordpress instance, with API enabled.
- <Badge type="warning" text="Optional" /> [Wordpress Application credentials](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/) to use advanced features :
- Menus
- Contact form

## Installation


### Setup

::: code-group

```sh [npm]
$ npm add -D nuxt-wp
```

```sh [pnpm]
$ pnpm add -D nuxt-wp
```

```sh [yarn]
$ yarn add -D nuxt-wp
```

```sh [bun]
$ bun add -D nuxt-wp
```
:::

::: code-group
```ts [nuxt-config.ts]
export default defineNuxtConfig({
modules: ['nuxt-wp'],
})
```
:::



### Config

In order to work, you need to provide the API endpoint :

::: code-group

```sh [.env]
WP_API_ENDPOINT=https://your-wordpress-site.com/wp-json
```

```ts [nuxt-config.ts]
export default defineNuxtConfig({
wordpress:{
apiEndpoint: 'https://your-wordpress-site.com/wp-json',
},
})
```
:::

If you want to use advances features, you need to provide Application Credentials too :

::: code-group
```sh [.env]
WP_API_ENDPOINT=https://your-wordpress-site.com/wp-json
WP_APPLICATION_USER=your-username
WP_APPLICATION_PASSWORD=your-password
```

```ts [nuxt-config.ts]
export default defineNuxtConfig({
wordpress:{
apiEndpoint: 'https://your-wordpress-site.com/wp-json',
applicationUser: 'your-username',
applicationPassword: 'your-password'
},
})
```
:::
27 changes: 27 additions & 0 deletions docs/introduction/options.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Options

## Available options

| Option | Type | Default | Required | Description |
|-----------------------|----------|---------|----------|-----------------------------------------------------------------------------|
| `apiEndpoint` | string | `''` | Yes | The endpoint of your WordPress API. |
| `additionalQueryParams` | string | `'&acf?_embed'` | No | Additional query parameters to append to the API requests. |
| `applicationUser` | string | `''` | No | The username for the WordPress application. |
| `applicationPassword` | string | `''` | No | The password for the WordPress application. |

## Set options
::: code-group
```ts [nuxt-config.ts]
export default defineNuxtConfig({
modules: ['nuxt-wp', {
// options
}],

// Or

wordpress: {
// options
}
})
```
:::
Loading

0 comments on commit 4128d05

Please sign in to comment.