UIXpress Documentation

https://docs.uipress.co
Admin
Transform your WordPress admin experience with a modern, dark-mode-first interface, powerful APIs,...
Tokens:84,608
Snippets:1,458
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Vue Component Example

Source: https://docs.uipress.co/api/sidebar-render-api

A basic Vue 3 component example using `<script setup>` and template syntax. It accepts props for dynamic styling and data.

```vue
<script setup>
import { defineProps } from 'vue';
import { useAppStore } from '@/store/app/app.js';

const props = defineProps({
  appData: Object,
  id: String,
  className: String,
});

const appStore = useAppStore();
</script>

<template>
  <div :class="className" class="p-4 bg-zinc-50 dark:bg-zinc-800 rounded-lg">
    <h3 class="text-sm font-semibold text-zinc-900 dark:text-zinc-100 mb-2">
      My Custom Widget
    </h3>
    <p class="text-xs text-zinc-600 dark:text-zinc-400">
      This component appears before the menu items.
    </p>
  </div>
</template>

```

--------------------------------

### Example Remote Site Configuration

Source: https://docs.uipress.co/remote-sites/setup

This is an example of how to configure a remote site, including the site URL, username, and an optional site name.

```text
Site URL: https://staging.example.com
Username: admin
Application Password: xxxx xxxx xxxx xxxx xxxx xxxx
Site Name: Staging Site (optional)

```

--------------------------------

### Vue Component Lifecycle and Data Fetching

Source: https://docs.uipress.co/api/user-details-components-api

Example of a Vue component's script setup, including importing necessary functions, defining props, managing component state (data, loading, error), fetching data using lmnFetch, and watching for prop changes.

```javascript
<script setup>
import { ref, computed, onMounted, watch } from 'vue';
import { lmnFetch } from '@/assets/js/functions/lmnFetch.js';

const props = defineProps({
  userId: { type: [String, Number], required: true },
  userData: { type: Object, required: true },
  appData: { type: Object, required: true },
});

// Component state
const data = ref([]);
const loading = ref(false);
const error = ref(null);

// Load data function
const loadData = async () => {
  loading.value = true;
  try {
    const args = {
      endpoint: `wp/v2/users/${props.userId}/custom-endpoint`,
    };
    const response = await lmnFetch(args);
    data.value = response.data;
  } catch (err) {
    error.value = err.message;
  } finally {
    loading.value = false;
  }
};

// Watch for user ID changes
watch(
  () => props.userId,
  () => {
    loadData();
  }
);

// Watch for user data changes
watch(
  () => props.userData,
  () => {
    // React to user data changes
  },
  { deep: true }
);

// Load data on mount
onMounted(() => {
  loadData();
});
</script>

```

--------------------------------

### Complete Dashboard Customization Example

Source: https://docs.uipress.co/api/dashboard-cards-api

A comprehensive example demonstrating how to simultaneously reorder categories and filter out specific cards. This combines category sorting and card removal for a fully customized dashboard.

```javascript
document.addEventListener("uixpress/dashboard/ready", () => {
  const { addFilter } = window.uixpress;

  // Reorder categories - put Analytics first
  addFilter("uixpress/dashboard/categories/register", (categories) => {
    return categories.sort((a, b) =>
      a.value === "analytics" ? -1 : b.value === "analytics" ? 1 : 0
    );
  });

  // Filter out specific cards
  addFilter("uixpress/dashboard/cards/register", (widgets) => {
    return widgets.filter((widget) => {
      return !(widget.metadata && widget.metadata.id === "server-health");
    });
  });
});

```

--------------------------------

### Vue Component Script Setup

Source: https://docs.uipress.co/api/user-details-components-api

The script setup for a Vue component, defining props for user ID, user data, app data, and component ID.

```vue
<script setup>
import { ref, computed, onMounted, watch } from 'vue';

const props = defineProps({
  userId: {
    type: [String, Number],
    required: true,
  },
  userData: {
    type: Object,
    required: true,
  },
  appData: {
    type: Object,
    required: true,
  },
  id: {
    type: String,
    required: true,
  },
});

// Your component logic here
</script>

<template>
  <!-- Your component template -->
</template>

```

