Embedding Widgets

​

Overview

​

Before You Start

• Your configured widget’s embed code (generated in Widget Configuration)
• Access to edit the website where you want to embed the widget
• Basic understanding of your website’s content management system

• Website must support iframe embedding (most modern sites do)
• Sufficient space on your webpage (widgets adapt to container width, minimum height ~150-600px)
• HTTPS-enabled website (recommended for security)

​

Steps

​

Step 1: Get Your Widget Embed Code

1. Navigate to Widget Configuration: Go to Widget → select your program
2. Configure Appearance: Set up colors, titles, and data display preferences
3. Generate Embed Code: Click “Show Embed Code” to reveal implementation options
4. Copy HTML Code: Click “Copy Code” to copy the complete iframe embed code

<!-- Mapademics Career Opportunities Widget -->
<iframe 
  src="https://[bucket-name].s3.amazonaws.com/widget/widget.html?apiKey=[your-api-key]&programId=[program-id]&config=[encoded-config]"
  width="100%" 
  height="150"
  frameborder="0"
  style="border: none;"
  title="Career Opportunities for [Program Name]">
</iframe>

​

Step 2: Choose Your Embedding Method

​

Option A: Content Management System (CMS)

1. Edit Your Page: Open the page editor where you want to add the widget
2. Switch to HTML Mode: Look for “Text,” “HTML,” or “Source Code” view in your editor
3. Paste Embed Code: Insert the complete iframe code where you want the widget to appear
4. Save and Preview: Save your changes and view the page to confirm the widget displays correctly

​

Option B: Website Builder Platforms

1. Add HTML/Embed Element: Look for “HTML,” “Embed,” or “Code” widgets in your platform’s element library
2. Paste Widget Code: Insert your complete iframe embed code into the HTML/embed field
3. Adjust Container Size: Set the container to appropriate dimensions (100% width, 150px+ height)
4. Publish Changes: Save and publish your page updates

​

Option C: Direct HTML Implementation

1. Open HTML File: Access your website’s HTML source code
2. Locate Insertion Point: Find where you want the widget to appear in your page structure
3. Insert Embed Code: Paste the iframe code within appropriate HTML containers
4. Upload Changes: Save and upload your modified HTML files to your web server

​

Step 3: Optimize for Responsive Design

​

Standard Responsive Implementation

<div style="width: 100%; max-width: 1200px; margin: 0 auto;">
  <!-- Your iframe embed code here -->
  <iframe 
    src="https://[widget-url]"
    width="100%" 
    height="150"
    frameborder="0"
    style="border: none; min-width: 320px;"
    title="Career Opportunities Widget">
  </iframe>
</div>

​

Advanced Responsive Container

<div class="widget-responsive-container">
  <!-- Your iframe embed code here -->
</div>

<style>
.widget-responsive-container {
  width: 100%;
  max-width: 1200px;
  margin: 20px auto;
  padding: 0 15px;
  box-sizing: border-box;
}

