5 قدم برای ایجاد گالری تصاویر در شیرپوینت 5 steps to create an image gallery in SharePoint

نمایش تصاویر به صورت گالری یکی از جذاب‌ترین و کاربردی‌ترین روش‌ها برای ارایه محتوا در پورتال‌های سازمانی است. ایجاد یک گالری تصاویر سفارشی می‌تواند کمک کند تا تجربه کاربری بهتر و جذاب‌تری برای بازدیدکنندگان خود فراهم کنید. در این مطلب، با استفاده از جاوا اسکریپت و JSOM، مراحل ایجاد یک گالری تصاویر حرفه‌ای در شیرپوینت را به صورت گام به گام بررسی خواهیم کرد. در گالری می‌توانید تصاویر را به راحتی بارگذاری کنید و آن‌ها را بر اساس دسته‌بندی‌ها و سال‌های مختلف نمایش دهید. برای ایجاد گالری تصاویر در شیرپوینت باید این مراحل را طی کنید:

مرحله 1: ساختن سایت کالکشن و مخزن تصاویر

در مرحله نخست باید با استفاده از Central Administration، یک سایت کالکشن مجزا که دیتابیس مخصوص خود را دارد ایجاد کنید؛ این کار باعث می‌شود که بتوانید گالری تصاویر در شیرپوینت را به صورت کاملاً مستقل مدیریت کنید؛ در این سایت کالکشن از چند Picture Library که شامل تصاویر خواهند بود استفاده می‌کنیم؛ در این پروژه من تصاویر سازمان را به تفکیک سال مرتبط با تصویر در مخازن مرتبط قرار دادم. مثلاً تصاویر سال 1403 را در مخزن تصویری به نام 1403 قرار دادم. برای ایجاد کتابخانه تصویر یا همان Picture Library این مراحل را طی کنید:

• وارد سایتی که ایجاد کردید شوید.
• از چرخ‌دنده استفاده کنید و گزینه «افزودن اپ» را انتخاب کنید.
• از میان گزینه‌ها «کتابخانه تصاویر» را انتخاب کنید.
• نام مناسبی برای کتابخانه انتخاب کرده و آن را ایجاد کنید.
• این مراحل را برای هر تعداد کتابخانه‌ای که نیاز دارید تکرار کنید.

در ادامه‌ی تنظیمات اولیه برای ساخت گالری تصاویر در شیرپوینت، افزودن یک ستون به نوع محتوای «عکس» (یا هر نوع محتوای دیگری که به صورت پیش‌فرض در کتابخانه تصاویر شما استفاده شده است) می‌تواند گالری شما را کاربردی‌تر کند؛ در این مرحله، ستونی با نام دسته‌بندی (GalleryCategory) ایجاد خواهیم کرد که به کاربران امکان می‌دهد تصاویر را بر اساس دسته‌بندی‌های مختلف مرتب کنند؛ این ستون از نوع فیلد انتخابی است.

مرحله 2: کاهش حجم فایل‌ها و قرار دادن آن‌ها در مخزن تصاویر

برای بهبود سرعت بارگذاری و بهینه‌سازی عملکرد گالری تصاویر در شیرپوینت، توصیه می‌شود از فشرده‌سازی تصاویر استفاده کنید. اپلیکیشن Flexxi یک برنامه ساده و کارآمد برای کاهش اندازه تصاویر است؛ ابتدا تصاویر را با استفاده از این اپلیکیشن فشرده‌سازی کرده و سپس آن‌ها را در کتابخانه‌های تصاویر که در مرحله قبلی ایجاد کردیم، بارگذاری می‌کنیم.

فشرده‌سازی تصاویر به کاهش حجم فایل‌ها بدون کاهش قابل توجه کیفیت تصویر کمک می‌کند. همچنین در مراحل بعد خواهید دید که از روش لیزی‌لودینگ برای نمایش تصاویر استفاده خواهیم کرد تا فقط زمانی که لازم است تصویر در مرورگر بارگزاری شود. برای استفاده از نرم‌افزار Flexxi این مراحل را طی کنید:

• نرم‌افزار متن‌باز و رایگان Flexxi را دانلود کنید.
• پس از دانلود نرم‌افزار Flexxi را باز کنید.
• تصاویر را بکشید و داخل محیط نرم‌افزار رها کنید.
• از منوی سمت راست گزینه Resize را انتخاب کنید.
• سایز مورد نظر خود را برای کاهش ابعاد تصویر انتخاب کنید.
• در صورت نیاز سایر تنظیمات را بررسی کنید.
• Start را بزنید تا عملیات فشرده‌سازی تصاویر آغاز شود.

می‌بینید که تصاویر با سرعت زیادی فشرده و آماده آپلود در کتابخانه تصویر می‌شوند. پس از اتمام عملیات فشرده‌سازی، تصاویر فشرده شده را در کتابخانه تصویر مورد نظر خود آپلود کنید و حتماً فیلد دسته‌بندی را برای هر تصویر انتخاب کنید.

مرحله 3: ایجاد HTML گالری تصاویر در شیرپوینت

قبل از شروع به نوشتن کد JSOM، باید ساختار HTML گالری را برای نمایش در مسترپیج ایجاد کنید. این جا یک مثال ساده از ساختار HTML برای نمایش گالری آورده شده است؛ در این مرحله، با استفاده از HTML، ساختار اصلی گالری تصاویر را طراحی می‌کنیم. این ساختار شامل دو بخش است: بخش اصلی تصاویر و بخش پیش‌نمایش کوچک تصاویر (یا همان تصاویر بندانگشتی). برای نمایش تصاویر به صورت پویا، از کتابخانه Swiper استفاده شده است؛ این کتابخانه امکان ایجاد اسلایدرهای حرفه‌ای را فراهم می‌کند.

<div class="row mb0">
     <div class="col s10" id="theGalleryImages">
          <div class="swiper" id="mainSwiper">
               <div class="swiper-wrapper" id="imageSliderContainer">
                    <div class="swiper-lazy-preloader"></div>
                         <!-- Slides will be appended here -->
                    </div>

                    <!-- Navigation Buttons -->
                    <div class="swiper-button-next"></div>
                    <div class="swiper-button-prev"></div>

               </div>
          </div>
          <div class="col s2">
               <div class="swiper mtHalf" id="thumbSwiper">
                    <div class="swiper-wrapper" id="imageSliderThumbs">
                         <div class="swiper-lazy-preloader"></div>
                         <!-- Slides will be appended here -->
                    </div>
               <div class="swiper-scrollbar"></div>
          </div>
     </div>
</div>
            
<link rel="stylesheet" href="css/swiper-bundle.min.css" />
<script src="js/galleryHome.js"></script>
<script src="js/swiper-bundle.min.js"></script>

این کد HTML را می‌توانید با روش‌های مختلفی در صفحات شیرپوینت قرار دهید. مثلاً می‌توانید از مسترپیج و قالب صفحات استفاده کنید یا می‌توانید کدها را در یک وب پارت قرار دهید. من برای نمایش گالری تصاویر از کتابخانه Swiper استفاده کرده‌ام، اما با این روش می‌توان از هر کتابخانه‌ای برای ساختن اسلایدشو استفاده کرد.

همان طور که در HTML می‌بینید، اسلایدر اصلی با شناسه mainSwiper مشخص شده است. تصاویر اصلی در عنصر swiper-wrapper اضافه خواهند شد؛ همچنین پیش‌نمایش تصاویر با شناسه thumbSwiper تعریف شده است. ضمناً یک نوار اسکرول برای پیش‌نمایش‌ها وجود دارد. در نهایت فایل CSS مربوط به Swiper و دو فایل جاوااسکریپت galleryHome.js و swiper-bundle.min.js فراخوانی شده‌اند.

مرحله 4: نمایش دسته‌بندی‌های گالری تصاویر در شیرپوینت

در این مرحله، دسته‌بندی تصاویر از کتابخانه‌های شیرپوینت خوانده شده و به صورت پویا در رابط کاربری گالری نمایش داده می‌شود. این کار با استفاده از کد جاوااسکریپت و JSOM انجام می‌شود. کد زیر شامل بخش‌های مختلف برای دریافت دسته‌بندی‌ها و ایجاد رابط کاربری مربوطه است:

$(document).ready(function () {
     ExecuteOrDelayUntilScriptLoaded(initializeGallery, "SP.js")
})