--------------------------------

### Get All Capabilities

Source: https://docs.uipress.co/role-editor/summary

Retrieves a list of all available capabilities.

```APIDOC
## GET /uixpress/v1/role-editor/capabilities

### Description
Retrieves a list of all available capabilities.

### Method
GET

### Endpoint
/uixpress/v1/role-editor/capabilities
```

--------------------------------

### Vue Component Example for Toolbar

Source: https://docs.uipress.co/api/toolbar-render-api

A sample Vue 3 component designed to be used within the toolbar. It includes basic setup, props, and a template for a button with an icon.

```vue
<script setup>
import { defineProps } from 'vue';
import { useAppStore } from '@/store/app/app.js';
import AppButton from '@/components/utility/app-button/index.vue';
import AppIcon from '@/components/utility/icons/index.vue';

const props = defineProps({
  appData: Object,
  id: String,
  className: String,
});

const appStore = useAppStore();

const handleClick = () => {
  // Your custom action
  console.log('Toolbar button clicked');
};
</script>

<template>
  <AppButton
    type="transparent"
    :title="__('My Custom Button', 'uixpress')"
    @click="handleClick"
    :class="className"
  >
    <AppIcon icon="settings" class="text-xl" />
  </AppButton>
</template>

```

--------------------------------

### React Card Metadata Example

Source: https://docs.uipress.co/api/dashboard-cards-api

Defines the metadata for a React-based dashboard card. Ensure 'language' is set to 'react'.

```javascript
export default {
  id: 'react-analytics',
  title: 'React Analytics',
  description: 'Analytics built with React',
  width: 6,
  mobileWidth: 12,
  language: 'react', // Important: Set to 'react' for React components
  category: 'analytics',
  requires_capabilities: ['manage_options'],
};
```

--------------------------------

### Example Safe Query Construction

Source: https://docs.uipress.co/database-explorer/security

Demonstrates secure table name handling by validating and escaping before interpolation into a SQL query.

```php
// Validate table name
$validated = self::validate_table_name($table_name);
if (!$validated) return error;

// Escape after validation
$escaped = esc_sql($table_name);

// Use in query
$query = "SELECT * FROM `{$escaped}`";

```

--------------------------------

### Usage Examples

Source: https://docs.uipress.co/api/uixpress-core-stop-filter

Demonstrates various ways to use the 'uixpress/core/stop' filter to conditionally stop UiXpress based on different criteria.

```APIDOC
## Usage Examples
### Always Stop UiXpress
```php
add_filter('uixpress/core/stop', '__return_true');
```

### Stop UiXpress on Specific Pages
```php
add_filter('uixpress/core/stop', function($should_stop, $action) {
    $screen = get_current_screen();
    
    if ($screen && $screen->id === 'my-custom-page') {
        return true; // Stop UiXpress on this page
    }
    
    return $should_stop; // Keep default behavior
}, 10, 2);
```

### Stop UiXpress Based on User Role
```php
add_filter('uixpress/core/stop', function($should_stop, $action) {
    $current_user = wp_get_current_user();
    
    // Stop UiXpress for subscribers
    if (in_array('subscriber', $current_user->roles)) {
        return true;
    }
    
    return $should_stop;
}, 10, 2);
```

### Stop UiXpress Based on URL Parameters
```php
add_filter('uixpress/core/stop', function($should_stop, $action) {
    // Stop UiXpress when a specific parameter is present
    if (isset($_GET['disable_uixpress']) && $_GET['disable_uixpress'] === '1') {
        return true;
    }
    
    return $should_stop;
}, 10, 2);
```

### Stop UiXpress for Specific Post Types
```php
add_filter('uixpress/core/stop', function($should_stop, $action) {
    global $post_type;
    
    // Stop UiXpress when editing specific post types
    $disabled_types = ['product', 'order'];
    
    if (isset($post_type) && in_array($post_type, $disabled_types)) {
        return true;
    }
    
    return $should_stop;
}, 10, 2);
```

### Conditional Stop Based on Plugin State
```php
add_filter('uixpress/core/stop', function($should_stop, $action) {
    // Stop UiXpress if another plugin is active
    if (is_plugin_active('conflicting-plugin/conflicting-plugin.php')) {
        return true;
    }
    
    return $should_stop;
}, 10, 2);
```

### Stop UiXpress During Maintenance Mode
```php
add_filter('uixpress/core/stop', function($should_stop, $action) {
    // Stop UiXpress if site is in maintenance mode
    if (defined('WP_MAINTENANCE_MODE') && WP_MAINTENANCE_MODE) {
        return true;
    }
    
    return $should_stop;
}, 10, 2);
```

### Combine Multiple Conditions
```php
add_filter('uixpress/core/stop', function($should_stop, $action) {
    $screen = get_current_screen();
    $current_user = wp_get_current_user();
    
    // Stop UiXpress if:
    // 1. On a specific screen, OR
    // 2. User has a specific role, OR
    // 3. A custom option is enabled
    if (
        ($screen && $screen->id === 'my-custom-page') ||
        in_array('subscriber', $current_user->roles) ||
        get_option('my_plugin_disable_uixpress', false)
    ) {
        return true;
    }
    
    return $should_stop;
}, 10, 2);
```
```

