{"_id":"564e0de843817f17002a5ecc","__v":27,"githubsync":"","parentDoc":null,"project":"564de2dbfe07a81700b5c3a5","version":{"_id":"564de2dbfe07a81700b5c3a8","project":"564de2dbfe07a81700b5c3a5","__v":10,"createdAt":"2015-11-19T14:55:23.838Z","releaseDate":"2015-11-19T14:55:23.837Z","categories":["564de2ddfe07a81700b5c3a9","564df317826645210097a890","564df3217c8f372b00b934df","564e5227c3553e0d003e53ba","5666dac5d784a70d00397bcb","56cd08ddd98d851d00c0c3bd","56e9a50946bfd60e008840a7","5718e37bf8f7de1900683fad","58c3308dfedf070f0043b72c","58ce99c75457d02300560c0a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"user":"564de2b4fe07a81700b5c3a4","category":{"_id":"564df317826645210097a890","project":"564de2dbfe07a81700b5c3a5","__v":5,"pages":["564e0de843817f17002a5ecc","564e0e5ea910003500a0ca38","564e19e3bc4e172d00b9534e","56f168612a85600e00ea3dcb","56f17465dbe4cc1700a66a7a"],"version":"564de2dbfe07a81700b5c3a8","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-19T16:04:39.832Z","from_sync":false,"order":2,"slug":"javascript","title":"JavaScript"},"updates":["591eb6ce2c1b1f0f000faa1a","597035777c0fd30038b24063","597f37ac878132001ee24be6","5b607ebed22b04000307c9fe","5b9a35a4d617ad0003f27529"],"next":{"pages":[],"description":""},"createdAt":"2015-11-19T17:59:04.099Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Cards provide you with responsive and shareable embeds to drive the reach of your websites, blog posts, and articles. Our [code generator](http://embed.ly/code) makes it super simple to create a card of any site.\n\nThe follow explains how to use platform.js to programmatically create cards.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Basics\"\n}\n[/block]\nThis adds [platform.js](doc:platformjs) to your site and loads the script asynchronously. By\ndefault ``platform.js`` will create a card for an ``A`` tag or ``BLOCKQUOTE``\nwith the class ``embedly-card``. For example, this will create a card for\nembed.ly:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" <a href=\\\"http://embed.ly\\\" class=\\\"embedly-card\\\">Embedly</a>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nAnd this will also create a card:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" <blockquote class=\\\"embedly-card\\\">\\n    <h4><a href=\\\"http://embed.ly/docs\\\">Documentation</a></h4>\\n    <p>\\n      Embedly's Documentation is the best.\\n    </p>\\n  </blockquote>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe difference here, is that the ``H4`` will become the title of the Card and\nthe ``P`` text will become the description.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Customize\"\n}\n[/block]\nThere are a number of ``data-card-*`` attributes that you can use to customize\nthe card. They are as follows:\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Value\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"data-card-via\",\n    \"0-1\": \"URL i.e http://embed.ly\",\n    \"0-2\": \"Specifies the via content in the card. It's a great way to do attribution.\",\n    \"1-0\": \"data-card-chrome\",\n    \"1-1\": \"\\\"1\\\", \\\"0\\\"\",\n    \"1-2\": \"Chrome of 0 will remove the left hand colored border.\",\n    \"2-0\": \"data-card-theme\",\n    \"2-1\": \"\\\"light\\\", \\\"dark\\\"\",\n    \"2-2\": \"For dark backgrounds it's better to specify the dark theme.\",\n    \"3-0\": \"data-card-image\",\n    \"4-0\": \"data-card-embed\",\n    \"5-0\": \"data-card-controls\",\n    \"6-0\": \"data-card-width\",\n    \"7-0\": \"data-card-align\",\n    \"8-0\": \"data-card-recommend\",\n    \"3-1\": \"URL i.e. http://embed.ly/image.jpg\",\n    \"4-1\": \"URL i.e. https://vimeo.com/62648882\",\n    \"5-1\": \"\\\"1\\\", \\\"0\\\"\",\n    \"6-1\": \"\\\"100%\\\", \\\"300px\\\", etc.\",\n    \"7-1\": \"\\\"left\\\", \\\"center\\\", \\\"right\\\"\",\n    \"8-1\": \"\\\"1\\\", \\\"0\\\"\",\n    \"7-2\": \"Align the card, Default: \\\"center\\\"\",\n    \"6-2\": \"Sets the width of the card. Specifically the max-width, so card is still responsive.\",\n    \"5-2\": \"Enable Share Icons. Default: \\\"1\\\"\",\n    \"4-2\": \"Instead of using the static page content, the card will embed the video or rich media.\",\n    \"3-2\": \"Specify which image to use in article cards.\",\n    \"8-2\": \"Disable Embedly Recommendations on video and rich cards. Default: 1\",\n    \"9-0\": \"data-card-key\",\n    \"9-1\": \"\\\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\\\"\",\n    \"9-2\": \"You Embedly API Key. If you are a paid user this will remove Embedly's branding from the cards.\"\n  },\n  \"cols\": 3,\n  \"rows\": 10\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Javascript\"\n}\n[/block]\nPlatform.js has some pretty interesting features for customizing cards further. For example, if you do not want to use a custom class instead of ``embedly-card`` you can use the following code:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly('card', '.card-this');\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIf you would like to create a card from a single element you can do the\nfollowing:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" var a = document.getElementById('#myCard');\\n embedly('card', a);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nLastly if you would like to limit the cards to only embed certain types of\nmedia you can pass in a ``types`` argument::\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly('card', {types: ['rich', 'video', 'image']});\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nor with a custom selector as well:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly('card', {selector: 'a.embed', types: ['article', 'image']});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIf ``platform.js`` has not loaded yet, it will queue actions till we are ready\nto act on them.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Listeners\"\n}\n[/block]\nWhen using cards in non-standard displays you may want to listen to some events. Cards supports the following events.\n\n**``card.rendered``**\n\nWhen the card has actually been rendered.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly('on', 'card.rendered', function(iframe){\\n  // iframe is the card iframe that we used to render the event.\\n  $card = $(iframe);\\n\\n  // Grab the width and height.\\n  console.log($card.width(), $card.height());\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n**``card.resize``**\n\nWhen the card has been resized. We do this fairly often when the browser window has changed size, or the content in the card has changed.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly('on', 'card.resize', function(iframe){\\n  // iframe is the card iframe that we used to render the event.\\n  $card = $(iframe);\\n\\n  // Grab the width and height.\\n  console.log($card.width(), $card.height());\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Defaults\"\n}\n[/block]\nIf you would like to set options globally instead of per card you use\n``defaults``. Here's an example of setting all the cards to align right with a\nwidth of 700px and remove the chrome.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly(\\\"defaults\\\", {\\n  cards: {\\n    key: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',\\n    width: 700,\\n    align: 'right',\\n    chrome: 0\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNote that data attributes on the card override these defaults. If you wish for the defaults to override the data attributes, you can add ``override: true`` like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly(\\\"defaults\\\", {\\n  cards: {\\n    override: true,\\n    width: '90%',\\n    ...\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Player\"\n}\n[/block]\nEmbedly gives you programmatic control of embedded video via [Player.js](https://github.com/embedly/player.js/) and we've expanded that to Cards as well. Player allows you to play, pause, seek and listen to events for cards with video. Here's a quick example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly('player', function(player){\\n  console.log(player.url) // URL of the media that we are operating on.\\n\\n  // When the user pauses a video, perform an action.\\n  player.on('pause', function(){\\n    //display modal.\\n  });\\n\\n  // Autoplay all the videos that support Player.js\\n  player.play()\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nLearn more about the [Player functionality](doc:player)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"CSS Customization\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"CSS is only available on a paid plan.\",\n  \"body\": \"You can upgrade inside [app.embed.ly](https://app.embed.ly)\"\n}\n[/block]\nEmbedly allows you to customize the styles inside a card. If you want to change the font or colors of the card than this feature is for you! There are a couple of ways to pass styles into a card. We will outline them here. \n\n## inline\nYou can specify the css styles inline via a `style` tag. Embedly will look for a single `style` tag with the `embedly-css` and use that CSS.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<style class=\\\"embedly-css\\\">\\n  :::at:::import url(https://fonts.googleapis.com/css?family=Open+Sans+Condensed:300);\\n  .card {\\n    font-family: 'Open Sans Condensed', sans-serif;\\n  }\\n  .card a, .card .action {\\n    color: red;\\n  }\\n  .hdr {\\n    display:none;\\n  }\\n</style>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n## link\nYou can specify a stylesheet for Embedly to place inside the card via a `link` tag. Embedly will look for a single `link` tag with the `embedly-css` and use that CSS.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<head>\\n  ...\\n\\t<link rel=\\\"stylesheet\\\" href=\\\"http://example.com/styles/card.css\\\">\\n</head>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n## defaults\nLastly you can pass the css through defaults like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly(\\\"defaults\\\", {\\n  cards: {\\n    key: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',\\n\\t\\tcss: 'http://example.com/styles/card.css'\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## demo\n[block:embed]\n{\n  \"html\": \"<iframe class=\\\"embedly-embed\\\" src=\\\"//cdn.embedly.com/widgets/media.html?url=https%3A%2F%2Fjsfiddle.net%2FvuwLcpw1%2F%3Fheight%3D600%26tabs%3Dresult%2Chtml&src=https%3A%2F%2Fjsfiddle.net%2FvuwLcpw1%2Fembedded%2Fresult%2Chtml%2F&type=text%2Fhtml&key=02466f963b9b4bb8845a05b53d3235d7&schema=jsfiddle\\\" width=\\\"600\\\" height=\\\"600\\\" scrolling=\\\"no\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>\",\n  \"url\": \"https://jsfiddle.net/vuwLcpw1/?height=600&tabs=result,html\",\n  \"title\": \"Edit fiddle - JSFiddle\",\n  \"favicon\": \"https://jsfiddle.net/favicon.png\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Remove Branding\"\n}\n[/block]\nCards includes a \"powered by Embedly\" logo at the bottom of every card. If you would like to removed this branding, you can upgrade to a the embed product in [app.embed.ly](https://app.embed.ly/ar?path=settings%2Fplan).\n\nAny card created through [app.embed.ly](https://app.embed.ly) will have branding removed within 24 hours due to browser caching. \n\nFor cards not generated through app.embed.ly you must include your API key, found [here](https://app.embed.ly/ar?path=api%2Fkey). You can do this one of two ways.\n\n### On the Card\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<a href=\\\"embedly-card\\\" data-card-key=\\\"XXXXXXXXXXXX\\\" href=\\\"http://embed.ly\\\"></a>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n### Via JavaScript\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"embedly(\\\"defaults\\\", {\\n  cards: {\\n    key: 'XXXXXXXXXXXX',\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"cards","type":"basic","title":"Cards"}
Cards provide you with responsive and shareable embeds to drive the reach of your websites, blog posts, and articles. Our [code generator](http://embed.ly/code) makes it super simple to create a card of any site. The follow explains how to use platform.js to programmatically create cards. [block:api-header] { "type": "basic", "title": "Basics" } [/block] This adds [platform.js](doc:platformjs) to your site and loads the script asynchronously. By default ``platform.js`` will create a card for an ``A`` tag or ``BLOCKQUOTE`` with the class ``embedly-card``. For example, this will create a card for embed.ly: [block:code] { "codes": [ { "code": " <a href=\"http://embed.ly\" class=\"embedly-card\">Embedly</a>", "language": "html" } ] } [/block] And this will also create a card: [block:code] { "codes": [ { "code": " <blockquote class=\"embedly-card\">\n <h4><a href=\"http://embed.ly/docs\">Documentation</a></h4>\n <p>\n Embedly's Documentation is the best.\n </p>\n </blockquote>", "language": "html" } ] } [/block] The difference here, is that the ``H4`` will become the title of the Card and the ``P`` text will become the description. [block:api-header] { "type": "basic", "title": "Customize" } [/block] There are a number of ``data-card-*`` attributes that you can use to customize the card. They are as follows: [block:parameters] { "data": { "h-0": "Attribute", "h-1": "Value", "h-2": "Description", "0-0": "data-card-via", "0-1": "URL i.e http://embed.ly", "0-2": "Specifies the via content in the card. It's a great way to do attribution.", "1-0": "data-card-chrome", "1-1": "\"1\", \"0\"", "1-2": "Chrome of 0 will remove the left hand colored border.", "2-0": "data-card-theme", "2-1": "\"light\", \"dark\"", "2-2": "For dark backgrounds it's better to specify the dark theme.", "3-0": "data-card-image", "4-0": "data-card-embed", "5-0": "data-card-controls", "6-0": "data-card-width", "7-0": "data-card-align", "8-0": "data-card-recommend", "3-1": "URL i.e. http://embed.ly/image.jpg", "4-1": "URL i.e. https://vimeo.com/62648882", "5-1": "\"1\", \"0\"", "6-1": "\"100%\", \"300px\", etc.", "7-1": "\"left\", \"center\", \"right\"", "8-1": "\"1\", \"0\"", "7-2": "Align the card, Default: \"center\"", "6-2": "Sets the width of the card. Specifically the max-width, so card is still responsive.", "5-2": "Enable Share Icons. Default: \"1\"", "4-2": "Instead of using the static page content, the card will embed the video or rich media.", "3-2": "Specify which image to use in article cards.", "8-2": "Disable Embedly Recommendations on video and rich cards. Default: 1", "9-0": "data-card-key", "9-1": "\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"", "9-2": "You Embedly API Key. If you are a paid user this will remove Embedly's branding from the cards." }, "cols": 3, "rows": 10 } [/block] [block:api-header] { "type": "basic", "title": "Javascript" } [/block] Platform.js has some pretty interesting features for customizing cards further. For example, if you do not want to use a custom class instead of ``embedly-card`` you can use the following code: [block:code] { "codes": [ { "code": "embedly('card', '.card-this');", "language": "javascript" } ] } [/block] If you would like to create a card from a single element you can do the following: [block:code] { "codes": [ { "code": " var a = document.getElementById('#myCard');\n embedly('card', a);", "language": "javascript" } ] } [/block] Lastly if you would like to limit the cards to only embed certain types of media you can pass in a ``types`` argument:: [block:code] { "codes": [ { "code": "embedly('card', {types: ['rich', 'video', 'image']});\n", "language": "javascript" } ] } [/block] or with a custom selector as well: [block:code] { "codes": [ { "code": "embedly('card', {selector: 'a.embed', types: ['article', 'image']});", "language": "javascript" } ] } [/block] If ``platform.js`` has not loaded yet, it will queue actions till we are ready to act on them. [block:api-header] { "type": "basic", "title": "Listeners" } [/block] When using cards in non-standard displays you may want to listen to some events. Cards supports the following events. **``card.rendered``** When the card has actually been rendered. [block:code] { "codes": [ { "code": "embedly('on', 'card.rendered', function(iframe){\n // iframe is the card iframe that we used to render the event.\n $card = $(iframe);\n\n // Grab the width and height.\n console.log($card.width(), $card.height());\n});", "language": "javascript" } ] } [/block] **``card.resize``** When the card has been resized. We do this fairly often when the browser window has changed size, or the content in the card has changed. [block:code] { "codes": [ { "code": "embedly('on', 'card.resize', function(iframe){\n // iframe is the card iframe that we used to render the event.\n $card = $(iframe);\n\n // Grab the width and height.\n console.log($card.width(), $card.height());\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Defaults" } [/block] If you would like to set options globally instead of per card you use ``defaults``. Here's an example of setting all the cards to align right with a width of 700px and remove the chrome. [block:code] { "codes": [ { "code": "embedly(\"defaults\", {\n cards: {\n key: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',\n width: 700,\n align: 'right',\n chrome: 0\n }\n});", "language": "javascript" } ] } [/block] Note that data attributes on the card override these defaults. If you wish for the defaults to override the data attributes, you can add ``override: true`` like so: [block:code] { "codes": [ { "code": "embedly(\"defaults\", {\n cards: {\n override: true,\n width: '90%',\n ...\n }\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Player" } [/block] Embedly gives you programmatic control of embedded video via [Player.js](https://github.com/embedly/player.js/) and we've expanded that to Cards as well. Player allows you to play, pause, seek and listen to events for cards with video. Here's a quick example: [block:code] { "codes": [ { "code": "embedly('player', function(player){\n console.log(player.url) // URL of the media that we are operating on.\n\n // When the user pauses a video, perform an action.\n player.on('pause', function(){\n //display modal.\n });\n\n // Autoplay all the videos that support Player.js\n player.play()\n});", "language": "javascript" } ] } [/block] Learn more about the [Player functionality](doc:player) [block:api-header] { "type": "basic", "title": "CSS Customization" } [/block] [block:callout] { "type": "info", "title": "CSS is only available on a paid plan.", "body": "You can upgrade inside [app.embed.ly](https://app.embed.ly)" } [/block] Embedly allows you to customize the styles inside a card. If you want to change the font or colors of the card than this feature is for you! There are a couple of ways to pass styles into a card. We will outline them here. ## inline You can specify the css styles inline via a `style` tag. Embedly will look for a single `style` tag with the `embedly-css` and use that CSS. [block:code] { "codes": [ { "code": "<style class=\"embedly-css\">\n @import url(https://fonts.googleapis.com/css?family=Open+Sans+Condensed:300);\n .card {\n font-family: 'Open Sans Condensed', sans-serif;\n }\n .card a, .card .action {\n color: red;\n }\n .hdr {\n display:none;\n }\n</style>", "language": "html" } ] } [/block] ## link You can specify a stylesheet for Embedly to place inside the card via a `link` tag. Embedly will look for a single `link` tag with the `embedly-css` and use that CSS. [block:code] { "codes": [ { "code": "<head>\n ...\n\t<link rel=\"stylesheet\" href=\"http://example.com/styles/card.css\">\n</head>", "language": "html" } ] } [/block] ## defaults Lastly you can pass the css through defaults like so: [block:code] { "codes": [ { "code": "embedly(\"defaults\", {\n cards: {\n key: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',\n\t\tcss: 'http://example.com/styles/card.css'\n }\n});", "language": "javascript" } ] } [/block] ## demo [block:embed] { "html": "<iframe class=\"embedly-embed\" src=\"//cdn.embedly.com/widgets/media.html?url=https%3A%2F%2Fjsfiddle.net%2FvuwLcpw1%2F%3Fheight%3D600%26tabs%3Dresult%2Chtml&src=https%3A%2F%2Fjsfiddle.net%2FvuwLcpw1%2Fembedded%2Fresult%2Chtml%2F&type=text%2Fhtml&key=02466f963b9b4bb8845a05b53d3235d7&schema=jsfiddle\" width=\"600\" height=\"600\" scrolling=\"no\" frameborder=\"0\" allowfullscreen></iframe>", "url": "https://jsfiddle.net/vuwLcpw1/?height=600&tabs=result,html", "title": "Edit fiddle - JSFiddle", "favicon": "https://jsfiddle.net/favicon.png" } [/block] [block:api-header] { "type": "basic", "title": "Remove Branding" } [/block] Cards includes a "powered by Embedly" logo at the bottom of every card. If you would like to removed this branding, you can upgrade to a the embed product in [app.embed.ly](https://app.embed.ly/ar?path=settings%2Fplan). Any card created through [app.embed.ly](https://app.embed.ly) will have branding removed within 24 hours due to browser caching. For cards not generated through app.embed.ly you must include your API key, found [here](https://app.embed.ly/ar?path=api%2Fkey). You can do this one of two ways. ### On the Card [block:code] { "codes": [ { "code": "<a href=\"embedly-card\" data-card-key=\"XXXXXXXXXXXX\" href=\"http://embed.ly\"></a>", "language": "html" } ] } [/block] ### Via JavaScript [block:code] { "codes": [ { "code": "embedly(\"defaults\", {\n cards: {\n key: 'XXXXXXXXXXXX',\n }\n});", "language": "javascript" } ] } [/block]