function initializeGallery() {
     $('.galleryCatContainer').each((_, container) => {
          getGalleryCategories(container.id)
     })
     getImages()
}
function getGalleryCategories(year) {
     const context = SP.ClientContext.get_current()
     const list = context.get_web().get_lists().getByTitle(year)
     const camlQuery = new SP.CamlQuery()

     camlQuery.set_viewXml(`
          <View>
               <Query>
                    <OrderBy>
                         <FieldRef Name="ID" Ascending="FALSE" />
                    </OrderBy>
               </Query>
               <ViewFields>
                    <FieldRef Name="GalleryCategory" />
               </ViewFields>
               <RowLimit>5000</RowLimit>
          </View>
     `)

     const listItems = list.getItems(camlQuery)
     context.load(listItems)

     context.executeQueryAsync(
          () => {
               const categoryCounts = {}

               // Count items by category
               listItems.get_data().forEach(item => {
                    const category = item.get_item('GalleryCategory')
                    if (category) {
                         categoryCounts[category] = (categoryCounts[category] || 0) + 1
                    }
          })

          // Generate HTML for categories with counts
          const categoryHtml = Object.entries(categoryCounts)
               .map(
                    ([category, count]) => `
                         <div class="gallery-category" data-year="${year}" data-category="${category}">
                              <a class="white-text" href="#">
                                   <span>${category}</span>
                                   <strong>(${count})</strong>
                              </a>
                         </div>`
                    )
               .join('')

               const container = $(`#${year}.galleryCatContainer`)
               container.html(categoryHtml)

               container.off('click').on('click', '.gallery-category', function (e) {
                    e.preventDefault()
                    $('.gallery-category').removeClass('activeCategory')
                    $(this).addClass('activeCategory')
                    getImages($(this).data('category'), false, year)
               })
          },
          sender => console.error('Error loading gallery categories:', sender.get_message())
     )
}

در این کد، از تابع ExecuteOrDelayUntilScriptLoaded برای اطمینان از لود شدن کامل کتابخانه SP.js استفاده شده است. در تابع getGalleryCategories یک کوئری CAML نوشته شده که تمام مقادیر ستون GalleryCategory را از کتابخانه مربوطه می‌خواند؛ سپس دسته‌بندی‌ها به همراه تعداد آیتم‌های هر دسته در قالب HTML  تولید می‌شوند. هر دسته با یک لینک نمایش داده می‌شود که با کلیک روی آن، دسته به‌عنوان فعال (activeCategory) تنظیم شده و تصاویر مربوط به آن دسته با تابع getImages بارگذاری می‌شوند.

مرحله 5: بارگذاری و نمایش تصاویر

در این مرحله، تصاویر گالری با استفاده از کد جاوااسکریپت و JSOM از لیست شیرپوینت دریافت شده و در رابط کاربری گالری نمایش داده می‌شوند. تصاویر بر اساس دسته‌بندی انتخاب‌شده (در صورت وجود) بارگذاری می‌شوند.