--------------------------------

### React Component Example

Source: https://docs.uipress.co/api/sidebar-render-api

A functional React component example with JSDoc comments for props. It uses template literals for conditional CSS classes.

```javascript
import React from 'react';

/**
 * Post-menu React component
 * @param {Object} props - Component props
 * @param {Object} props.appData - App store instance
 * @param {string} props.id - Component ID
 * @param {string} props.className - CSS classes
 */
const MyPostMenuComponent = ({ appData, id, className }) => {
  return (
    <div className={`p-4 bg-zinc-50 dark:bg-zinc-800 rounded-lg ${className || ''}`}>
      <h3 className="text-sm font-semibold text-zinc-900 dark:text-zinc-100 mb-2">
        My Custom Widget
      </h3>
      <p className="text-xs text-zinc-600 dark:text-zinc-400">
        This component appears after the menu items.
      </p>
    </div>
  );
};

export default MyPostMenuComponent;

```

--------------------------------

### Register Components After Toolbar Ready

Source: https://docs.uipress.co/api/toolbar-render-api

Listen for the `uixpress/toolbar/ready` event before registering components to ensure the toolbar is initialized. This example shows a basic registration without adding specific components.

```javascript
document.addEventListener('uixpress/toolbar/ready', () => {
  // Toolbar component is ready, safe to register components
  addFilter('uixpress/toolbar/render/right', (components) => {
    // Register your components
    return components;
  });
});

```

--------------------------------

### Example Capabilities for Access Control

Source: https://docs.uipress.co/remote-sites/setup

Illustrates different WordPress capabilities that can be used to control access to remote sites, ranging from administrator-only to custom roles.

```text
manage_options - Administrators only
edit_posts - Editors and above
publish_posts - Authors and above
Custom capability - Your custom role

```

--------------------------------

### Vue Card Metadata Example

Source: https://docs.uipress.co/api/dashboard-cards-api

Defines the metadata for a Vue-based dashboard card. Ensure 'language' is set to 'vue'.

```javascript
export default {
  id: 'user-analytics',
  title: 'User Analytics',
  description: 'Track user engagement and activity',
  width: 6,
  mobileWidth: 12,
  language: 'vue',
  category: 'site',
  requires_capabilities: ['manage_options', 'edit_users'],
};
```

--------------------------------

### React Component Metadata Example

Source: https://docs.uipress.co/api/user-details-components-api

Configure metadata for a React user component, specifying its ID, title, category, language, and required capabilities. Ensure the language is set to 'react'.

```javascript
export default {
  id: 'user-social-links',
  title: 'Social Links',
  category: 'details',
  language: 'react', // Important: Set to 'react' for React components
  requires_capabilities: ['edit_users'],
};

```

--------------------------------

### Handle User Capabilities

Source: https://docs.uipress.co/api/toolbar-render-api

