Google Drive Integration Guide

Google Drive Integration Guide

This guide explains how to use the GoogleDriveFolder component to display files from Google Drive on any page in the site.

Overview

The Google Drive integration allows you to:

• Display files from any Google Drive folder
• Show files in a clean grid layout
• Provide preview and download functionality
• Reuse the component across multiple pages

Prerequisites

1. Google Drive API Access: Already configured in the environment
2. Folder Sharing: The Google Drive folder must be shared with the service account
3. Folder ID: You need the Google Drive folder ID

Getting the Folder ID

To get a Google Drive folder ID:

1. Open Google Drive
2. Navigate to the folder you want to display
3. Copy the ID from the URL
   • URL: https://drive.google.com/drive/folders/FOLDER_ID_HERE
   • The ID is the long string after /folders/

Basic Usage

1. Create a New Page

Create a new .md file in the appropriate directory under /src/content/docs/. For example:

• /src/content/docs/protected/member/new-page.md
• /src/content/docs/protected/coreteam/resources.md

2. Use the GoogleDriveFolder Component

---
title: "Your Page Title"
description: "Page description"
roles: ["Member", "CoreTeam", "Admin"]
tags: ["tag1", "tag2"]
status: "published"
lastUpdated: 2024-12-11T00:00:00.000Z
---

import GoogleDriveFolder from '@components/GoogleDriveFolder.astro';

# Your Page Title

Your page content here.

<GoogleDriveFolder
  folderId="YOUR_GOOGLE_DRIVE_FOLDER_ID"
  title="Custom Section Title"
  description="Optional description for your users"
/>

Component Props

The GoogleDriveFolder component accepts the following props:

• folderId (required): Google Drive folder ID
• title (optional): Section title displayed above the files
• description (optional): Description text shown below the title

Example Implementations

Example 1: Simple Policy Library

---
title: "Company Policies"
roles: ["Member", "CoreTeam", "Admin"]
---

import GoogleDriveFolder from '@components/GoogleDriveFolder.astro';

# Company Policies

Browse all company policies and documentation.

<GoogleDriveFolder
  folderId="1ABC123DEF456GHI789JKL012MNO345PQR"
  title="Available Policies"
  description="Click on any document to view or download"
/>

Example 2: Training Materials

---
title: "Training Resources"
roles: ["CoreTeam", "Admin"]
---

import GoogleDriveFolder from '@components/GoogleDriveFolder.astro';

# Training Resources

Access all training materials and guides.

<GoogleDriveFolder
  folderId="1XYZ789ABC456DEF123GHI789JKL012MNO"
  title="Training Library"
/>

Example 3: Marketing Assets

---
title: "Marketing Assets"
roles: ["Admin"]
---

import GoogleDriveFolder from '@components/GoogleDriveFolder.astro';

# Marketing Assets

Download logos, brochures, and marketing materials.

<GoogleDriveFolder
  folderId="1LMN456OPQ789RST012UVW345XYZ789ABC"
  title="Marketing Library"
  description="Official company marketing materials"
/>

Best Practices

1. Folder Organization

• Organize files in Google Drive before linking
• Use clear, descriptive folder names
• Keep folders focused on a single topic

2. File Naming

• Use descriptive file names
• Include dates for versioned documents
• Avoid special characters in file names

3. Access Control

• Set appropriate roles for each page:
  • ["Guest"] - Public content
  • ["Member"] - Team member content
  • ["CoreTeam"] - Core team resources
  • ["Admin"] - Admin-only materials

4. Page Structure

---
title: "Descriptive Title"
description: "Clear description of the page content"
roles: ["Member", "CoreTeam"]  # Choose appropriate roles
tags: ["relevant", "tags"]
status: "published"
lastUpdated: 2024-12-11T00:00:00.000Z
---

import GoogleDriveFolder from '@components/GoogleDriveFolder.astro';

# Main Heading

Brief introduction explaining what this page contains.

<GoogleDriveFolder
  folderId="FOLDER_ID"
  title="Section Title"
  description="Helpful description for users"
/>

---

## Additional Notes

Add any additional context or instructions for users.

How It Works

The Component Flow

1. Component Mounts: The GoogleDriveFolder component loads on the page
2. API Call: It fetches files from /api/pdfs-dev?folderId=YOUR_ID
3. File Display: Files are displayed in a responsive grid
4. User Actions: Users can preview or download each file

API Endpoint Details

The API endpoint (/api/pdfs-dev) accepts:

• folderId (required): Google Drive folder ID
• search (optional): Search query to filter files
• limit (optional): Number of files to return (default: 50)
• offset (optional): Pagination offset (default: 0)

File Display

• Files are shown in a card layout
• Each file shows:
  • File icon based on type
  • File name
  • Preview button (opens in new tab)
  • Download button (downloads file)

Troubleshooting

Common Issues

1. 404 Error: Check that the file path is correct and roles match
2. No Files Showing:
   • Verify the folder ID is correct
   • Ensure the folder is shared with the service account
   • Check that the folder contains PDF files
3. Permission Errors: Make sure the user has the required role

Debugging

1. Check the browser console for errors
2. Verify the API endpoint returns data:

   curl "http://localhost:4321/api/pdfs-dev?folderId=YOUR_ID"

3. Ensure the Google Drive folder is publicly accessible or shared with the service account

Security Considerations

• Folder IDs are not secret, but folder access is controlled
• Always set appropriate roles for sensitive content
• The API validates folder IDs to prevent unauthorized access
• Files are streamed directly from Google Drive, not stored on the server

Performance Notes

• Files are loaded on-demand when the page loads
• The component includes a 5-minute cache to reduce API calls
• Large folders may take longer to load initially
• Consider organizing large collections into sub-folders

Need Help?

If you encounter issues or have questions:

1. Check the browser console for error messages
2. Verify the folder is properly shared
3. Ensure you’re using the correct folder ID
4. Test with a known working folder first