# General
SleekPixel is a powerful WordPress plugin that transforms how you create and manage dynamic images for your website. Using an intuitive drag-and-drop editor directly within the WordPress Admin dashboard, you can design beautiful, dynamic images without writing complex code. These images automatically update based on your WordPress content, making it perfect for social media previews, featured images, and more.
## Key Features
- **Dynamic Image Generation**: Create images that automatically update with your content changes
- **Drag-and-Drop Editor**: Design images easily with a user-friendly interface
- **Multiple Output Types**: Generate images for: - Open Graph (Facebook)
- Twitter Cards
- Featured Images
- Combined Social Media Images
- **Smart Text Handling**: Automatic text scaling and alignment for varying content lengths
- **Google Fonts Integration**: Access to the entire Google Fonts library
- **Flexible Locations**: Control where and when your dynamic images appear
- **Template System**: Save and reuse designs across your website
- **Custom Data Support**: Extend functionality with your own dynamic data sources
- **Optimization Options**: Choose between different image formats and processing methods
## How It Works
SleekPixel seamlessly integrates with WordPress to provide a complete dynamic image solution:
1. **Design**: Create your image templates using the visual editor
2. **Configure**: Set up locations and conditions for where images should appear
3. **Connect**: Link your designs to dynamic content sources
4. **Generate**: Images are automatically created and updated as needed
## Processing Options
SleekPixel offers two processing methods to suit different needs:
- **Synchronous Processing**: Images generate immediately when needed
- **Asynchronous Processing**: Images generate in the background for better performance
## Integration Methods
Implement SleekPixel-generated images in various ways:
- **Automatic Integration**: Images appear automatically based on location rules
- **PHP Functions**: Use provided functions in your theme or plugin
- **Shortcodes**: Embed images directly in your content
- **WordPress Hooks**: Extend and customize functionality
SleekPixel is designed to solve common challenges in managing dynamic images for WordPress websites, making it an essential tool for creating professional, consistent, and automatically updated visuals across your site.
---
# Activating
SleekPixel can be activated on a site by navigating to the `SleekPixel` menu item in the WordPress admin dashboard.
Alternatively, it is also possible to activate SleekPixel using PHP. This is done by adding the following code constant to your `functions.php` file:
```php
const SLEEKPIXEL_LICENSE = "YOUR LICENSE KEY";
```
---
# Settings - Options
The Options section allows you to configure how SleekPixel generates and processes images. These settings affect all images created through the plugin.
## File Format
Select the format for your generated images. Facebook and Twitter generally expect PNG or JPEG formats for `og:image`. WebP images might not display correctly.
- PNG: Higher quality images with larger file sizes
- JPEG: Smaller file sizes with slightly lower quality
- WebP: Modern format with good compression (note: may not display correctly on all platforms)
## Image Processing
Optimize your image generation workflow in SleekPixel by choosing between synchronous and asynchronous image processing. Follow these steps to configure your preferred method.
### Understanding Image Processing Modes
- **Synchronous Processing:** Images are generated immediately when needed. This ensures that images are available right away but may cause a slight delay in page load time.
- **Asynchronous Processing:** Images are generated in the background. This allows pages to load faster, but images may not be immediately available on the first load. In asynchronous mode, the fallback will be the default Open Graph image or the featured image until the generated image is ready.
### Configure Image Processing Mode in SleekPixel
You can select your preferred image processing mode in the SleekPixel settings:
1. **Access SleekPixel Settings:**
- Log in to your WordPress admin dashboard.
- Navigate to `SleekPixel` in the sidebar and click on `Settings`.
2. **Locate the Options Section:**
- In the settings page, find the `Options` section.
3. **Choose Image Processing Mode:**
- Look for the setting labeled `Image Processing`.
- Select either **Synchronous** or **Asynchronous** from the available options.
- **Synchronous:** Images will be processed immediately.
- **Asynchronous:** Images will be processed in the background. The default Open Graph image or featured image will be used as a fallback until the custom image is generated.
4. **Save Your Settings:**
- Click the `Save Options` button at the bottom of the page to apply your new settings.
### Considerations
**Performance Impact:**
- **Synchronous:** May increase page load time, especially if generating large or complex images.
- **Asynchronous:** Improves page load speed but will cause a slight delay in image availability.
**User Experience:**
- **Synchronous:** Users will see the generated images immediately.
- **Asynchronous:** Users may see the default Open Graph image or featured image until the custom image is ready.
---
# Settings - Custom Fonts
The Custom Fonts section allows you to upload and manage your own font files, enabling you to maintain brand consistency and use unique typography in your SleekPixel designs.
## Uploading Custom Fonts
When you first visit the Custom Fonts section, you will be presented directly with the upload interface.
1. **Navigate to Settings:** Go to `SleekPixel` > `Settings` in your WordPress admin sidebar.
2. **Select Custom Fonts Tab:** Click on the `Custom Fonts` tab.
3. **Add Font Files:** Drag and drop your font files (accepted types shown are `.ttf`, `.font/ttf`) onto the designated area, or click to select files.
4. **Review and Upload:** The selected files will appear in the "Files ready to upload" list. You can remove individual files using the trash icon if needed. Click the `Upload X files` button to proceed.
Once you upload your first font, the interface will change to include two sub-tabs: `Upload New` and `Uploaded`. The `Upload New` tab contains the drag-and-drop interface described above.
## Managing Custom Fonts
After uploading at least one font, the `Uploaded` sub-tab becomes available. This tab allows you to manage your custom fonts.
- **View Uploaded Fonts:** This tab lists all fonts you have successfully added.
- **Edit Font Title:** Click the pencil icon (**) next to a font name. A modal will appear allowing you to change the display **Title** of the font as it appears in the editor's font list.
- **Delete Fonts:** Remove fonts you no longer need by clicking the trash icon (**) next to the font name.
## Using Custom Fonts in the Editor
After uploading, your custom fonts will automatically be available in the font selection dropdown within the SleekPixel editor.
1. **Open the Editor:** Go to `SleekPixel` > `Designs` and open or create a design.
2. **Select a Text Element:** Click on any text element on your canvas.
3. **Access Font Options:** In the element panel (usually on the right), find the `Font Family` dropdown.
4. **Choose Your Custom Font:** Your uploaded custom fonts will appear at the top of the list, prefixed with `Custom:` followed by the **Title** you set (e.g., `Custom: MyBrandFont`). Select the desired font to apply it to the text element.
By using custom fonts, you can ensure your dynamically generated images perfectly align with your website's branding and visual identity.
---
# Settings - API Keys
The API Keys section allows you to integrate Google Fonts into your SleekPixel designs. By adding a Google Fonts API key, you'll gain access to the entire Google Fonts library for use in your generated images.
## Google Fonts API Key
Enhance your designs with a wide variety of typography options by integrating Google Fonts into SleekPixel. Follow these steps to activate and configure Google Fonts using your API key.
## Obtain a Google Fonts API Key
Before you can use Google Fonts in SleekPixel, you need to obtain an API key from Google. Here's how to get one:
1. **Visit the Google Cloud Console:** Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. **Create or Select a Project:** - If you don't have a project, click on `Select a project` and then `New Project`. - Enter a project name and click `Create`. - If you already have a project, select it from the list.
3. **Enable the Google Fonts API:** - In the left sidebar, navigate to `APIs & Services` > `Library`. - Search for `Google Fonts Developer API`. - Click on it and then click `Enable`.
4. **Create Credentials:** - After enabling the API, go to `APIs & Services` > `Credentials`. - Click on `Create Credentials` and select `API Key`. - A pop-up will display your new API key. Copy this key and keep it secure.
## Enter the API Key in SleekPixel Settings
Once you have your Google Fonts API key, follow these steps to integrate it with SleekPixel:
1. **Access SleekPixel Settings:** - Log in to your WordPress admin dashboard. - Navigate to `SleekPixel` in the sidebar and click on `Settings`.
2. **Locate the Google Fonts Section:** - In the settings page, find the `Google Fonts` section.
3. **Enter Your API Key:** - Paste your Google Fonts API key into the designated field.
---
# Settings - License
The License section is where you activate your plugin by entering your license key. A valid license ensures you receive automatic updates and have access to all premium features.
## Adding Your License Key
1. Enter your license key in the provided field
1. Click the "Set Key" button to validate and activate your license
Once activated, your license key will be securely stored and automatically validate your installation for updates.
## License Status
After entering your key, the system will automatically verify its validity.
---
# Info - How Text Works
Understanding how text works in SleekPixel is crucial for creating designs that work reliably with dynamic content. The text system is designed to handle varying content lengths while maintaining your design's integrity.
## Text Box Controls
The text element in SleekPixel provides intuitive controls for sizing and scaling:
- **Corner Handles**: Scale both the font size and the text box proportionally
- **Side Handles**: Adjust the width of the text box while maintaining font size
## Dynamic Text Behavior
When using dynamic text sources (such as post titles or excerpts) instead of static text, SleekPixel automatically manages the text sizing to ensure your design remains intact. The text will automatically scale down if the content is too long to fit within the designated text box. This automatic scaling is essential for maintaining design integrity when working with unpredictable content lengths.
## Vertical Alignment
SleekPixel offers vertical alignment options (top, middle, or bottom) for text elements. It's important to note that while this setting affects the final rendered image, it may not be visible in the editor. This is because the text box in the editor always wraps tightly around the text for easier editing.
The vertical alignment becomes particularly useful when working with dynamic content that might be shorter than your test text, ensuring consistent placement regardless of content length.
## Best Practices for Text Design
To achieve the best results with text elements in SleekPixel:
1. **Set Ideal Size First** Choose a sample text that represents the maximum number of lines you want to allow at your desired font size. This establishes your baseline text box size.
2. **Configure Vertical Alignment** Select the appropriate vertical alignment (top, middle, or bottom) based on your design needs. This will ensure consistent text placement across different content lengths.
3. **Test with Various Lengths** Preview your design with both shorter and longer text than your sample to ensure the automatic scaling and alignment work as expected.
This approach ensures that your design will:
- Automatically scale down text that's too long to fit
- Properly align shorter text according to your preferences
- Maintain visual consistency across different content lengths
---
# Info - Rendering Differences
Understanding the subtle differences between what you see in the SleekPixel editor and the final generated image is important for achieving the best results. While we continuously work to minimize these differences, some variations may occur due to the nature of different rendering engines.
## Understanding the Two Rendering Engines
The core of SleekPixel's functionality relies on two distinct rendering engines working in harmony. In the editor, you interact with a real-time preview powered by your browser's DOM engine, providing immediate visual feedback as you design. The final output, however, is generated using PHP's ImageMagick library, which processes and creates the actual image files for your website.
This dual-engine approach allows us to provide both an intuitive design experience and powerful image generation capabilities. However, it's important to understand that these two engines may interpret and render certain elements slightly differently.
## Best Practices for Optimal Results
Achieving consistent results requires a thoughtful approach to design. Start with simpler layouts and gradually add complexity while testing the output at each stage. This iterative process helps identify potential rendering differences early in the design phase.
Regular testing is crucial - always preview your final generated images, especially when working with complex designs or when pixel-perfect accuracy is required.
## Reporting and Resolving Differences
If you encounter significant rendering differences that impact your designs, we're here to help. Document the issue by taking screenshots of both the editor view and the final output, noting any specific settings or effects that might be contributing to the difference. Before reporting, ensure all your settings are properly configured and you're using the latest version of SleekPixel.
Our support team is committed to helping you achieve the best possible results, and your feedback helps us continue improving the rendering accuracy across both engines. Detailed reports of rendering differences contribute to our ongoing efforts to enhance SleekPixel's capabilities and reliability.
---
# Locations
Under the **Locations** tab in your project, you can specify exactly where you want these images to appear on your site. This allows you to control the visibility and placement of the dynamically generated images across different pages and posts.
## Output types
SleekPixel offers four specific output types:
1. **Open Graph**: Generates images tailored for Open Graph meta tags, ensuring rich previews on social platforms like Facebook.
2. **Twitter Card**: Creates images optimized for Twitter Card meta tags, enhancing Twitter post previews.
3. **Open Graph + Twitter Card**: Combines both, producing images compatible with both platforms.
4. **Featured Image**: Automatically generates featured images for your posts, enhancing their visual appeal on your website.
## Open Graph
When you select the **Open Graph** image type, SleekPixel generates images specifically optimized for Open Graph meta tags (`og:image`). These images will always overwrite any SEO plugin-set images for Open Graph, ensuring that your dynamically generated images are used when your content is shared on social platforms like Facebook.
## Twitter Card
When you choose the **Twitter Card** image type, SleekPixel generates images specifically optimized for Twitter Card meta tags (`twitter:image`). These images will always overwrite any SEO plugin-set images for Twitter Cards, ensuring that your dynamically generated images enhance the preview of your content when shared on Twitter.
## Open Graph + Twitter Card
Selecting **Open Graph + Twitter Card** allows SleekPixel to generate images compatible with both Open Graph and Twitter Card meta tags. These images will always overwrite any SEO plugin-set images for both Open Graph and Twitter Cards, ensuring consistent and optimized previews across multiple social media platforms.
## Featured Image
When you select the **Featured Image** type, SleekPixel automatically generates featured images for your posts, enhancing their visual appeal on your website. These dynamically generated images will replace the default featured images for your posts.
**Important Note:** For the **Featured Image** functionality to work, there must be at least one item in your media library. SleekPixel uses an existing media item as a base for the `post_thumbnail_html` filter. This is necessary because WordPress requires a media attachment to generate the featured image HTML, and SleekPixel leverages this mechanism to insert the dynamically generated image into your posts.
## Conditions and Values
SleekPixel allows you to set specific conditions for where and how your images are displayed. These conditions correspond to WordPress functions and help you fine-tune the display of your dynamically generated images.
### Values
These options let you target specific elements in your WordPress site:
- **Post Type**: Target specific post types.
- **Post**: Target individual posts by their ID.
- **Post Status**: Target posts based on their status (e.g., published, draft).
- **Page Template**: Target pages using a specific page template.
- **Taxonomy**: Target posts associated with a specific taxonomy.
- **Term**: Target posts associated with a specific term within a taxonomy.
### Conditions
These options correspond to WordPress conditional tags and allow you to target specific types of pages or conditions:
- **Is Home**: Corresponds to `is_home()`. Checks if the main blog page is being displayed.
- **Is Front Page**: Corresponds to `is_front_page()`. Checks if the front page is being displayed.
- **Is Page**: Corresponds to `is_page()`. Checks if any single Page is being displayed.
- **Is Single Page**: Corresponds to `is_single()`. Checks if any single Post is being displayed.
- **Is Singular Page**: Corresponds to `is_singular()`. Checks if any single Post of any post type (Post, Page, Attachment) is being displayed.
- **Is Search Page**: Corresponds to `is_search()`. Checks if a search result page is being displayed.
- **Is Archive Page**: Corresponds to `is_archive()`. Checks if an archive page is being displayed.
- **Is Post Type Archive**: Corresponds to `is_post_type_archive()`. Checks if a post type archive page is being displayed.
- **Is Category Page**: Corresponds to `is_category()`. Checks if a category archive page is being displayed.
- **Is Tag Page**: Corresponds to `is_tag()`. Checks if a tag archive page is being displayed.
- **Is Taxonomy Page**: Corresponds to `is_tax()`. Checks if a taxonomy archive page is being displayed.
- **Is Author Page**: Corresponds to `is_author()`. Checks if an author archive page is being displayed.
- **Is Date Page**: Corresponds to `is_date()`. Checks if a date-based archive page is being displayed.
- **Is Year Archive**: Corresponds to `is_year()`. Checks if a yearly archive page is being displayed.
- **Is Month Archive**: Corresponds to `is_month()`. Checks if a monthly archive page is being displayed.
- **Is Day Archive**: Corresponds to `is_day()`. Checks if a daily archive page is being displayed.
- **Is Time Archive**: Corresponds to `is_time()`. Checks if a time-based archive page is being displayed.
- **Is Attachment Page**: Corresponds to `is_attachment()`. Checks if an attachment page is being displayed.
- **Is 404 Page**: Corresponds to `is_404()`. Checks if a 404 Not Found page is being displayed.
- **Has Featured Image**: Checks if the post has a featured image set.
---
# Custom Data
Besides a plethora of options, SleekPixel allows you to add custom entries to the dynamic data dropdown in the editor. This can be achieved using the `sleekPixel/data/custom` filter.
```php
add_filter(
"sleekPixel/data/custom", function ($data, $args) {
$postId = $args["postId"];
// Add custom data entry 1
$data[] = [
"value" => "customData1",
"label" => "Custom data",
"data" => get_field('my_field', $postId),
];
// Add custom data entry 2
$data[] = [
"value" => "customData2",
"label" => "Custom data 2",
"data" => "My custom title #2",
];
return $data;
}, 10, 2 );
```
---
# Rendering - Function
SleekPixel provides several PHP functions that allow you to easily render and manipulate dynamic images in your WordPress theme or plugin. These functions offer flexibility in how you integrate SleekPixel-generated images into your site.
## get_image_url
This function retrieves the URL of a SleekPixel-generated image.
### Parameters
The function accepts an array with the following keys:
- `id` (required): The ID of the SleekPixel image.
- `key` (required): The key or an array of keys for the image. This key is used to uniquely identify the image in the cache.
- `postId` (optional): The ID of the post associated with the image.
- `data` (optional): Custom data to merge with the image data. This data is merged recursively with other data.
### Usage
```php
$imageUrl = sleekPixel_get_image_url([
'id' => 123,
'key' => 'my_image_key',
'postId' => get_the_ID(),
'data' => [
"post" => [
"title" => "Custom Title"
]
]
]);
echo $imageUrl;
```
Note: The `data` parameter is recursively merged with other image data, allowing you to override or add specific values without affecting the entire data structure.
## get_image
This function returns an HTML `![]()
` tag for a SleekPixel-generated image.
### Parameters
The function accepts the same parameters as `get_image_url`.
### Usage
```php
$imageHtml = sleekPixel_get_image([
'id' => 123,
'key' => 'my_image_key',
'postId' => get_the_ID(),
'data' => [
"post" => [
"title" => "Custom Title for Image"
]
]
]);
echo $imageHtml;
```
## render_image
This function directly outputs an HTML `![]()
` tag for a SleekPixel-generated image.
### Parameters
The function accepts the same parameters as `get_image_url`.
### Usage
```php
sleekPixel_render_image([
'id' => 123,
'key' => 'my_image_key',
'postId' => get_the_ID(),
'data' => [
"post" => [
"title" => "Another Custom Title"
]
]
]);
```
These functions provide a convenient way to integrate SleekPixel-generated images into your WordPress theme or plugin. Choose the function that best suits your needs based on whether you need the image URL, HTML, or direct output. Remember that the `key` parameter is crucial for uniquely identifying and caching the generated image, and the `data` parameter allows for flexible customization of the image content.
---
# Rendering - Shortcode
SleekPixel provides a powerful shortcode that allows you to easily embed dynamic images in your WordPress content. This shortcode offers a flexible way to display SleekPixel-generated images within your posts, pages, or custom post types.
## Basic Usage
The basic syntax for the SleekPixel shortcode is as follows:
```
[sleekpixel id="123" key="my_image_key"]
```
## Parameters
The shortcode accepts several parameters to customize the image output:
- `id` (required): The ID of the SleekPixel image.
- `key` (required): The key or keys for the image. Multiple keys can be separated by commas.
- `post_id` (optional): The ID of the post associated with the image. If not provided, the current post ID will be used.
- `data` (optional): Custom data to merge with the image data. This should be provided as a JSON-encoded string.
## Advanced Usage
Here's an example of a more advanced usage of the shortcode:
```
[sleekpixel id="123" key="header_image,footer_image" post_id="456" data='{"custom_field": "value"}']
```
In this example:
- We're using two keys: `header_image` and `footer_image`.
- We're specifying a custom `post_id` of 456.
- We're passing custom data as a JSON-encoded string.
## Using in Templates
You can also use the shortcode within your PHP templates using the `do_shortcode()` function:
```php
```
The SleekPixel shortcode provides a convenient way to embed dynamic images in your content without needing to write PHP code. It's particularly useful for content editors who want to include SleekPixel images in their posts or pages.
---
# I18n
While SleekPixel doesn't currently support internationalization directly through the UI, you can use the `sleekPixel/data/custom` filter to add translated content from WPML or other translation plugins.
## Example: Adding WPML Translated Post Titles
Here's how you can add translated post titles from WPML to be available in your templates:
```php
add_filter(
"sleekPixel/data/custom", function ($data, $args) {
$postId = $args["postId"];
// Get current language
$currentLang = apply_filters('wpml_current_language', null);
// Get post title in current language
$translatedTitle = apply_filters('wpml_translate_single_string',
get_the_title($postId),
'post_title',
'post_' . $postId . '_title',
$currentLang
);
// Add translated title to data array
$data[] = [
"value" => "translatedTitle",
"label" => "Translated Title",
"data" => $translatedTitle,
];
return $data;
}, 10, 2 );
```
This example will add the translated post title for the current language in WPML.
---
# Hooks - PHP
Below you'll find a list of all available PHP hooks that can be used to extend or adjust the functionality of the plugin.
## conditions
This filter allows adding custom conditions to locations.
```php
add_filter('sleekPixel/conditions', function ($data) {
$data[] = [
'id' => 'isCustomUrl',
'label' => 'Custom URL Check',
'value' => str_contains($_SERVER['REQUEST_URI'], '?customParam'),
];
return $data;
});
```
## data
This filter allows modifying the data before it's used to generate the image.
```php
add_filter('sleekPixel/data', function($data, $args) {
$imageId = $args['id'] ?? 0;
// Modify post title for a specific image
if ($imageId === 123) {
$data['post']['title'] = 'New Post Title';
}
return $data;
}, 10, 2);
```
## data/custom
This filter allows registering custom data which can be chosen inside the editor.
```php
add_filter(
"sleekPixel/data/custom", function ($data, $args) {
$postId = $args["postId"];
// Add custom data entry 1
$data[] = [
"value" => "customData1",
"label" => "Custom data",
"data" => get_field('my_field', $postId),
];
// Add custom data entry 2
$data[] = [
"value" => "customData2",
"label" => "Custom data 2",
"data" => "My custom title #2",
];
return $data;
}, 10, 2 );
```
## image/element/data
This filter allows modifying the data of individual elements within a SleekPixel image.
```php
add_filter('sleekPixel/image/element/data', function($elementData, $image) {
// Check if this is the specific image we want to modify
if ($image['id'] === 123) {
// Loop through the styles of each element
foreach ($elementData['styles'] as &$style) {
// Check if the element has a 'color' key
if (isset($style['color'])) {
// Set the color to a primary color
$style['color'] = '#007bff'; // Example primary blue color
}
}
}
return $elementData;
}, 10, 2);
```
---