Conditionally render toolbar components based on user capabilities. This example shows how to restrict access to administrators using the 'manage_options' capability.

```json
{
  metadata: {
    requires_capabilities: ['manage_options'],
  }
}
```

--------------------------------

### Vue Component Metadata Example

Source: https://docs.uipress.co/api/user-details-components-api

Configure metadata for a Vue user component, specifying its ID, title, category, language, and required capabilities.

```javascript
export default {
  id: 'user-profile-info',
  title: 'Profile Info',
  category: 'details',
  language: 'vue',
  requires_capabilities: ['edit_users'],
};

```

--------------------------------

### Adding Components to the Toolbar

Source: https://docs.uipress.co/api/toolbar-render-api

Demonstrates how to use the `addFilter` function to register custom components to the toolbar. It shows examples of adding components with high and low priorities to control their rendering order.

```APIDOC
## Using Priority to Control Order

This section illustrates how to use the `addFilter` function to insert custom components into the toolbar. The priority argument in `addFilter` determines the rendering order, where a lower number indicates higher priority (runs earlier).

### Example 1: High Priority (Runs First)
```javascript
import { addFilter } from '@/assets/js/functions/HooksSystem.js';

addFilter(
  'uixpress/toolbar/render/right',
  (components) => {
    return [
      {
        metadata: {
          id: 'my-plugin/important-button',
          language: 'vue',
        },
        component: ImportantComponent,
      },
      ...components,
    ];
  },
  5 // Low priority number = runs first
);
```

### Example 2: Low Priority (Runs Last)
```javascript
import { addFilter } from '@/assets/js/functions/HooksSystem.js';

addFilter(
  'uixpress/toolbar/render/right',
  (components) => {
    return [
      ...components,
      {
        metadata: {
          id: 'my-plugin/less-important-button',
          language: 'vue',
        },
        component: LessImportantComponent,
      },
    ];
  },
  20 // High priority number = runs last
);
```

## Component Props

Components registered via the toolbar API receive the following props:

### Vue Components
* **`appData`**(Object): The app store instance (Pinia store).
* **`id`**(String): Component ID from metadata.
* **`className`**(String): CSS classes from metadata.

### React Components
* **`appData`**(Object): The app store instance (Pinia store).
* **`id`**(String): Component ID from metadata.
* **`className`**(String): CSS classes from metadata.
```

--------------------------------

### View Command Syntax Help

Source: https://docs.uipress.co/search/search_features

Use the '?help' command prefix to display information about available command syntax and filters.

```text
?help
```

--------------------------------

### Show Quick Actions

Source: https://docs.uipress.co/search/search_features

Use the '!action' command prefix to display a list of available quick actions within the command palette.

```text
!action
```

--------------------------------

### Combined Search and Quick Actions

Source: https://docs.uipress.co/global-search/command-syntax

Demonstrates combining search prefixes with queries for more specific results, and using the '!' prefix for quick actions.

```text
>post wordpress - Posts containing "wordpress"
@user smith - Users with "smith" in name/email
#category tech - Categories with "tech" in name
```

```text
!action - All quick actions
!action new - Actions with "new" in name
!action post - Actions related to posts
```

--------------------------------

### Get Role Details

Source: https://docs.uipress.co/role-editor/summary

Retrieves the details of a specific role.

```APIDOC
## GET /uixpress/v1/role-editor/role/{role}

### Description
Retrieves the details of a specific role.

### Method
GET

### Endpoint
/uixpress/v1/role-editor/role/{role}

### Parameters
#### Path Parameters
- **role** (string) - Required - The name or identifier of the role to retrieve.
```

--------------------------------

### Toolbar Ready Event

Source: https://docs.uipress.co/api/toolbar-render-api

This section explains how to listen for the `uixpress/toolbar/ready` event to ensure the toolbar component is initialized before attempting to register new components.

```APIDOC
## Event System

The toolbar component dispatches a custom event when it's ready for plugin registration. This ensures that your components are added only after the toolbar has been fully initialized.

### Listening for Toolbar Ready Event
```javascript
document.addEventListener('uixpress/toolbar/ready', () => {
  // Toolbar component is ready, safe to register components
  // Example: addFilter('uixpress/toolbar/render/right', (components) => {
  //   // Register your components here
  //   return components;
  // });
});
```
```

