Repository navigation
Developer Integration API #67
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.
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
Merged
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
319afb3
fix: Public JS API — window.cimo.optimizeFiles
Arukuen da41fb7
fix: PHP filters for upload selectors
Arukuen 0185b3d
fix: Public enqueue helper — cimo_enqueue_assets()
Arukuen 89e4b77
chore: developer docs
Arukuen cff1995
chore: dev docs and clearer comment
Arukuen 0cdc246
Apply suggestion from @bfintal
bfintal 0c2a95f
Clarify developer integration docs for plugin authors.
bfintal 23697f3
Merge branch 'develop' into feat/dev-api
bfintal 4c744b2
Add e2e coverage for the public developer integration API.
bfintal File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,181 @@ | ||
| # Cimo Developer Integration | ||
|
|
||
| Cimo optimizes files in the browser **before** your plugin or theme uploads them. | ||
| It does not replace your upload endpoint or your upload JavaScript. | ||
|
|
||
| ## How integration works | ||
|
|
||
| 1. **Enqueue Cimo** on pages where uploads happen (required on the frontend). | ||
| 2. **Tell Cimo where or when to optimize**, using one of the methods below. | ||
|
|
||
| Most integrations need Step 1 plus **one** method from Step 2. | ||
| You can combine file-picker interception (A) and drag-and-drop interception (B) if your UI supports both. | ||
|
|
||
| ## Step 1: Enqueue Cimo (required on frontend) | ||
|
|
||
| Cimo already loads in wp-admin and the block editor. | ||
| You do not need to enqueue it there. | ||
|
|
||
| On frontend pages or other custom screens, you must load Cimo yourself. | ||
| Call `cimo_enqueue_assets()` on the pages where users upload files. | ||
| Always check that the function exists first, in case Cimo is not active. | ||
|
|
||
| Register any PHP selector filters **before** you call `cimo_enqueue_assets()` on that page. | ||
| Cimo reads those filters while it loads its scripts. | ||
| Filters added afterward will not apply until the next page load. | ||
|
|
||
| **PHP** | ||
|
|
||
| ```php | ||
| add_action( 'wp_enqueue_scripts', function () { | ||
| if ( is_page( 'my-upload-form' ) && function_exists( 'cimo_enqueue_assets' ) ) { | ||
| cimo_enqueue_assets(); | ||
| } | ||
| } ); | ||
| ``` | ||
|
|
||
| ## Step 2: Choose how Cimo optimizes files | ||
|
|
||
| | Your upload UI | What to add after enqueue | | ||
| |----------------|---------------------------| | ||
| | User clicks and picks files (`<input type="file">`) | Method A | | ||
| | User drags files into a drop zone | Method B | | ||
| | Your plugin already has JavaScript that uploads via Fetch, XHR, or AJAX | Method C | | ||
| | Both a file picker and drag-and-drop | Method A + Method B | | ||
|
|
||
| ### Method A: File picker forms (automatic) | ||
|
|
||
| Use this when your form has a normal file input. | ||
| Your existing upload code can stay as it is. | ||
|
|
||
| 1. Wrap the file input in an element with a CSS class you control. | ||
| 2. Tell Cimo about that class with the `cimo/select_files/allowed_locations` filter. | ||
|
|
||
| **PHP** | ||
|
|
||
| ```php | ||
| add_filter( 'cimo/select_files/allowed_locations', function ( $locations ) { | ||
| $locations[] = '.my-plugin-uploader'; | ||
| return $locations; | ||
| } ); | ||
| ``` | ||
|
|
||
| **HTML** | ||
|
|
||
| ```html | ||
| <div class="my-plugin-uploader"> | ||
| <input type="file" name="photo" accept="image/*"> | ||
| </div> | ||
| ``` | ||
|
|
||
| The class must be on a wrapper around the file input (or on the input itself). | ||
| Cimo intercepts the `change` event, optimizes the file in the browser, puts the optimized file back on the input, then re-triggers `change` so your existing upload code still runs. | ||
| You do not need to write any Cimo JavaScript for this method. | ||
|
|
||
| ### Method B: Drag-and-drop zones (automatic) | ||
|
|
||
| Use this when users can drop files onto an area on the page, not only pick them from a file dialog. | ||
|
|
||
| Tell Cimo about the drop target with the `cimo/drop_zone/allowed_locations` filter. | ||
|
|
||
| **PHP** | ||
|
|
||
| ```php | ||
| add_filter( 'cimo/drop_zone/allowed_locations', function ( $locations ) { | ||
| $locations[] = '.my-plugin-dropzone'; | ||
| return $locations; | ||
| } ); | ||
| ``` | ||
|
|
||
| **HTML** | ||
|
|
||
| ```html | ||
| <div class="my-plugin-dropzone"> | ||
| <p>Drop images here</p> | ||
| </div> | ||
| ``` | ||
|
|
||
| If the same UI also has a file input, add Method A as well. | ||
| The two filters handle different events: file picking vs dropping. | ||
|
|
||
| ### Method C: Call the JavaScript API directly (manual) | ||
|
|
||
| Use this when your plugin already controls the upload in JavaScript and you can wait for Cimo before sending the files. | ||
|
|
||
| Call `window.cimo.optimizeFiles()` first. | ||
| Then upload the files it returns. | ||
|
|
||
| **JavaScript** | ||
|
|
||
| ```js | ||
| async function onFilesSelected( files ) { | ||
| const results = await window.cimo.optimizeFiles( files, { showProgress: true } ) | ||
| const filesToUpload = results.map( ( { file } ) => file ) | ||
|
|
||
| // Continue with your plugin or theme upload flow. | ||
| await uploadFiles( filesToUpload ) | ||
| } | ||
| ``` | ||
|
|
||
| The API accepts a single `File`, a `FileList`, or an array of `File` objects. | ||
| It returns: | ||
|
|
||
| **JavaScript** | ||
|
|
||
| ```js | ||
| [ | ||
| { | ||
| file: File, | ||
| metadata: Object || null, | ||
| }, | ||
| ] | ||
| ``` | ||
|
|
||
| `showProgress` defaults to `true`. | ||
| Set it to `false` if your UI already shows upload or optimization progress. | ||
|
|
||
| If Cimo optimization is disabled or a file type is unsupported, the original file is returned with `metadata: null`. | ||
|
|
||
| ## Complete minimal example | ||
|
|
||
| This is a frontend form with a file picker only. | ||
| It uses Step 1 plus Method A. | ||
| No other Cimo code is required. | ||
|
|
||
| **PHP** | ||
|
|
||
| ```php | ||
| add_filter( 'cimo/select_files/allowed_locations', function ( $locations ) { | ||
| $locations[] = '.my-plugin-uploader'; | ||
| return $locations; | ||
| } ); | ||
|
|
||
| add_action( 'wp_enqueue_scripts', function () { | ||
| if ( is_page( 'submit-photo' ) && function_exists( 'cimo_enqueue_assets' ) ) { | ||
| cimo_enqueue_assets(); | ||
| } | ||
| } ); | ||
| ``` | ||
|
|
||
| **HTML** | ||
|
|
||
| ```html | ||
| <form action="/your-endpoint" method="post" enctype="multipart/form-data"> | ||
| <div class="my-plugin-uploader"> | ||
| <input type="file" name="photo" accept="image/*" required> | ||
| </div> | ||
| <button type="submit">Upload</button> | ||
| </form> | ||
| ``` | ||
|
|
||
| ## Notes | ||
|
|
||
| The same JavaScript API is used in free and premium. | ||
| If Cimo Premium is loaded, premium converters are applied automatically. | ||
| There is no separate premium entry point. | ||
|
|
||
| Cimo optimization is pre-upload only. | ||
| It does not optimize by attachment ID, bulk replace existing files, or run server-side Imagick/GD compression. | ||
|
|
||
| On guest frontend uploads, files can still be optimized in the browser. | ||
| Stats and metadata in wp-admin may not appear when the visitor is not logged in or cannot access the Cimo metadata endpoint. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| <?php | ||
| /** | ||
| * Plugin Name: Cimo E2E Developer API | ||
| * Description: Registers public integrator selectors and enqueues Cimo on marked e2e pages. | ||
| */ | ||
|
|
||
| if ( ! defined( 'ABSPATH' ) ) { | ||
| exit; | ||
| } | ||
|
|
||
| add_filter( | ||
| 'cimo/select_files/allowed_locations', | ||
| static function ( $locations ) { | ||
| $locations[] = '.cimo-e2e-dev-uploader'; | ||
| return $locations; | ||
| } | ||
| ); | ||
|
|
||
| add_filter( | ||
| 'cimo/drop_zone/allowed_locations', | ||
| static function ( $locations ) { | ||
| $locations[] = '.cimo-e2e-dev-dropzone'; | ||
| return $locations; | ||
| } | ||
| ); | ||
|
|
||
| add_action( | ||
| 'wp_enqueue_scripts', | ||
| static function () { | ||
| if ( ! function_exists( 'cimo_enqueue_assets' ) ) { | ||
| return; | ||
| } | ||
|
|
||
| if ( ! is_singular( 'page' ) ) { | ||
| return; | ||
| } | ||
|
|
||
| $post = get_queried_object(); | ||
| if ( ! $post instanceof WP_Post ) { | ||
| return; | ||
| } | ||
|
|
||
| if ( false === strpos( $post->post_title, 'Cimo Dev API E2E' ) ) { | ||
| return; | ||
| } | ||
|
|
||
| cimo_enqueue_assets(); | ||
| } | ||
| ); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.