search

cferdinandi / petfinderAPI4everybody

A JavaScript plugin that makes it easier to use the Petfinder API.
MIT License
14 stars 7 forks source link
animals api javascript javascript-plugin no-dependencies non-profit petfinder petfinder-api vanilla-js

readme

petfinderAPI4everybody.js Build Status

A JavaScript plugin that makes it easier for developers to use the Petfinder API.

Download petfinderAPI4everybody.js / View the demo

Note: This is DIY library for web developers. If you're not comfortable writing code, you may prefer working with Fetch, my plug-and-play solution for the Petfinder API.

Getting Started

Compiled and production-ready code can be found in the dist directory. The src directory contains development code.

1. Include petfinderAPI4everybody.js on your site.

<script src="https://github.com/cferdinandi/petfinderAPI4everybody/raw/master/dist/js/petfinderAPI4everybody.js"></script>

2. Add the markup to your HTML.

<div data-petfinder="main">
    <!-- Required -->
    <!-- Main pet content will be generated here -->
    <a href="http://awos.petfinder.com/shelters/AA11.html">View our adoptable pets on Petfinder.</a>
</div>

<div data-petfinder="aside">
    <!-- Optional -->
    <!-- Supplemental content will be generated here -->
</div>

Place the two [data-petfinder] elements anywhere on a webpage. You can wrap them in other elements, add classes and IDs, and so on.

Note: You should include a backup link or Petfinder iframe in the [data-petfinder="main"] element. This will be displayed if the user's browser is not supported by petfinderAPI4everybody.js or the API fails to load.

3. Initialize petfinderAPI4everybody.js.

In the footer of your page, after the content, initialize petfinderAPI4everybody.js.

A key and sheltherID are required. This is also where you pass in templates for the main and aside content.

And that's it, you're done. Nice work!

Note: If you find this section confused, check out the template to see an example of how you might set things up. Still lost? I can help.

<script>
    petfinderAPI.init({
        key: '123456789', // Your API key with Petfinder
        shelterID: 'AA11', // Your Petfinder shelter ID
        templates: {
            // The layout for the page that displays all pets
            allPets:
                '<div>' +
                    '<div>' +
                        '<img src="https://github.com/cferdinandi/petfinderAPI4everybody/raw/master/{{photo.1.medium}}">' +
                    '</div>' +
                    '<h2>{{name}}</h2>' +
                    '<p><a href="https://github.com/cferdinandi/petfinderAPI4everybody/blob/master/{{url.pet}}">View Full Profile</a></p>' +
                    '<hr>' +
                '</div>',
            onePet: null, // The layout for individual pet profiles [optional]
            asideAllPets: null, // The layout for secondary content on the "All Pets" page [optional]
            asideOnePet: null, // The layout for secondary content on individual pet pages [optional]
        }
    });
</script>

API Data Variables

Include the following variables in your template markup to dynamically add content from the Petfinder API.

Pet Variables:

Aside Variables:

Note: Lists return <li> elements only. You must place them inside an <ol> or <ul> element as desired. Example: <ul>{{list.breeds}}</ul>

Filtering Pets

If you have a lot of pets, you may want to give users the option of filter by attributes like animal type, breed, age, and more. The included (but optional) petfinderSort.js script makes this really easy.

1. Include the script on your site.

<script src="https://github.com/cferdinandi/petfinderAPI4everybody/raw/master/dist/js/petfinderSort.js"></script>

2. Add the markup to your HTML and initialize petfinderSort.js as a callback after the content is generated.

Add any of the attribute checklists you want to use to your template, and add the {{classes}} variable on a containing <div> in the allPets template. Initialize petfinderSort.js as a callback after content is generated.

<script>
    petfinderAPI.init({
        ...
        templates: {
            allPets:
                '<div class="{{classes}}">' +
                    // Pet layout
                '</div>',
            asideAllPets:
                '<strong>Age:</strong>' +
                '{{checkbox.ages.toggle}}' +
                '<br><br>' +

                '<strong>Size:</strong>' +
                '{{checkbox.sizes}}' +
                '<br><br>' +

                '<strong>Gender:</strong>' +
                '{{checkbox.genders}}' +
                '<br><br>' +

                '<strong>Breeds:</strong>' +
                '{{checkbox.breeds.toggle}}',
            callback: function () {
                petfinderSort.init();
            }
        }
    });
</script>

Template

If the initial setup is a bit confusing, here's a template to get you started.

<!-- Container that "aside" content will be added to -->
<div data-petfinder="aside"></div>

<!-- Container that "main" content will be added to. The text in here will be replaced when the script loads. -->
<div data-petfinder="main">
    <a href="http://awos.petfinder.com/shelters/AA11.html">View our adoptable pets on Petfinder.</a>