--------------------------------

### Help Command

Source: https://docs.uipress.co/global-search/command-syntax

Use the '?' prefix followed by 'help' to access command syntax information.

```text
?help - Command syntax help
```

--------------------------------

### Get table data

Source: https://docs.uipress.co/database-explorer/summary

Retrieves data from a specific table.

```APIDOC
## GET /uixpress/v1/database/tables/{table}/data

### Description
Retrieves data from a specific table.

### Method
GET

### Endpoint
/uixpress/v1/database/tables/{table}/data

### Parameters
#### Path Parameters
- **table** (string) - Required - The name of the table.
```

--------------------------------

### Get table structure

Source: https://docs.uipress.co/database-explorer/summary

Retrieves the structure of a specific table.

```APIDOC
## GET /uixpress/v1/database/tables/{table}/structure

### Description
Retrieves the structure of a specific table.

### Method
GET

### Endpoint
/uixpress/v1/database/tables/{table}/structure

### Parameters
#### Path Parameters
- **table** (string) - Required - The name of the table.
```

--------------------------------

### Register Quick Actions on Search Ready

Source: https://docs.uipress.co/api/quick-actions-api

Listen for the 'uixpress/search/ready' event to safely register custom quick actions. This ensures the search component is initialized before attempting to add actions.

```javascript
document.addEventListener('uixpress/search/ready', () => {
  // Search component is ready, safe to register actions
  addFilter('uixpress/search/quickActions/register', (actions) => {
    // Register your actions
    return actions;
  });
});

```

--------------------------------

### Get table row count

Source: https://docs.uipress.co/database-explorer/summary

Retrieves the total number of rows in a specific table.

```APIDOC
## GET /uixpress/v1/database/tables/{table}/count

### Description
Retrieves the total number of rows in a specific table.

### Method
GET

### Endpoint
/uixpress/v1/database/tables/{table}/count

### Parameters
#### Path Parameters
- **table** (string) - Required - The name of the table.
```

--------------------------------

### Search for Users

Source: https://docs.uipress.co/search/search_features

Use the '@user' command prefix to search for specific users within the WordPress installation.

```text
@user admin
```

--------------------------------

### Dashboard Category URL Structure

Source: https://docs.uipress.co/dashboard/system-features

Example of how a dashboard category is represented in the URL. The 'dashboard_category' query parameter determines the active category.

```url
/wp-admin/index.php?dashboard_category=analytics

```

--------------------------------

### Get Single Log

Source: https://docs.uipress.co/activity-logger/features

Retrieves a detailed view of a specific log entry, including full metadata and enhanced user data.

```APIDOC
## GET /logs/{id}

### Description
Retrieves a single log entry by its ID, providing detailed information and enhanced user data.

### Method
GET

### Endpoint
/logs/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the log entry.

### Response
#### Success Response (200)
- **log** (object) - The detailed log entry.
- **user_data** (object) - Enhanced user information.

#### Response Example
{
  "log": {
    "id": 1,
    "action": "User logged in",
    "timestamp": "2023-10-27T10:00:00Z",
    "user_id": 123,
    "details": "User logged in successfully.",
    "metadata": {
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0..."
    }
  },
  "user_data": {
    "123": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "avatar": "http://example.com/avatar.jpg"
    }
  }
}
```

--------------------------------

### Get Logs

Source: https://docs.uipress.co/activity-logger/features

Retrieves a list of activity logs with support for pagination, filtering, searching, and sorting. Includes enhanced user data.