.widget-responsive-container iframe {
  width: 100%;
  min-height: 150px;
  border: none;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

@media (max-width: 768px) {
  .widget-responsive-container {
    padding: 0 10px;
  }
  
  .widget-responsive-container iframe {
    min-height: 200px;
  }
}
</style>

​

Step 4: Test Your Implementation

1. Desktop Testing: View your page on desktop browsers (Chrome, Firefox, Safari, Edge)
2. Mobile Testing: Check appearance on smartphones and tablets
3. Data Verification: Ensure career opportunity data displays correctly for your program
4. Load Time Testing: Confirm the widget loads quickly without impacting page performance
5. Cross-Browser Testing: Test on multiple browsers your audience commonly uses

​

Integration with Different Platforms

​

WordPress Integration

1. Add a “Custom HTML” block to your page or post
2. Paste your widget embed code into the HTML block
3. Preview and publish your content

1. Switch to the “Text” tab in the editor
2. Paste your embed code where you want the widget
3. Switch back to “Visual” tab to see the widget placeholder

1. Go to Appearance → Widgets
2. Add a “Custom HTML” widget to your desired widget area
3. Paste your embed code and save

​

Drupal Integration

1. Create or Edit Content: Navigate to the page where you want to add the widget
2. Access Text Format: Set text format to “Full HTML” or equivalent
3. Add Embed Code: Paste your iframe code in the content area
4. Save Content: Save your changes and view the published page

​

Custom HTML Sites

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Program Information</title>
</head>
<body>
    <main>
        <section class="program-info">
            <h1>Computer Science Program</h1>
            <p>Explore career opportunities for our Computer Science program:</p>
            
            <!-- Mapademics Widget Embed -->
            <div class="career-widget">
                <iframe 
                  src="https://[your-widget-url]"
                  width="100%" 
                  height="150"
                  frameborder="0"
                  style="border: none;"
                  title="Career Opportunities for Computer Science">
                </iframe>
            </div>
        </section>
    </main>
</body>
</html>

​

What Happens Next

1. Immediate Display: Career opportunity data appears on your website for visitors
2. Automatic Updates: Widget content stays current as your program data changes in Mapademics
3. Enhanced User Experience: Prospective students can explore career outcomes directly on your site
4. Improved Transparency: Your institution demonstrates commitment to student success with real data
5. Marketing Benefits: Course catalogs and program pages gain credibility with employment statistics

​

Responsive Design Considerations

​

Mobile Optimization

• Use width="100%" for automatic resizing
• Set a max-width to prevent excessive stretching on large screens
• Ensure minimum width of 320px for proper mobile display

• Start with height="150" for basic implementations
• Increase height (200-300px) for mobile screens if content appears cramped
• Monitor how data displays on different screen sizes

​

Tablet Considerations

• Test in both portrait and landscape orientations
• Ensure touch targets (links, buttons) are appropriately sized
• Verify readability of salary and employment data

​

Performance Optimization

​

Loading Speed

• Place widget embed code after main page content
• Use loading="lazy" attribute for iframes below the fold
• Avoid wrapping widgets in heavy CSS frameworks unnecessarily

<iframe 
  src="https://[your-widget-url]"
  width="100%" 
  height="150"
  frameborder="0"
  loading="lazy"
  style="border: none;"
  title="Career Opportunities Widget">
</iframe>

​

Caching Considerations

• Widget data updates automatically - no manual cache clearing needed
• Browser caching doesn’t interfere with data freshness
• Content delivery through AWS S3 ensures fast global loading

​

Troubleshooting Common Issues

​

Widget Not Displaying

1. Iframe Restrictions: Some platforms block iframe embedding
   • Solution: Enable iframe embedding in your CMS settings
   • Alternative: Contact your web administrator for assistance
2. Ad Blockers: Browser extensions may block widget content
   • Solution: Test in private/incognito mode or different browsers
   • Note: This affects individual users, not your overall implementation
3. HTTPS Requirements: Mixed content security restrictions
   • Solution: Ensure your website uses HTTPS (most modern sites do)
   • Check: Verify the widget URL uses HTTPS protocol

​

Styling Issues

1. Widget Too Small: Content appears cramped or cut off
   • Solution: Increase iframe height (try 200-300px)
   • Check: Test on mobile devices where content may need more vertical space
2. Width Not Responsive: Widget doesn’t resize with container
   • Solution: Verify iframe width is set to “100%” not a fixed pixel value
   • Enhancement: Add responsive container CSS as shown in Step 3
3. Visual Conflicts: Widget styling clashes with site design
   • Solution: Wrap widget in a neutral container with appropriate margins/padding
   • Advanced: Use CSS to create visual separation from surrounding content

​

Data Display Issues

1. Program Configuration: Ensure your program has completed skills processing
   • Check: Verify in Mapademics dashboard that SOC mappings exist
   • Solution: Complete skills extraction for your program courses
2. API Key Problems: Authentication errors prevent data loading
   • Check: Confirm you’re using the correct embed code from Widget Configuration
   • Solution: Regenerate embed code if you suspect API key issues
3. Program Selection: Wrong program data displays
   • Verify: Check that the program ID in your embed code matches your intended program
   • Fix: Generate new embed code for the correct program

​

Browser Compatibility

• Chrome, Firefox, Safari, Edge: Full support for modern versions
• Internet Explorer: Limited support (consider browser upgrade notices)
• Mobile Browsers: Full support on iOS Safari and Android Chrome

• Older Browsers: May have iframe rendering differences
• Solution: Test with your audience’s most common browser versions
• Fallback: Consider adding browser upgrade messaging for very old browsers

​

Advanced Implementation

​

Custom Styling Integration

<!-- Custom container with site-matching styles -->
<div class="program-career-section">
  <div class="section-header">
    <h2>Career Opportunities</h2>
    <p>Explore employment outcomes for this program:</p>
  </div>
  
  <div class="widget-container">
    <iframe 
      src="https://[your-widget-url]"
      width="100%" 
      height="200"
      frameborder="0"
      style="border: none; border-radius: 8px;"
      title="Career Opportunities Widget">
    </iframe>
  </div>
</div>

<style>
.program-career-section {
  background: #f8f9fa;
  padding: 30px 20px;
  margin: 40px 0;
  border-radius: 12px;
}

.section-header {
  text-align: center;
  margin-bottom: 20px;
}

.widget-container {
  max-width: 1000px;
  margin: 0 auto;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  border-radius: 8px;
  overflow: hidden;
}
</style>

​

Multiple Widget Implementation

1. Use Different Programs: Each iframe should reference a different program ID
2. Unique Containers: Wrap each widget in separately styled containers
3. Performance Consideration: Multiple widgets load independently without conflicts
4. Spacing: Add adequate margin between widgets for visual clarity

​

Security and Privacy

​

Data Protection

• Public API keys limit access to appropriate career data only
• No personal or sensitive institutional information exposed
• CORS (Cross-Origin Resource Sharing) enabled for safe embedding
• HTTPS encryption for all data transmission

• Widgets display public career outcome data only
• No user tracking or personal data collection
• Complies with standard web privacy practices
• No cookies or local storage requirements

​

Best Practices

1. API Key Management: Keep embed codes confidential within your organization
2. Regular Updates: Periodically verify widgets continue displaying correctly
3. Monitoring: Check widget performance as part of regular website maintenance
4. Backup Planning: Keep copies of your embed codes for quick restoration if needed

​

Related Tasks

• Widget Configuration - Customize appearance and data display
• Widget System Overview - Understanding the complete widget ecosystem
• Program Reports - Source data that powers your widgets
• Organization Settings - Managing API keys and permissions