Skip to content

05. 🗂Map →

Jump to bottom
The Administrator edited this page Jul 4, 2020 · 4 revisions

Mapping Tab

This is where we map a source field from the scrape items to a destination field for a post, image or meta-object.

When we create a new WordPress post, it will perform five tasks:

  1. Create a post object.
  2. Create an image object.
  3. Update the post object with any new meta values.
  4. Associate the post object to the image object.
  5. Associate the post to a term with the name of the Search ID.

Mapper Report

The mapper report will show you the value that will be inserted in each field, in each object (post/meta/image), for every item. If a mapping source field is incorrect, you will see in the mapper report that the mapping does not exist.

Mapper Instance

A mapper instance is a group of all the single mappings that will create a new post in WordPress. Since each YouTube API response will be slightly different and contain different fields you can create a different mapping instance for each search type (Search / Multichannel Activity / Playlist Items / Playlists ) response.

Mapper ID

Used to populate the scraper tab and allow you to select the particular mapping you will use on the scrape results.

Mapper Row

The heart of the mapper will be all of the individual rows indicating every source to the destination field in the instance.

Source Field

The source field can be in one of two different formats:

1. Mapper Location

A location in the result item from the API. This is in the hyphen arrow -> format.

This is the default format that will be used.

For example, a standard search type will respond with items in this format:

{
        "kind": "youtube#searchResult",
        "etag": ""Dn5xIderbhAnUk5TAW0qkFFir0M/fNclM0aMUSJDvAskXFCY32I02wE"",
        "id": {
            "kind": "youtube#video",
            "videoId": "5vosgbLnQVc"
        },
        "snippet": {
            "publishedAt": "2020-05-01T14:59:54.000Z",
            "channelId": "UCrNQZRCklXq9ZjQzf3V575g",
            "title": "PARKOUR GONE WRONG IN LOS ANGELES",
            "description": "Here's a small edit from clips I got about 2 months ago in DTLA of some of the best parkour/free running athletes in the world! This was back when I was just ...",
            "thumbnails": {
                "default": {
                    "url": "https://i.ytimg.com/vi/5vosgbLnQVc/default.jpg",
                    "width": 120,
                    "height": 90
                },
                "medium": {
                    "url": "https://i.ytimg.com/vi/5vosgbLnQVc/mqdefault.jpg",
                    "width": 320,
                    "height": 180
                },
                "high": {
                    "url": "https://i.ytimg.com/vi/5vosgbLnQVc/hqdefault.jpg",
                    "width": 480,
                    "height": 360
                }
            },
            "channelTitle": "Bailey Payne",
            "liveBroadcastContent": "none"
        }
    },

To get the title of the video, the source field would be snippet->title. The source field for the URL of the default thumbnail would be snippet->thumbnails->default->url.

Use the filter tab's 'Filter Report' to see exactly which fields can be mapped as source fields.

Note: If the result contains an unnamed array, you can just reference the key number of the array entry you wish to reference. For instance, is you have this result:

            "edge_media_to_caption": {
                "edges": [
                    {
                        "node": {
                            "text": "This is the text I want!"
                        }
                    }
                ]
            },

You can get to the "text" entry by using the key 0. So the entry would be: edge_media_to_caption->edges->0->node->text

2. Literal String

The second format would be a literal string. The literal string can be anything you want to insert into the destination field. For instance, you may want to put the word publish into the post_status of the destination post.

To use a literal string instead of a location in the source item, you can use the field_as_string transform group.

Transform Group

The transform group select box will be populated from the 'Transform' tab. More details on that wiki page. By selecting a transform group you will be performing alterations of the source data before it is put into the destination field.

A simple example would be to trim the title to the first 50 characters, or maybe make everything UPPERCASE.

Destination

Using Wordpress functions, part of the process is to create a standard post object using wp_insert_post(), create a thumbnail image post using media_handle_sideload() and update the post metadata with update_post_meta(). Each of these items require different arguments to be created. We can map to these three destinations by selecting the correct one in the select field.

Post

The post destination can be any of the fields defined in the wp_insert_post Wordpress codex page here: https://developer.wordpress.org/reference/functions/wp_insert_post/

Image

The image destination type also takes the same post arguments as a default post, with some added extra fields to map. These are listed below:

  1. url. This is the URL to download the image from.
  2. filename. This is the filename to use when saving the downloaded image.
  3. alt. The alt tag of the image. Defaults to the post_title if not set.

If no filename is defined, an MD5 hash of the URL field is used. This means that each image filename will be unique, but repeatable for each video. This helps with making sure image downloading only happens once per video.

Meta

The meta destination type can be any string. This will update an existing meta field or create a new one if it doesn't exist. Good for updating meta fields from other plugins too. Mapping to rank_math_title or rank_math_description for the RankMath plugin will auto-populate those fields.

Destination field

This is the name of the post / image / meta field you wish to insert the value into. A literal string that will be used to reference the field.

Minimum Mappings

As a minimum it would be wise to map the following fields:

  1. Post - post_title. Required field for creating a post.
  2. Post - post_content. Required field for creating a post.
  3. Post - post_status. Use to set to 'publish' and set the published state.
  4. Image - url. Use to download the featured image.
  5. Image - filename. Use to download the featured image.

Please read the 'transform' tabs notes because it will explain much more about what to use on the mappings.

Notes

Image 'URL' Transform

One of the transforms available is the best_image one. Use it with a source of the entire 'thumbnail' array. It will then take the URL of the best image. Better to use than manually picking a URL field that may be missing on some items.

Post_status Transform

If no post_status is given the post inserted will be a 'draft' by default. To set to being published, use the mapping field_to_string to map the word publish to the field post_status.

Image title

The post_title of the image will automatically have the word 'image' added onto the end of it. This is to distinguish it from the title of the post itself. Otherwise a post_exists() check of an existing post will match both objects, rather just the post.

Clone this wiki locally