```APIDOC
## GET /logs

### Description
Retrieves a paginated list of activity logs. Supports filtering, searching, and sorting.

### Method
GET

### Endpoint
/logs

### Query Parameters
- **page** (integer) - Optional - The page number for pagination.
- **limit** (integer) - Optional - The number of logs per page.
- **filter** (string) - Optional - Criteria to filter logs.
- **search** (string) - Optional - Search term for logs.
- **sort** (string) - Optional - Field to sort logs by.

### Response
#### Success Response (200)
- **logs** (array) - Array of log entries.
- **total** (integer) - Total number of logs.
- **user_data** (object) - Enhanced user information associated with logs.

#### Response Example
{
  "logs": [
    {
      "id": 1,
      "action": "User logged in",
      "timestamp": "2023-10-27T10:00:00Z",
      "user_id": 123,
      "details": "User logged in successfully."
    }
  ],
  "total": 100,
  "user_data": {
    "123": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "avatar": "http://example.com/avatar.jpg"
    }
  }
}
```

--------------------------------

### Overview Card Data Loading Logic

Source: https://docs.uipress.co/dashboard/cards/overview-cards

This snippet demonstrates the common data loading pattern for overview cards, including state management for data, loading, and errors, and watching for date range changes. It's essential for cards that fetch data dynamically.

```javascript
// Props
const props = defineProps({
  dateRange: { type: Array, required: true },
  appData: { type: Object, required: true },
});

// State
const data = ref([]);
const loading = ref(false);
const error = ref(null);

// Data Loading
const loadData = async () => {
  loading.value = true;
  try {
    // Fetch data based on dateRange
  } catch (err) {
    error.value = err.message;
  } finally {
    loading.value = false;
  }
};

// Watch date range changes
watch(() => props.dateRange, loadData, { deep: true });

// Load on mount
onMounted(loadData);

```

--------------------------------

### Overview Card Metadata Configuration

Source: https://docs.uipress.co/dashboard/cards/overview-cards

This snippet shows the standard metadata configuration for an overview card, including its ID, title, description, and layout properties for different screen sizes. This configuration is required for each card to be recognized and rendered correctly.

```javascript
export default {
  id: 'card-id',
  title: 'Card Title',
  description: 'Card description',
  width: 4, // 1-12 columns
  mobileWidth: 12,
  category: 'site',
  requires_capabilities: ['manage_options'], // Optional
};

```

--------------------------------

### Chart.js Setup for Vue

Source: https://docs.uipress.co/dashboard/cards/analytics-cards

Configures Chart.js for use within a Vue.js application. Imports and registers necessary Chart.js components for line charts.

```javascript
// Chart.js setup for visualizations
import { Line } from 'vue-chartjs';
import {
  Chart as ChartJS,
  CategoryScale,
  LinearScale,
  PointElement,
  LineElement,
  Title,
  Tooltip,
  Legend,
  Filler,
} from 'chart.js';

ChartJS.register(
  CategoryScale,
  LinearScale,
  PointElement,
  LineElement,
  Title,
  Tooltip,
  Legend,
  Filler
);

```

--------------------------------

### Extracting Date Range in React

Source: https://docs.uipress.co/api/dashboard-cards-api

Converts the start and end dates from the 'dateRange' prop to ISO string format for use in React components.

```javascript
const startDate = dateRange[0].toISOString();
const endDate = dateRange[1].toISOString();
```

--------------------------------

### Registering a New Quick Action

Source: https://docs.uipress.co/api/quick-actions-api

Add a new quick action to the list by returning a new array that includes the existing actions and your custom action. Ensure the `id`, `name`, `icon`, and `action` properties are correctly defined.

```javascript
import { addFilter } from '@/assets/js/functions/HooksSystem.js';
// Or use window.uixpress.addFilter if outside Vue app

addFilter('uixpress/search/quickActions/register', (actions) => {
  return [
    ...actions,
    {
      id: 'my-plugin/create-product',
      name: __('Create Product', 'my-plugin'),
      icon: 'add',
      action: () => {
        window.location.href = '/wp-admin/post-new.php?post_type=product';
      },
    },
  ];
});

```

--------------------------------

### Extracting Date Range in Vue

Source: https://docs.uipress.co/api/dashboard-cards-api

Converts the start and end dates from the 'dateRange' prop to ISO string format for use in Vue components.

```javascript
const startDate = props.dateRange[0].toISOString();
const endDate = props.dateRange[1].toISOString();
```
Tokens:
Raw