{"id":20140239,"url":"https://github.com/10quality/wp-media-uploader","last_synced_at":"2025-04-09T18:23:10.182Z","repository":{"id":57399524,"uuid":"254474213","full_name":"10quality/wp-media-uploader","owner":"10quality","description":"jQuery WordPress media Uploader. Converts a link or a button into a Media Library input.","archived":false,"fork":false,"pushed_at":"2022-12-07T03:51:26.000Z","size":57,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T19:52:40.423Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/10quality.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-09T20:41:56.000Z","updated_at":"2024-05-01T15:11:33.000Z","dependencies_parsed_at":"2023-01-23T15:05:11.639Z","dependency_job_id":null,"html_url":"https://github.com/10quality/wp-media-uploader","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/10quality%2Fwp-media-uploader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/10quality%2Fwp-media-uploader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/10quality%2Fwp-media-uploader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/10quality%2Fwp-media-uploader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/10quality","download_url":"https://codeload.github.com/10quality/wp-media-uploader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085946,"owners_count":21045243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T21:49:51.805Z","updated_at":"2025-04-09T18:23:10.164Z","avatar_url":"https://github.com/10quality.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WordPress Media Uploader\n\nInpired on [amostajo/wordpress-media-uploader](https://github.com/amostajo/wordpress-media-uploader), this jquery library converts any DOM element into a media uploader input.\n\nThe Media Uploader will pop-up WordPress Media Library, and will allow to upload and or select uploaded media from the library.\n\nContent:\n\n * [Install](#install)\n * [Basic usage](#basic-usage)\n    * [Enqueue](#enqueue)\n    * [Via HTML](#via-html)\n    * [Via Javascript](#via-javascript)\n * [Options](#options)\n    * [HTML attributes](#html-attributes)\n    * [target](#option-target)\n        * [after](#after)\n        * [inside](#inside)\n        * [DOM selector](#selector)\n    * [mediaFilter](#option-mediafilter)\n    * [mediaMap](#option-mediamap)\n    * [mediaLoad](#option-mediaload)\n * [Events](#events)\n * [Methods](#methods)\n * [Templating](#templating)\n\n## Install\n\nVia *npm*:\n```\nnpm install wp-media-uploader\n```\n\nOr download release and add it into your project.\n\n## Basic usage\n\n### Enqueue\n\nFirst enqueue script and media dependnecies:\n\n```php\n// (1) Make sure WP media gallery is enqueued\nwp_enqueue_media();\n\n// (2) Enqueue \"Wordpress Media Uploader\"\nwp_enqueue_script(\n    'wp-media-uploader',\n    PATH_TO_FILE . '/jquery.wp-media-uploader.min.js',\n    [ 'jquery', 'jquery-ui-core' ],\n    '1.0.0',\n    true\n);\n```\n\nIf you want the plugin to load select attachments and render them for you, add `wp-api` as dependency:\n```php\n// (1) Make sure WP media gallery is enqueued\nwp_enqueue_media();\n\n// (2) Enqueue \"Wordpress Media Uploader\"\nwp_enqueue_script(\n    'wp-media-uploader',\n    PATH_TO_FILE . '/jquery.wp-media-uploader.min.js',\n    [ 'jquery', 'jquery-ui-core', 'wp-api' ],\n    '1.0.0',\n    true\n);\n```\n\n### Via HTML\n\nInstantiate via HTML by adding attribute `role=\"media-uploader\"`, additionally, you can configure all options via `data` attributes:\n```html\n\u003ca role=\"media-uploader\"\n    data-editor=\"my-editor\"\n\u003e\n    Add Media\n\u003c/a\u003e\n```\n\n### Via Javascript\n\nTo instantiate via Javascript, first add an element in the DOM:\n```html\n\u003ca id=\"my-uploader\"\u003eAdd Media\u003c/a\u003e\n```\nThen call to `wp_media_uploader` jQuery plugin:\n```javascript\n$( '#my-uploader' ).wp_media_uploader( options );\n```\n\n## Options\n\nThe following is the list of available jQuery plugin `options`:\n\n| Option | Type | Description |\n| --- | --- | --- |\n| `name` | `string` | Input name. Required if this will be used inside a form. |\n| `value` | `string` | Input value. Values separated by commas when using the `multiple` option. |\n| `editor` | `string` | Editor ID. Default: *the plugin will assign a unique ID* |\n| `target` | `string` | Expected values `after`, `inside` or a DOM selector. This identifies where the selected will be rendered. Default: `after` |\n| `render` | `bool` | Flag that indicates if selected results should be rendered inside target or not. Default: `true` |\n| `multiple` | `bool` | Flag that indicates if multiple selection is allowed. Default: `false` |\n| `clearOnSelection` | `bool` | Flag that indicates if results in target should be cleared once a new selection is made, if set to `false`, results will be appended. The plugin will force this option to `true` when the `multiple` option is set to `false`. Default: `true` |\n| `title` | `string` | Title to display on top of the media uploader modal. |\n| `buttonText` | `string` | Selection button text to display inside the media uploader modal. |\n| `mimeType` | `string` | Expected values `image`, `video` or empty. |\n| `size` | `string` | The image size to use when rendering an image (for example: `thumbnail`, `large` or other). |\n| `allowClose` | `bool` | Wether or not to allow modal to close after selection. |\n| `success` | `function` | Function to use once a selection is made and after rendering. |\n| `mediaFilter` | `function` | Function to use to filter selected attachments before rendering. |\n| `mediaMap` | `function` | Function to use to map selected attachments before rendering. |\n| `idValue` | `bool` | Whether or not to use the attachment  ID as the input value instead of a url. Default: `true` |\n| `showInput` | `bool` | Whether or not to display the input. Default: `false` |\n| `inputCssClass` | `string` | The CSS class(es) to assign to the input. |\n| `targetCssClass` | `string` | The CSS class(es) to assign to the target. |\n| `templateImage` | `string` | HTML or a DOM selector. Template to use for image-based attachments. Default: *the plugin will use an internal template* |\n| `templateVideo` | `string` | HTML or a DOM selector. Template to use for video-based attachments. Default: *the plugin will use an internal template* |\n| `templateFile` | `string` | HTML or a DOM selector. Template to use for file-based attachments. Default: *the plugin will use an internal template* |\n| `templateEmbed` | `string` | HTML or a DOM selector. Template to use for embed-based attachments (Simple Post Gallery plugin). Default: *the plugin will use an internal template* |\n| `mediaLoad` | `string` | Expectes the name of a global (`window`) function or empty. This is the callable that will be used to load the media when the plugin is ready. Default: *the plugin will user WordPress rest api (if avialable) to load the attachment (Only supports ID values).* |\n\n### HTML attributes\n\nThe following lists the HTML attributes and their javascript option counter-part:\n\n| HTML attrbutes | Option | Value type |\n| --- | --- | --- |\n| `value` | `value` | `string` |\n| `name` | `name` | `string` |\n| `multiple` | `multiple` | `int` (values `1` or `0`) |\n| `data-editor` | `editor` | `string` |\n| `data-target` | `target` | `string` |\n| `data-render` | `render` | `int` (values `1` or `0`) |\n| `data-clear-on-selection` | `clearOnSelection` | `int` (values `1` or `0`) |\n| `data-title` | `title` | `string` |\n| `data-button` | `mimeType` | `string` |\n| `data-type` | `size` | `string` |\n| `data-size` | `size` | `string` |\n| `data-allow-close` | `allowClose` | `int` (values `1` or `0`) |\n| `data-id-value` | `idValue` | `int` (values `1` or `0`) |\n| `data-show-input` | `showInput` | `int` (values `1` or `0`) |\n| `data-input-class` | `inputCssClass` | `string` |\n| `data-target-class` | `targetCssClass` | `string` |\n| `data-media-load` | `mediaLoad` | `string` |\n| `data-template-image` | `templateImage` | `string` |\n| `data-template-video` | `templateVideo` | `string` |\n| `data-template-file` | `templateFile` | `string` |\n| `data-template-embed` | `templateEmbed` | `string` |\n\n\n### Option: target\n\nThis option allows you to define where is the selection going to be rendered.\n\n#### after\n\n*Note:* This is the default value.\n\nTarget set to `after` will make the plugin generate a unique container that will be placed right after the uploader. Selection will be rendered inside the generated `\u003cdiv\u003e`:\n```javascript\n$( '#my-uploader' ).wp_media_uploader();\n```\n```html\n\u003cbutton id=\"my-uploader\"\u003eAdd Media\u003c/button\u003e\n\u003c!-- Generated \"div\" target will be placed here --\u003e\n```\n\n#### inside\n\nTarget set to `inside` will make the plugin render the selection inside its own HTML element:\n```javascript\n$( '#my-uploader' ).wp_media_uploader( {\n    target: 'inside',\n} );\n```\n```html\n\u003cdiv id=\"my-uploader\"\u003e\n    Click to add media here\n    \u003c!-- Selection will be rendered here. the text \"Click to add media here\" will be cleared upon selection --\u003e\n\u003c/div\u003e\n```\n\n#### selector\n\nTarget set to a DOM selector will allow you to determine where to render the selection:\n```javascript\n$( '#my-uploader' ).wp_media_uploader( {\n    target: '#my-container',\n} );\n```\n```html\n\u003cbutton id=\"my-uploader\"\u003eAdd Media\u003c/button\u003e\n\u003cdiv id=\"my-container\"\u003e\u003c/div\u003e\n```\n\n### Option: mediaFilter\n\nThis option allows you to filter attachments before they are rendered, for example, the next snippet filters and returns only attachments with `url` property:\n```javascript\n$( '#my-uploader' ).wp_media_uploader( {\n    mediaFilter: function( attachment ) {\n        return attachment.url !== undefined;\n    },\n} );\n```\n\n### Option: mediaMap\n\nThis option allows you to map and modify  attachments before they are rendered, for example, the next snippet maps and returns a modified attachment:\n```javascript\n$( '#my-uploader' ).wp_media_uploader( {\n    mediaMap: function( attachment ) {\n        attachment.is_invalid = isNaN( attachment.id );\n        attachment.id = 55;\n        return attachment;\n    },\n} );\n```\n\n### Option: mediaLoad\n\nThis option allows you to set your own custom global function that will handle the initial attachments load, by default the plugin uses `wp.api` @ `media` endpoint; the next snippet uses a custom api endpoint to retrieve the attachments:\n```javascript\n$( '#my-uploader' ).wp_media_uploader( {\n    value: '45,65,77', // IDs separated by comma\n    mediaLoad: 'custom_load_media',\n} );\n\n/**\n * @param {object} uploader The uploader instance.\n * @param {array}  values   The collection of values.\n */\nwindow.custom_load_media = function( uploader, values )\n{\n    // Verify\n    if ( wp === undefined || wp.api === undefined )\n        return;\n    // Disable uploader (to prevent selection during loading)\n    uploader.$el.prop( 'disabled', true );\n    uploader.$el.addClass( 'loading' );\n    uploader.$el.attr( 'disabled', 'disabled' );\n    // Make request\n    wp.apiRequest( {\n        path: 'custom_namespace/v1/custom_endpoint',\n        method: 'GET',\n        data: {\n            values: values,\n        },\n    } )\n    .then( function( data ) {\n        var attachments = [];\n        // Process data\n        for ( var i in data ) {\n            // This is the minumin media properties expected to fill\n            var media = {\n                _model: undefined,\n                id: data[i].id,\n                type: data[i].type,\n                url: data[i].url,\n            };\n            if ( data[i].alt_text )\n                media.alt = data[i].alt_text;\n            if ( uploader.options.size\n                \u0026\u0026 data[i].sizes\n                \u0026\u0026 data[i].sizes[uploader.options.size]\n            )\n                media.url = data[i].sizes[uploader.options.size];\n            attachments.push( media );\n        }\n        uploader.render( attachments );\n        // Enable uploader\n        uploader.$el.prop( 'disabled', false );\n        uploader.$el.removeAttr( 'disabled' );\n        uploader.$el.removeClass( 'loading' );\n    } );\n}\n```\n\nYou can also stop the plugin from loading media by sending and empty string as parameter. For instance, this is useful if you plan to add load the attachment with PHP.\n```javascript\n$( '#my-uploader' ).wp_media_uploader( {\n    value: '45,65,77',\n    mediaLoad: '',\n    target: '#my-container'\n} );\n```\n```html\n\u003ca id=\"my-uploader\"\u003eAdd Media\u003c/a\u003e\n\u003cdiv id=\"my-container\"\u003e\n    \u003c?php if ( $attachment ) : ?\u003e\n        \u003cdiv id=\"\u003c?php echo esc_attr( $attachment-\u003eID ) ?\u003e\" class=\"attachment\"\u003e\n            \u003c!-- custom template--\u003e\n        \u003c/div\u003e\n    \u003c?php endif ?\u003e\n\u003c/div\u003e\n```\n\n**IMPORTANT**: If you will load the attachment(s) via PHP, make sure the markup is wrapped inside a div with the following attributes `id=\"{attachment_id}\"` and `class=\"attachment\"`.\n\n## Events\n\nList of events:\n\n| Event | Parameters | Description |\n| --- | --- | --- |\n| `uploader:ready` | *values*, *uploader* | Triggered when the plugin has initialized and it is ready. |\n| `uploader:open` | *uploader* | Triggered after WordPress media modal is called and opened. |\n| `uploader:render.before` | *uploader* | Triggered before rendering. |\n| `uploader:render.after` | *uploader* | Triggered after rendering. |\n| `uploader:render` | | Triggered after rendering (no parameters). |\n| `uploader:attachments` | *array*, *uploader* | Triggered after attachments have been selected, filtered and mapped. Before rendering. |\n| `uploader:selection` | *array*, *uploader* | Triggered after rendering. The array is the raw collection of models returned by WordPress media uploader modal and not the list of attachements proccessed by the plugin. |\n| `uploader:clear` | | Triggered after selection has been cleared. Also triggers `uploader:attachments` and `uploader:selection`. |\n\n### Event usage\n\n```javascript\n$( '#my-uploader' ).on( event, handler );\n```\n\nExamples:\n```javascript\n$( '#my-uploader' ).on( 'uploader:ready', function() {\n    alert( 'Ready!' );\n} );\n\n$( '#my-uploader' ).on( 'uploader:attachments', function( event, attachments, uploader ) {\n    console.log( attachments );\n    uploader.$el.hide();\n} );\n```\n\n## Methods\n\nList of methods:\n\n| Method | Parameters | Description |\n| --- | --- | --- |\n| `destroy` | | Destroys plugin instance. |\n| `clear` | | Clears current selection. |\n\nUsage example:\n```javascript\n$( '#my-uploader' ).wp_media_uploader( 'destroy' );\n```\n\n## Templating\n\n### Templating using external selector\n\nThe best way to explain templating is with a case scenario.\n\nThe following snippets will customize the plugin to use `jquery-ui-sortable` to enabled sorting inside the target, to allow sorting ofrendered results using drag-and-drop. The image template will be replaced to add an extra remove button, so selected media can be removed from selection.\n\n#### (1) Enqueue sortable and add WP.API dependency\n\nThe following sample, will enqueue the plugin, plus `wordpress media`, `jquery-ui-sortable` and `wp-api`.\n```php\nwp_enqueue_media();\nwp_enqueue_script(\n    'wp-media-uploader',\n    PATH_TO_FILE . '/jquery.wp-media-uploader.min.js',\n    [ 'jquery', 'jquery-ui-core', 'jquery-ui-sortable', 'wp-api' ],\n    '1.0.0',\n    true\n);\n```\n\n#### (2) Uploader initialized via HTML\n\nThe following sample will initialize the uploader input via HTML. The PHP value passed as attribute is validated first, to see if is an array or not, and if so, the value is passed as a comma separated list. `sortable` css class will be added to the generated target. The template inside `#gallery-image` will be used to render all selected images. `data-clear-on-selection` will allow for new selection to be appended to the target.\n```html\n\u003cdiv id=\"gallery\" class=\"gallery-container\"\u003e\n    \u003cbutton role=\"media-uploader\"\n        id=\"gallery\"\n        type=\"button\"\n        class=\"button\"\n        name=\"gallery\"\n        value=\"\u003c?php echo esc_attr( is_array( $gallery ) ? implode( ',', $gallery ) : $gallery ) ?\u003e\"\n        multiple=\"multiple\"\n        data-type=\"image\"\n        data-editor=\"gallery\"\n        data-clear-on-selection=\"0\"\n        data-target-css=\"sortable\"\n        data-template-image=\"#gallery-image\"\n    \u003e\u003c?php echo __( 'Add Media' ) ?\u003e\u003c/button\u003e\n\u003c/div\u003e\n\u003cscript id=\"gallery-image\" type=\"text/template\"\u003e\n    \u003cdiv class=\"attachment\"\u003e\n        \u003cimg\u003e\u003cinput type=\"text\"/\u003e\n        \u003cspan class=\"remove\"\u003e\u0026times;\u003c/span\u003e\n    \u003c/div\u003e\n\u003c/script\u003e\n```\n\n#### (3) Init sortable on ready event\n\nThe following sample will initialize `sortable` once the plugin is ready and has generated the target `\u003cdiv\u003e`.\n```javascript\n$( '#my-uploader' ).on( 'uploader:ready', function( event, uploader ) {\n    if ( uploader.$target.hasClass( 'sortable' ) )\n        uploader.$target.sortable();\n} );\n```\n\n#### (4) Add remove behavior\n\nThe following sample will allow to remove attachments.\n```javascript\n$( document ).on( 'click', '.attachment .remove', function( event ) {\n    event.preventDefault();\n    if ( confirm( 'Do you really want to remove this item?' ) ) {\n        $( this ).closest( '.attachment' ).remove();\n    }\n} );\n```\n\n### Templating using attributes\n\nAnother way of templating is by using the `data-template-image`, `data-template-video`, `data-template-file`, and `data-template-embed` attributes.\n\nThe plugin will look for the following selectors inside the template to append data:\n\n| Selector | Behavior |\n| --- | --- |\n| `input` | The plugin will add the media's value in the `value` attribute of the `input` element. The plugin will add the `name` attribute with the respective name. |\n| `.inject-media-id` | The plugin will put the media's ID inside the element with this selector. |\n| `.inject-media-url` | The plugin will put the media's URL inside the element with this selector. |\n| `.inject-media-filename` | The plugin will put the media's filename inside the element with this selector. |\n| `img` | **ONLY FOR IMAGE AND EMBED** The plugin will add the media's URL in the `src` attribute of the element. If the media has an `alt` text, the plugin will add the media's alt text in the `alt` attribute of the element. |\n| `source` | **ONLY FOR VIDEO** The plugin will add the media's URL in the `src` attribute of the element. |\n\nAny template passed through as an attribute must be wrapped in an extra `\u003cdiv\u003e` wrapper element. For example:\n```html\n\u003cdiv\u003e\u003cdiv class=\"attachment type-file\"\u003e\u003cspan class=\"inject-media-filename\"\u003e\u003c/span\u003e\u003cinput type=\"hidden\"/\u003e\u003c/div\u003e\u003cdiv\u003e\n```\n\nAbove, the template is wrapped in a `\u003cdiv\u003e` which holds another `\u003cdiv\u003e` with the CSS classes `attachment type-file`, this second `\u003cdiv\u003e` is the one that will be used for rendering. Additionally, the media's filename will be injected inside the `\u003cspan\u003e` with the class `inject-media-filename` and will add the media's value as an attribute on the `input` element.\n\nThere rendered output will look like this:\n```html\n\u003cdiv class=\"attachment type-file\" id=\"123\"\u003e\u003cspan class=\"inject-media-filename\"\u003efilename.jpg\u003c/span\u003e\u003cinput type=\"hidden\" value=\"123\"/\u003e\u003c/div\u003e\n```\n\nFinally, this is how uploader initialization will look like:\n```html\n\u003cdiv role=\"media-uploader\"\n    name=\"test\"\n    multiple=\"multiple\"\n    data-editor=\"test\"\n    data-template-file='\u003cdiv\u003e\u003cdiv class=\"attachment type-file\"\u003e\u003cspan class=\"inject-media-filename\"\u003e\u003c/span\u003e\u003cinput type=\"hidden\"/\u003e\u003c/div\u003e\u003cdiv\u003e'\n\u003e\u003c?php echo __( 'Add Media' ) ?\u003e\u003c/div\u003e\n```\n\n## License\n\nMIT - (c) 2022 [10 Quality Studio](https://www.10quality.com/).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F10quality%2Fwp-media-uploader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F10quality%2Fwp-media-uploader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F10quality%2Fwp-media-uploader/lists"}