When dropped into your page, this sample library creates a gallery of Stock search thumbnails. While you can add different search parameters, it is designed to search on a similar image URL (such as the main image on your page), or on keywords. Keyword extraction is provided by the Keyword Extractor package by Michael DeLorenzo.
New as of July 26, 2018 In the 1.2 release, there is now support for video thumbnails. See the video thumbnails demo located here. Adobe Stock does not support similarity search for videos yet, so only keyword search is part of this demo. There are two new configuration commands added:
videoSupport: true,
ctaLink: 'video',
The command videoSupport enables video thumbnails. This detects if an asset has a video preview, and adds this preview as a dynamic video thumbnail that plays when hovered over it. It also adds a video icon to the image.
The command ctaLink controls what call-to-action (CTA) link appears above the thumbnails. The default language is "First month free with Adobe Stock annual plans." If ctaLink is set to video, the link text will read "Save money on Adobe Stock videos." (Default value is fmf for the "first-month free" promotion.)
https://cfsdemos.com/stock/demos/stockthumbs/sdk_stockthumbs1.html
Before you use the sample, you will need to register for an Adobe Stock API key. Also, if you want to get paid for referral traffic, sign up to become an Adobe affiliate. Otherwise, you will not receive credit for traffic you generate.
For more information about the Stock API and the SDK, see Getting Started.
All files are pre-built in the dist folder, otherwise you can run npm install and npm run build to build your own copy. The library includes minified versions of jQuery, Masonry, and the Adobe Stock SDK for JavaScript; these are not dependencies of the main script but are required to reside in the same folder. You can supply your own versions if you prefer. The script will load jQuery if it does not detect it already loaded.
To use on your site:
- Either:
- Download and extract stockthumbs-1.x.x.zip (lates version) to your web server. It should extract as a folder with the same name as the archive.
- Copy the
distfolder to your server and optionally rename to "stockthumbs". This is not required, but matches the embed code example, below.
- Include the embed code in your page, preferably at the bottom before the closing
</body>tag. - Identify where you want the thumbnails to appear, and note the selector name. Change the
parentIdto match the CSS selector name and the gallery will build itself inside that container. By default, the gallery will appear in a DIV with an id ofastock-searchbar. - To test, your page must be hosted on a web server or in a localhost. Open a web inspector, and if any files are not loading, make sure the paths to the CSS and JS files are correct. The example code expects that if your page resides at the root of your site, then the files are located in a folder named
stockthumbsalso located at the root. If it is working properly, you should see some search results based on the title of your page. - Configure the options as described below under Configure.
<!-- Begin StockThumbs -->
<!-- StockThumbs container -->
<div id="astock-searchbar" class="astock-searchbar unfloat"></div>
<!-- StockThumbs styles -->
<link rel="stylesheet" type="text/css" href="./sdk_stockthumbs_styles.css">
<!-- StockThumbs script include -->
<script type="text/javascript" src="./sdk_stockthumbs.js"></script>
<script type="text/javascript">
StockThumbs.config = {
// container where StockThumbs will appear
parentId: '#astock-searchbar',
// search filters
filters: {
// first param is CSS selector of element containing keywords
// second param is how many keywords to include
WORDS: [],
// for high contrast, use '000000,ffffff'
FILTERS_COLORS: '',
/* To enable search on similar url:
* Enter selector of parent element containing image
* leave blank or remove to disable */
SIMILAR_URL: '#hero',
THUMBNAIL_SIZE: 220,
LIMIT: 16,
},
// Stock api key registered on console.adobe.io
apiKey: 'yourkeyname',
// Name you choose for app (whatever you want)
appName: 'StockThumbs/1.2',
// Your affiliate data--Change these values to receive credit!
camRef: '1101lryZ2',
pubRef: 'searchbar',
// experimental! create bubble tooltips over images
tooltips: true,
};
StockThumbs.init(StockThumbs.config);
</script>
<!-- End StockThumbs -->At a minimum, you must include the JS library sdk_stockthumbs.min.js. This script is minified using a source map which is included in the dist folder, so if you use a modern brower and open your web console, you should be able to inspect the source without needing to "prettify" it.
You will also want to include the CSS file sdk_stockthumbs_styles.min.css, although most of the search bar will create itself properly without it (and in some cases, it will create required classes). You can easily override the default CSS classes as needed.
As noted above, the StockThumbs also uses jQuery for various support functionality, Masonry.js to layout the thumbnails, and the Adobe Stock SDK as wrapper for the Stock API. These libraries are included as a courtesy, but you can also supply your own versions. The included jQuery version is 1.11.x, mainly for backwards compatibility, but should work with any version. If jQuery is detected, StockThumbs will not load its own version.
The options are described above in the code and are mostly self-explanatory, but here is additional detail.
The StockThumbs object does not accept a constructor, instead using an init method which takes a single argument, a config object. If you want to delay the instantiation of the StockThumbs so you can change the startup options, you can create the configuration separately, and then call init when you want the StockThumbs to assemble itself. This technique is used in the sdk_stockthumbs1.html reference demo, because the demo has an option to either use parameters that show image similarity search, or show keyword search.
StockThumbs.config = {
// place configuration options here
};
// now initialize the StockThumbs
StockThumbs.init(StockSearchBar.config);The configuration object has a few required properties:
-
parentId: As mentioned earlier, this is the selector for the containing element which will hold the StockThumbs. If this element doesn't exist, the script will throw an exception and nothing will appear.The sample code includes an example of a container:
<div id="astock-searchbar" class="astock-searchbar unfloat"></div>You can choose to place this DIV wherever you want the thumbnails to appear, or you can leave it out and choose a different container. If you use a different container and do not include the main `astock-searchbar` class, then a DIV element will be created with this class name.
When identifying the `parentId` you may use any valid CSS selector, but it's recommend you use an `id` selector to ensure that the StockThumbs only appears once on your page. If you are unfamiliar with selectors, see [this article](https://developer.mozilla.org/en-US/docs/Learn/CSS/Introduction_to_CSS/Simple_selectors).
filters: This is an object containing multiple search parameters, all of which are optional. See Filters object, below.apiKey: The Adobe Stock API key for your integration that you created at the Adobe I/O Developer Console. For more information on this simple process, see Register your application in the Adobe Stock Getting Started guide.appName: This field can be whatever you wish to call your app, as long as it is not blank. This is mainly used by Adobe for troubleshooting.
The next three parameters are required if you want to receive credit for referring traffic to Adobe Stock. Each successful Stock subscription attributed to you will pay a bounty! For more information, see the Adobe Affiliate Program.
Once accepted into the program and you join the Adobe campaign, go the Tracking page to get your camref value. Select the Adobe campaign and it should reveal a tracking link in this format: https://adobe.prf.hn/click/camref:{camRef}. The camref value is unique to the campaign, and is required to generate tracking events. You can optionally add a pubref value as well, which is a unique publisher reference that you can assign to a tracking link that will track from click to sale and is visible in your reporting. This allows you separate Stock Thumbs clicks from other clicks.
camRef: '1101lryZ2',
pubRef: 'stockthumbs',-
tooltips: This is somewhat experimental setting which uses JavaScript and CSS to create tooltip rollovers over each image that are customizable in CSS. Each tip is created dynamically based on thetitleattribute of the Stock image item.This setting has not been tested on mobile devices, as it relies on the
mouseenter/mouseleaveevents. If you run into issues, I recommend disabling it or leaving it out, in which case it will default tofalse.
The filters object includes a few commands which have special functionality, but otherwise the commands are the same as the Query Parameter Object settings found in the Stock JavaScript API SDK. See below for a few examples of adding your own filters. These filters are included by default, but are optional.
-
WORDS: Unlike the Stock SDK command with the same name, requires an array input of two arguments:- CSS selector where keywords are found on the page (string)
- Number of keywords to extract (integer)
This feature works by collecting the textContent node of the target object (such as the
<title>element), and running it through the highly useful Keyword Extractor library, which removes common "stopwords" (like "the", "a", "is").Note: The StockThumbs currently only supports US English keywords, but the Keyword Extractor library supports several languages, and Adobe Stock supports dozens of languages. If you have a need to support other languages, please open a new issue or contact us.
Example: Extract the first three keywords from the
<h1>tag.<h1>Chalet house on the edge of a forest</h1>WORDSparameter:WORDS: ['h1', 3],Resulting search query to Stock:
?search_parameters[words]=chalet house forestNote that the more keywords selected, the narrower the search results. For best results, choose 1-3 keywords.
If the
WORDScommand is removed or set to null, StockThumbs will not search any keywords. -
SIMILAR_URL: This command also operates a little differently than the Stock SDK version. It accepts a string parameter of a CSS selector containing an image element. It will find the URL of the first image it encounters, and send that URL to the Stock API. Stock will return images which look visually similar to that URL. Note that you can combine similarity search and keyword search, however keep in mind this will also limit the total search results.Example image tag:
<img id="hero" src="https://images.unsplash.com/photo-1486496146582-9ffcd0b2b2b7?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max&s=0f55748f4e8226e4f826cdeea2919a2c">SIMILAR_URLvalue to get the value of this tag which has an element id of "hero":SIMILAR_URL: '#hero', -
THUMBNAIL_SIZE: Size of image thumbnails returned (integer). CSS will be applied to fit the images within the StockThumbs, so you may want to increase or decrease this value depending on the size of your gallery. If you leave out this command, the default size is 500 pixels. These are the only valid values--any other values will cause StockThumbs to find the nearest size. Note that 500 and 1000 pixel sizes include watermarks.- 110px
- 160px
- 220px
- 240px tall (with variable height)
- 500px: Includes watermark
- 1000px: Includes watermark
-
LIMIT: Number of images returned (integer). The max images returned is 64 (default value is 16).Note that StockThumbs only returns the first page of results (API command is
offset=0), regardless of the number of results. If you need to support pagination, please open a new issue or contact us.
- To only include illustrations and vectors in your results, set these parameters:
FILTERS_CONTENT_TYPE_ILLUSTRATION: 1,
FILTERS_CONTENT_TYPE_VECTOR: 1,
You can either edit the styles in the uncompressed sdk_stockthumbs_styles.css (located in the src folder), or override them on your page.
Some classes are added programmatically when the StockThumbs is created. These include:
.astock-searchbar: Main class for StockThumbs container. If this class does not exist on the container div (parentId), then a new DIV child will be created under theparentIdparent, and this class will be applied there..astock-searchbar-header: Contains the Adobe Stock logo and header..astock-searchbar-wrap: A wrapper around the thumbnails which allows scrolling..astock-searchbar-body: Container for the thumbnails..astock-searchbar-item: Container for each thumbnail. This width, along with the width of the overall StockThumbs, will have the most direct influence on how many columns of thumbnails appear..astock-searchbar-tip: If tooltips are enabled, this controls the look of the tooltip bubble..astock-searchbar-fadein: Controls visibility of the StockThumbs, and is added when all images have loaded..item-small: A mix-in class that only is added if the StockThumbs falls under a minimum width (currently 150 pixels.)