</div>

<script src="https://github.com/cferdinandi/petfinderAPI4everybody/raw/master/dist/js/petfinderAPI4everybody.js"></script>
<script>
    ;(function (window, document, undefined) {

        'use strict';

        // Templates

        var allPets =
            '<div class="{{classes}}">' +
                '<div>' +
                    '<img src="https://github.com/cferdinandi/petfinderAPI4everybody/raw/master/{{photo.1.medium}}">' +
                '</div>' +
                '<h2>{{name}}</h2>' +
                '<p><a href="https://github.com/cferdinandi/petfinderAPI4everybody/blob/master/{{url.pet}}">View Full Profile</a></p>' +
                '<hr>' +
            '</div>';

        var onePet =
            '<p><a href="https://github.com/cferdinandi/petfinderAPI4everybody/blob/master/{{url.all}}">&larr; Back to Full List</a></p>' +
            '<p>' +
                '<a target="_blank" href="https://github.com/cferdinandi/petfinderAPI4everybody/blob/master/{{photo.1.large}}"><img src="https://github.com/cferdinandi/petfinderAPI4everybody/raw/master/{{photo.1.thumbnail.large}}"></a>&nbsp;' +
                '<a target="_blank" href="https://github.com/cferdinandi/petfinderAPI4everybody/blob/master/{{photo.1.large}}"><img src="https://github.com/cferdinandi/petfinderAPI4everybody/raw/master/{{photo.2.thumbnail.large}}"></a>&nbsp;' +
                '<a target="_blank" href="https://github.com/cferdinandi/petfinderAPI4everybody/blob/master/{{photo.1.large}}"><img src="https://github.com/cferdinandi/petfinderAPI4everybody/raw/master/{{photo.3.thumbnail.large}}"></a>' +
            '</p>' +
            '<h2>{{name}}</h2>' +
            '<p>' +
                'Age: {{age}}<br>' +
                'Gender: {{gender}}<br>' +
                'Size: {{size}}' +
            '</p>' +
            '<p>{{options.multi}}</p>' +
            '<div>{{description}}</div>';

        var asideAllPets =
            '<strong>Age:</strong>' +
            '{{checkbox.ages.toggle}}' +
            '<br><br>' +

            '<strong>Size:</strong>' +
            '{{checkbox.sizes}}' +
            '<br><br>' +

            '<strong>Gender:</strong>' +
            '{{checkbox.genders}}' +
            '<br><br>' +

            '<strong>Breeds:</strong>' +
            '{{checkbox.breeds.toggle}}';

        petfinderAPI.init({
            key: '[YOUR PETFINDER API KEY HERE]', // Learn more: https://www.petfinder.com/developers/api-key
            shelter: '[YOUR SHELTER ID]',
            templates: {
                allPets: allPets,
                onePet: onePet,
                asideAllPets: asideAllPets,
            },
            callback: function () {
                petfinderSort.init(); // If you want to use the filtering plugin
            }
        });

    })(window, document);
</script>

Installing with Package Managers

You can install petfinderAPI4everybody.js with your favorite package manager.

Working with the Source Files

If you would prefer, you can work with the development code in the src directory using the included Gulp build system. This compiles, lints, and minifies code.

Dependencies

Make sure these are installed first.

Quick Start

  1. In bash/terminal/command line, cd into your project directory.
  2. Run npm install to install required files.
  3. When it's done installing, run one of the task runners to get going:
    • gulp manually compiles files.
    • gulp watch automatically compiles files and applies changes using LiveReload.

Options and Settings

petfinderAPI4everybody.js includes smart defaults and works right out of the box. But if you want to customize things, it also has a robust API that provides multiple ways for you to adjust the default options and settings.

Global Settings

You can pass options and callbacks into petfinderAPI4everybody.js through the init() function:

petfinderAPI.init({

    // API Defaults
    key: null, // Your API developer key
    shelter: null, // The ID of the shelther you want to get data for
    count: 25, // Number of pets to get data for
    status: 'A', // Adoption status of pets (A = adoptable)
    offset: null, // Skip first x number of pets when retrieving data
    expiration: 60, // How long to save API data for locally, in minutes
    newestFirst: true, // If true, show newest pets first on page

    // Selectors (must be valid CSS selectors)
    selectorAppMain: '[data-petfinder="main"]', // Main content area
    selectorAppAside: '[data-petfinder="aside"]', // Secondary content area

    // Templates
    templates: {
        allPets: null, // Template for page that displays all pets
        onePet: null, // Tempplate for individual pet profiles
        asideAllPets: null, // Template for secondary content on all pets page
        asideOnePet: null, // Template for secondary content on individual pet profiles
    },

    // Class Hooks
    initClass: 'js-petfinder-api', // Added on initialization
    allClass: 'js-petfinder-api-all-pets', // Added when all pets are displayed
    oneClass: 'js-petfinder-api-one-pet', // Added when one pet is displayed

    // Miscellaneous
    titlePrefix: '{{name}}` - | ', // Prefix to add to document title when displaying one pet ({{name}} is replaced with pet name)
    loading: 'Fetching the latest pet info...', // Loading text and graphics
    noPet: noPet: 'Sorry, but this pet is no longer available. <a data-petfinder-async href="https://github.com/cferdinandi/petfinderAPI4everybody/blob/master/{{url.all}}">View available pets.</a>', // Message when petID in query string does not match an available pet ({{url.all}} is replaced with a URL to full pet list)

    // Lists and Checkboxes
    classPrefix: 'pf-', // Prefix to add before all pet classes
    toggleAll: 'Select/Unselect All', // Select/Unselect All checkbox text

    // Pet photos
    noImage: '', // Placeholder image to use when no photo is available

    // Breeds Text
    breedDelimiter: ', ', // Character(s) to use to separate multiple breeds

    // Animal Text
    animalUnknown: '', // Text when animal type is unknown

    // Size Text
    sizeUnknown: 'Not Known', // Text when pet size is unknown
    sizeS: 'Small', // Text for small pets
    sizeM: 'Medium', // Text for medium pets
    sizeL: 'Large', // Text for large pets
    sizeXL: 'Extra Large', // Text for extra large pets

    // Age Text
    ageUnknown: 'Not Known', // Text when pet age is unknown
    ageBaby: 'Baby', // Text for baby pets
    ageYoung: 'Young', // Text for young pets
    ageAdult: 'Adult', // Text for adult pets
    ageSenior: 'Senior', // Text for senior pets

    // Gender Text
    genderUnknown: 'Not Known', // Text when pet gender is unknown
    genderM: 'Male', // Text when pet is a male
    genderF: 'Female', // Text when pet is a female

    // Options Text
    optionsSpecialNeeds: 'Special Needs', // Text for pets with special needs
    optionsNoDogs: 'No Dogs', // Text for pets that can't be in a house with dogs
    optionsNoCats: 'No Cats', // Text for pets that can't be in a house with cats
    optionsNoKids: 'No Kids', // Text for pets that can't be in a house with kids
    optionsNoClaws: 'No Claws', // Text for pets without claws
    optionsHasShot: 'Has hots', // Text for pets that are up-to-date with shots
    optionsHousebroken: 'Housebroken', // Text for housebroken pets
    optionsAltered: 'Spayed/Neutered', // Text for spayed or neutered pets

    // Multi-Option Text
    optionsNoDogsCatsKids: 'No Dogs/Cats/Kids', // Text for pets that can't be in a house with dogs, cats, or kids
    optionsNoDogsCats: 'No Dogs/Cats', // Text for pets that can't be in a house with dogs or cats
    optionsNoDogsKids: 'No Dogs/Kids', // Text for pets that can't be in a house with dogs or kids
    optionsNoCatsKids: 'No Cats/Kids', // Text for pets that can't be in a house with cats or kids

    // Contact Info Missing Text
    contactName: '', // Text when pet's contact name is missing
    contactEmail: '', // Text when pet's contact email is missing
    contactPhone: '', // Text when pet's contact phone number is missing
    contactAddress1: '', // Text when pet's contact first line address is missing
    contactAddress2: '', // Text when pet's contact second line address is missing
    contactCity: '', // Text when pet's contact city is missing
    contactState: '', // Text when pet's contact state is missing
    contactZip: '', // Text when pet's contact zip code is missing
    contactFax: '', // Text when pet's contact fax number is missing

    // Callbacks
    callback: function () {} // Callback to run after each time pet content is generated
});

Use petfinderAPI4everybody.js events in your own scripts

You can also call petfinderAPI4everybody.js events in your own scripts.

destroy()

Destroy the current petfinderAPI.init(). This is called automatically during the init function to remove any existing initializations.

petfinderAPI.destroy();

Browser Compatibility

petfinderAPI4everybody.js works in all modern browsers, and IE 9 and above.

petfinderAPI4everybody.js is built with modern JavaScript APIs. If the JavaScript file fails to load, or if your site is viewed on older and less capable browsers, no API content will be displayed. You should always include fallback content in the [data-petfinder-app="main"] element.

How to Contribute

In lieu of a formal style guide, take care to maintain the existing coding style. Please apply fixes to both the development and production code. Don't forget to update the version number, and when applicable, the documentation.

License

The code is available under the MIT License.