function getImages(selectedCategory = null, limit = true, year = '1403') {
    const context = SP.ClientContext.get_current()
    const list = context.get_web().get_lists().getByTitle(year)

    // Build CAML query
    const camlQuery = new SP.CamlQuery()
    const queryConditions = selectedCategory
        ? `
            <Where>
                <Eq>
                    <FieldRef Name="GalleryCategory" />
                    <Value Type="Text">${selectedCategory}</Value>
                </Eq>
            </Where>
        ` : ''
    const rowLimit = limit ? `<RowLimit>15</RowLimit>` : ''

    camlQuery.set_viewXml(`
        <View>
            <Query>
                ${queryConditions}
                <OrderBy><FieldRef Name="Created" Ascending="FALSE" /></OrderBy>
            </Query>
            ${rowLimit}
        </View>
    `)

    const listItems = list.getItems(camlQuery)
    context.load(listItems)

    context.executeQueryAsync(
        () => {
            const items = listItems.get_data()
            const sliderHtml = items.map(item => {
                const fileRef = item.get_item('FileRef') || ''
                const fileDescription = item.get_item('Description') || ''
                const shamsiDate = new Date(item.get_item('Created')).toLocaleDateString('fa-IR')

                return `
                    <div class="swiper-slide">
                        <img src="${fileRef}" alt="Gallery Image" class="swiper-lazy" loading="lazy" />
                        <a href="${fileRef}" target="_blank" class="fullScreenKDM">
                            <img src="https://portal.tiddev.com/sites/Gallery/Shared%20Documents/fullscreen.png" />
                            <strong class="galleryUploadTime">تاریخ آپلود: ${shamsiDate}</strong>
                        </a>
                        ${fileDescription ? `<p>${fileDescription}</p>` : ''}
                    </div>
                `
            }).join('')

            // Update Swiper container
            $('#imageSliderContainer').html(sliderHtml)
            $('#imageSliderThumbs').html(sliderHtml)

            // Reinitialize Swiper
            if (window.mySwiper) window.mySwiper.destroy(true, true)

            window.mySwiperThumbs = new Swiper('#thumbSwiper', {
                direction: 'vertical',
                spaceBetween: 10,
                slidesPerView: 5,
                grabCursor: true,
                mousewheel: { invert: false },
                scrollbar: {
                    el: '.swiper-scrollbar',
                    draggable: true,
                },
            })
            window.mySwiper = new Swiper('#mainSwiper', {
                loop: true,
                navigation: { nextEl: '.swiper-button-next', prevEl: '.swiper-button-prev' },
                slidesPerView: 1,
                spaceBetween: 10,
                grabCursor: true,
                mousewheel: { invert: false },
                thumbs: { swiper: window.mySwiperThumbs },
            })
        },
        (sender, args) => console.error('Error loading images:', args.get_message())
    )
}

در کد بالا، در صورت انتخاب دسته‌بندی، تصاویر مرتبط با دسته‌بندی و سال انتخاب شده، بر اساس تاریخ ایجاد به صورت نزولی مرتب می‌شوند، تصاویر و اطلاعات مرتبط از لیست شیرپوینت دریافت می‌شوند و برای هر تصویر، آدرس فایل، توضیحات (در صورت وجود) و تاریخ شمسی آپلود استخراج می‌شود. سپس کد HTML لازم برای نمایش تصاویر در قالب اسلایدر تولید می‌شود. اسلایدر اصلی و اسلایدر تصاویر بندانگشتی با استفاده از Swiper.js ایجاد و مقداردهی می‌شوند و در نهایت تصاویر در هر دو اسلایدر قرار می‌گیرند.

نسخه‌های سازگار شیرپوینت

من این پروژه را در شیرپوینت 2019 پیاده‌سازی کردم، اما می‌توانید از این تکنیک‌ها در نسخه‌های قدیمی‌تر یا جدیدتر شیرپوینت، مانند 2016 و 2013 و SE نیز استفاده کنید. توجه داشته باشید که ممکن است برخی از ویژگی‌ها یا جزئیات نحوه استفاده بسته به نسخه‌های مختلف تغییر کنند. این تکنیک مبتنی بر استفاده از JSOM برای تعامل با لیست‌های شیرپوینت و دریافت اطلاعات به کمک کوئری CAML است؛ برای اطمینان از عملکرد صحیح این تکنیک، نسخه شیرپوینت باید از JSOM و CAML Query پشتیبانی کند.

نتیجه‌گیری نهایی

در این مطلب، مراحل ایجاد یک گالری تصاویر در شیرپوینت با استفاده از JSOM شرح داده شد؛ با دنبال کردن این مراحل، می‌توانید گالری تصاویری با قابلیت دسته‌بندی، نمایش و تعامل آسان ایجاد کنید که نسبت به امکانات پیش‌فرض شیرپوینت، تجربه کاربری بهتری برای کاربران فراهم می‌آورد. به صورت خلاصه، مراحل انجام شده شامل این موارد بودند:

• ابتدا با ایجاد یک مجموعه سایت و کتابخانه‌های تصاویر، بستر مورد نیاز را ایجاد کردیم.
• با استفاده از نرم‌افزار Flexxi اندازه تصاویر کاهش یافت و سپس تصاویر آپلود شدند.
• با طراحی HTML مناسب، ساختار گالری به شکلی زیبا و کاربرپسند تنظیم شد.
• دسته‌بندی تصاویر و نمایش آن‌ها بر اساس نیاز کاربران با استفاده از JSOM و کوئری‌های CAML انجام شد.
• در نهایت، تصاویر با استفاده از پلاگین Swiper.js در قالب یک اسلایدر نمایش داده شدند.