Google E-Tablolar ile Apps Komut Dosyası'nın Temelleri #4: Veri Biçimlendirme

1. Giriş

Google E-Tablolar ile Apps Komut Dosyası'nın Temelleri adlı codelab oynatma listesinin dördüncü bölümüne hoş geldiniz.

Bu codelab'i tamamlayarak Apps Komut Dosyası'nda e-tablo verilerinizi nasıl biçimlendireceğinizi ve herkese açık bir API'den alınan biçimlendirilmiş verilerle dolu düzenli e-tablolar oluşturmak için işlevleri nasıl yazacağınızı öğrenebilirsiniz.

Neler öğreneceksiniz?

• Apps Komut Dosyası'nda çeşitli Google E-Tablolar biçimlendirme işlemlerini uygulama
• JSON nesnelerinin ve özelliklerinin listesini Apps Komut Dosyası ile düzenli bir veri sayfasına dönüştürme

Başlamadan önce

Bu codelab, Google E-Tablolar ile Apps Komut Dosyası'nın Temelleri oynatma listesindeki dördüncü codelab'dir. Bu codelab'e başlamadan önce önceki codelab'leri tamamladığınızdan emin olun:

1. Makrolar ve Özel İşlevler
2. E-Tablolar, sayfalar ve aralıklar
3. Verilerle çalışma

İhtiyacınız olanlar

• Bu oynatma listesinin önceki codelab'lerinde ele alınan temel Apps Komut Dosyası konuları hakkında bilgi sahibi olmanız gerekir.
• Apps Komut Dosyası düzenleyici hakkında temel bilgi
• Google E-Tablolar'ı temel düzeyde kullanabilme
• E-Tablolar A1 Notasyonunu okuma özelliği
• JavaScript ve String sınıfı hakkında temel düzeyde bilgi sahibi olma

2. Kur

Devam etmeden önce bazı verilerin bulunduğu bir e-tabloya ihtiyacınız var. Daha önce olduğu gibi, bu alıştırmalar için kopyalayabileceğiniz bir veri sayfası sağladık. Aşağıdaki adımları uygulayın:

1. Veri sayfasını kopyalamak için bu bağlantıyı tıklayın ve ardından Kopya oluştur'u tıklayın. Yeni e-tablo, Google Drive klasörünüze yerleştirilir ve "Veri Biçimlendirme Kopyası" olarak adlandırılır.
2. E-tablo başlığını tıklayın ve "Veri Biçimlendirmesinin Kopyası" olan başlığı "Veri Biçimlendirmesi" olarak değiştirin. E-tablonuz, ilk üç Star Wars filmiyle ilgili bazı temel bilgileri içerecek şekilde aşağıdaki gibi görünmelidir:

3. Komut dosyası düzenleyiciyi açmak için Uzantılar > Apps Komut Dosyası'nı seçin.
4. Apps Komut Dosyası proje başlığını tıklayın ve "Untitled project" olan başlığı "Data Formatting" olarak değiştirin. Başlık değişikliğini kaydetmek için Yeniden adlandır'ı tıklayın.

Bu e-tablo ve proje ile codelab'e başlamaya hazırsınız. Apps Komut Dosyası'nda temel biçimlendirme hakkında bilgi edinmeye başlamak için sonraki bölüme geçin.

3. Özel menü oluşturma

E-Tablolarınıza Apps Komut Dosyası'nda çeşitli temel biçimlendirme yöntemleri uygulayabilirsiniz. Aşağıdaki alıştırmalarda, verileri biçimlendirmenin birkaç yolu gösterilmektedir. Biçimlendirme işlemlerinizi kontrol etmenize yardımcı olmak için ihtiyacınız olan öğeleri içeren özel bir menü oluşturalım. Özel menü oluşturma süreci Verilerle çalışma codelab'inde açıklanmıştı ancak burada tekrar özetleyeceğiz.

Uygulama

Özel bir menü oluşturalım.

1. Apps Komut Dosyası Düzenleyici'de, komut dosyası projenizdeki kodu aşağıdakilerle değiştirin:

/**
 * A special function that runs when the spreadsheet is opened
 * or reloaded, used to add a custom menu to the spreadsheet.
 */
function onOpen() {
  // Get the spreadsheet's user-interface object.
  var ui = SpreadsheetApp.getUi();

  // Create and add a named menu and its items to the menu bar.
  ui.createMenu('Quick formats')
   .addItem('Format row header', 'formatRowHeader')
   .addItem('Format column header', 'formatColumnHeader')
   .addItem('Format dataset', 'formatDataset') 
  .addToUi();
}

2. Senaryo projenizi kaydedin.
3. Komut dosyası düzenleyicide, işlevler listesinden onOpen simgesini seçin ve Çalıştır'ı tıklayın. Bu işlem, e-tablo menüsünü yeniden oluşturmak için onOpen()'ı çalıştırır. Böylece e-tabloyu yeniden yüklemeniz gerekmez.

Kod incelemesi

İşleyiş şeklini anlamak için bu kodu inceleyelim. onOpen() bölümünde, ilk satır bu komut dosyasının bağlı olduğu etkin e-tablonun kullanıcı arayüzünü temsil eden bir Ui nesnesi elde etmek için getUi() yöntemini kullanır.

Sonraki satırlar bir menü (Quick formats) oluşturur, menüye menü öğeleri (Format row header, Format column header ve Format dataset) ekler ve ardından menüyü e-tablonun arayüzüne ekler. Bu işlem sırasıyla createMenu(caption), addItem(caption, functionName) ve addToUi() yöntemleriyle yapılır.

addItem(caption, functionName) yöntemi, menü öğesi etiketi ile menü öğesi seçildiğinde çalışan bir Apps Komut Dosyası işlevi arasında bağlantı oluşturur. Örneğin, Format row header menü öğesinin seçilmesi, E-Tablolar'ın formatRowHeader() işlevini (henüz mevcut olmayan) çalıştırmayı denemesine neden olur.

Sonuçlar

E-tablonuzda, yeni menü öğelerini görüntülemek için Quick formats menüsünü tıklayın:

Bu öğeleri tıkladığınızda, ilgili işlevleri uygulamadığınız için hata oluşur. Bu nedenle, bir sonraki adımda bu işlevleri uygulayacağız.

4. Başlık satırını biçimlendirme

E-tablolardaki veri kümelerinde genellikle her sütundaki verileri tanımlamak için başlık satırları bulunur. Başlık satırlarını, e-tablodaki verilerin geri kalanından görsel olarak ayırmak için biçimlendirmeniz önerilir.

İlk codelab'de, başlığınız için bir makro oluşturup kodunu ayarlamıştınız. Burada, Apps Komut Dosyası'nı kullanarak bir başlık satırını sıfırdan biçimlendireceksiniz. Oluşturacağınız başlık satırında başlık metni kalınlaştırılır, arka plan koyu mavi-yeşil renge, metin beyaz renge boyanır ve bazı düz kenarlıklar eklenir.

Uygulama

Biçimlendirme işlemini uygulamak için daha önce kullandığınız Spreadsheet hizmeti yöntemlerini kullanacaksınız ancak artık hizmetin biçimlendirme yöntemlerinden bazılarını da kullanacaksınız. Aşağıdaki adımları uygulayın:

1. Apps Komut Dosyası Düzenleyici'de, komut dosyası projenizin sonuna aşağıdaki işlevi ekleyin:

/**
 * Formats top row of sheet using our header row style.
 */
function formatRowHeader() {
  // Get the current active sheet and the top row's range.
  var sheet = SpreadsheetApp.getActiveSheet();
  var headerRange = sheet.getRange(1, 1, 1, sheet.getLastColumn());
 
  // Apply each format to the top row: bold white text,
  // blue-green background, and a solid black border
  // around the cells.
  headerRange
    .setFontWeight('bold')
    .setFontColor('#ffffff')
    .setBackground('#007272')
    .setBorder(
      true, true, true, true, null, null,
      null,
      SpreadsheetApp.BorderStyle.SOLID_MEDIUM);

}

2. Senaryo projenizi kaydedin.

Kod incelemesi

Birçok biçimlendirme görevinde olduğu gibi, bu işlemi uygulamak için Apps Komut Dosyası kodu basittir. İlk iki satır, geçerli etkin sayfaya (sheet) ve sayfanın üst satırına (headerRange)) referans almak için daha önce gördüğünüz yöntemleri kullanır. Sheet.getRange(row, column, numRows, numColumns) yöntemi, yalnızca veri içeren sütunlar da dahil olmak üzere üst satırı belirtir. Sheet.getLastColumn() yöntemi, sayfada veri içeren son sütunun sütun dizinini döndürür. Örneğimizde bu sütun E (url) sütunudur.

Not: Burada, biçimlendirmek istediğimiz başlık satırının her zaman 1. satırda olduğunu, verilerimizin A1'den başladığını ve bitişik sütunların bir kısmına yayıldığını varsayıyoruz. Bu alıştırma için bu yaklaşım uygundur ancak genel olarak, kullanıcıların hangi hücrelerin biçimlendirileceğini belirtmesine izin vererek bu varsayımlardan kaçınmak isteyebilirsiniz (e-tablolarının yapısı farklı olabilir).

Kodun geri kalanı, biçimlendirme seçeneklerini headerRange içindeki tüm hücrelere uygulamak için çeşitli Range yöntemlerini çağırır. Kodu kolay okunabilir tutmak için her biçimlendirme yöntemini sırayla çağırmak üzere yöntem zincirleme kullanırız:

• Range.setFontWeight(fontWeight), yazı tipi ağırlığını kalın olarak ayarlamak için kullanılır.
• Range.setFontColor(color), yazı tipi rengini beyaz olarak ayarlamak için kullanılır.
• Range.setBackground(color), arka plan rengini koyu mavi-yeşil olarak ayarlamak için kullanılır.
• setBorder(top, left, bottom, right, vertical, horizontal, color, style), aralığın hücrelerinin etrafına düz siyah bir kenarlık yerleştirir.

Son yöntemin çeşitli parametreleri vardır. Şimdi her birinin ne yaptığını inceleyelim. Buradaki ilk dört parametre (tümü true olarak ayarlanmış) Apps Komut Dosyası'na kenarlığın aralığın üstüne, altına, soluna ve sağına eklenmesi gerektiğini bildirir. Beşinci ve altıncı parametreler (null ve null), Apps Komut Dosyası'nı seçili aralıktaki kenar çizgilerini değiştirmemeye yönlendirir. Yedinci parametre (null), kenarlığın renginin varsayılan olarak siyah olması gerektiğini belirtir. Son olarak, son parametre, SpreadsheetApp.BorderStyle tarafından sağlanan seçeneklerden alınan, kullanılacak kenarlık stili türünü belirtir.

Sonuçlar

Biçimlendirme işlevinizin nasıl çalıştığını görmek için aşağıdakileri yapın:

1. Henüz yapmadıysanız komut dosyası projenizi Apps Komut Dosyası Düzenleyici'ye kaydedin.
2. Hızlı biçimler > Satır başlığını biçimlendir menü öğesini tıklayın.

Not: gmail.com hesabı kullanıyorsanız komut dosyanızı ilk kez kullandığınızda "Bu uygulama doğrulanmadı" iletişim kutusu gösterilebilir. Google, bilinmeyen veya güvenilmeyen yazarlardan kod kullanan kullanıcıları uyarmak için bu bilgiyi kullanır. Bu iletişim kutusunu görüyorsanız komut dosyasının yazarı olduğunuz için devam edebilirsiniz. Komut dosyasını yetkilendirmeye devam etmek için ekrandaki istemleri uygulayın:

1. Doğrulanmamış uygulama iletişim kutusunda Gelişmiş'i tıklayın.
2. Veri Manipülasyonu ve Özel Menüler'e Git (güvenli değil) seçeneğini tıklayın.
3. İzin ver'i tıklayın.

Bu Codelab boyunca çeşitli izin istemleri alabilirsiniz. Bu süreç hakkında daha fazla bilgiyi Google Hizmetleri için yetkilendirme başlıklı makalede bulabilirsiniz.

Sonuçlar aşağıdaki gibi görünmelidir:

Artık bir biçimlendirme görevini otomatik hale getirdiniz. Sonraki bölümde, sütun başlıkları için farklı bir biçim stili oluşturmak üzere aynı teknik uygulanmaktadır.

5. Sütun başlığını biçimlendirme

Kişiselleştirilmiş bir satır başlığı oluşturabiliyorsanız sütun başlığı da oluşturabilirsiniz. Sütun başlıkları, belirli veri kümelerinin okunabilirliğini artırır. Örneğin, bu e-tablodaki başlıklar sütunu aşağıdaki biçim seçenekleriyle geliştirilebilir:

• Metni kalınlaştırma
• Metni italik yapma
• Hücre kenarlığı ekleme
• URL sütunu içeriklerini kullanarak köprü ekleme Bu köprüleri ekledikten sonra, sayfayı temizlemek için url sütununu kaldırabilirsiniz.

Ardından, bu değişiklikleri sayfadaki ilk sütuna uygulamak için bir formatColumnHeader() işlevi uygulayacaksınız. Kodu biraz daha kolay okunabilir hale getirmek için iki yardımcı işlev de uygulayacaksınız.

Uygulama

Daha önce olduğu gibi, sütun başlığı biçimlendirmesini otomatikleştirmek için bir işlev eklemeniz gerekir. Aşağıdaki adımları uygulayın:

1. Apps Komut Dosyası Düzenleyici'de, komut dosyası projenizin sonuna aşağıdaki formatColumnHeader() işlevini ekleyin:

/**
 * Formats the column header of the active sheet.
 */ 
function formatColumnHeader() {  
  var sheet = SpreadsheetApp.getActiveSheet();
  
  // Get total number of rows in data range, not including
  // the header row.
  var numRows = sheet.getDataRange().getLastRow() - 1;
  
  // Get the range of the column header.
  var columnHeaderRange = sheet.getRange(2, 1, numRows, 1);
  
  // Apply text formatting and add borders.
  columnHeaderRange
    .setFontWeight('bold')
    .setFontStyle('italic')
    .setBorder(
      true, true, true, true, null, null,
      null,
      SpreadsheetApp.BorderStyle.SOLID_MEDIUM);
 
  // Call helper method to hyperlink the first column contents
  // to the url column contents.
  hyperlinkColumnHeaders_(columnHeaderRange, numRows); 
}

2. Komut dosyası projenizin sonuna, formatColumnHeader() işlevinden sonra aşağıdaki yardımcı işlevleri ekleyin:

/**
 * Helper function that hyperlinks the column header with the
 * 'url' column contents. The function then removes the column.
 *
 * @param {object} headerRange The range of the column header
 *   to update.
 * @param {number} numRows The size of the column header.
 */
function hyperlinkColumnHeaders_(headerRange, numRows) {
  // Get header and url column indices.
  var headerColIndex = 1; 
  var urlColIndex = columnIndexOf_('url');  
  
  // Exit if the url column is missing.
  if(urlColIndex == -1)
    return; 
  
  // Get header and url cell values.
  var urlRange =
    headerRange.offset(0, urlColIndex - headerColIndex);
  var headerValues = headerRange.getValues();
  var urlValues = urlRange.getValues();
  
  // Updates header values to the hyperlinked header values.
  for(var row = 0; row < numRows; row++){
    headerValues[row][0] = '=HYPERLINK("' + urlValues[row]
      + '","' + headerValues[row] + '")';
  }
  headerRange.setValues(headerValues);
  
  // Delete the url column to clean up the sheet.
  SpreadsheetApp.getActiveSheet().deleteColumn(urlColIndex);
}

/**
 * Helper function that goes through the headers of all columns
 * and returns the index of the column with the specified name
 * in row 1. If a column with that name does not exist,
 * this function returns -1. If multiple columns have the same
 * name in row 1, the index of the first one discovered is
 * returned.
 * 
 * @param {string} colName The name to find in the column
 *   headers. 
 * @return The index of that column in the active sheet,
 *   or -1 if the name isn't found.
 */ 
function columnIndexOf_(colName) {
  // Get the current column names.
  var sheet = SpreadsheetApp.getActiveSheet();
  var columnHeaders =
    sheet.getRange(1, 1, 1, sheet.getLastColumn());
  var columnNames = columnHeaders.getValues();
  
  // Loops through every column and returns the column index
  // if the row 1 value of that column matches colName.
  for(var col = 1; col <= columnNames[0].length; col++)
  {
    if(columnNames[0][col-1] === colName)
      return col; 
  }

  // Returns -1 if a column named colName does not exist. 
  return -1; 
}

3. Senaryo projenizi kaydedin.

Kod incelemesi

Bu üç işlevdeki kodu ayrı ayrı inceleyelim:

formatColumnHeader()

Muhtemelen tahmin edebileceğiniz gibi, bu işlevin ilk birkaç satırı, ilgilendiğimiz sayfaya ve aralığa referans veren değişkenleri ayarlar:

• Etkin sayfa sheet içinde saklanır.
• Sütun başlığındaki satır sayısı hesaplanır ve numRows içine kaydedilir. Burada kod, sütun başlığını satır sayısına dahil etmemek için bir çıkarır: title.
• Sütun başlığını kapsayan aralık columnHeaderRange içinde saklanır.

Ardından kod, formatRowHeader()'daki gibi kenarlıkları ve kalınlaştırmayı sütun başlığı aralığına uygular. Burada, metni italik yapmak için Range.setFontStyle(fontStyle) de kullanılır.

Köprüleri başlık sütununa eklemek daha karmaşık bir işlem olduğundan formatColumnHeader(), görevi tamamlamak için hyperlinkColumnHeaders_(headerRange, numRows)'ı arar. Bu, kodun düzenli ve okunabilir olmasına yardımcı olur.

hyperlinkColumnHeaders_(headerRange, numRows)

Bu yardımcı işlev, önce başlığın (dizinin 1 olduğu varsayılır) ve url sütununun sütun dizinlerini tanımlar. URL sütunu dizinini almak için columnIndexOf_('url') işlevini çağırır. url sütunu bulunamazsa yöntem, herhangi bir veriyi değiştirmeden çıkar.

Bu işlev, üstbilgi sütunu satırlarına karşılık gelen URL'leri kapsayan yeni bir aralık (urlRange) alır. Bu işlem, iki aralığın aynı boyutta olmasını sağlayan Range.offset(rowOffset, columnOffset) yöntemiyle yapılır. Ardından hem headerColumn hem de url sütunlarındaki değerler alınır (headerValues ve urlValues).

Ardından işlev, her sütun başlığı hücre değerini döngüye alır ve başlık ile =HYPERLINK() sütun içeriklerinden oluşturulan bir url E-Tablolar formülüyle değiştirir. Değiştirilen başlık değerleri daha sonra Range.setValues(values) kullanılarak sayfaya eklenir.

Son olarak, sayfayı temiz tutmak ve gereksiz bilgileri ortadan kaldırmak için Sheet.deleteColumn(columnPosition) işlevi çağrılarak url sütunu kaldırılır.

columnIndexOf_(colName)

Bu yardımcı işlev, yalnızca belirli bir adı bulmak için sayfanın ilk satırında arama yapan basit bir yardımcı işlevdir. İlk üç satır, e-tablonun 1. satırındaki sütun başlığı adlarının listesini almak için daha önce gördüğünüz yöntemleri kullanır. Bu adlar, variableColumnNames değişkeninde saklanır.

Ardından işlev, her adı sırayla inceler. Aranan adla eşleşen bir ad bulursa durur ve sütunun dizinini döndürür. Adı bulmadan ad listesinin sonuna ulaşırsa adın bulunmadığını belirtmek için -1 değerini döndürür.

Sonuçlar

Biçimlendirme işlevinizin nasıl çalıştığını görmek için aşağıdakileri yapın:

1. Henüz yapmadıysanız komut dosyası projenizi Apps Komut Dosyası Düzenleyici'ye kaydedin.
2. Hızlı biçimler > Sütun başlığını biçimlendir menü öğesini tıklayın.

Sonuçlar aşağıdaki gibi görünmelidir:

Başka bir biçimlendirme görevini otomatikleştirmiş oldunuz. Sütun ve satır başlıkları biçimlendirildikten sonraki bölümde, verilerin nasıl biçimlendirileceği gösterilmektedir.

6. Veri kümenizi biçimlendirme

Başlıklarınız olduğuna göre şimdi de e-tablonuzdaki verilerin geri kalanını biçimlendiren bir işlev oluşturalım. Aşağıdaki biçimlendirme seçeneklerini kullanacağız:

• Alternatif satır arka plan renkleri (bantlama olarak bilinir)
• Tarih biçimlerini değiştirme
• Kenarlık uygulama
• Tüm sütun ve satırları otomatik boyutlandırma

Şimdi bu biçimleri e-tablo verilerinize uygulamak için bir işlev formatDataset() ve ek bir yardımcı yöntem oluşturacaksınız.

Uygulama

Veri biçimlendirmeyi otomatikleştirmek için daha önce yaptığınız gibi bir işlev ekleyin. Aşağıdaki adımları uygulayın:

1. Apps Komut Dosyası Düzenleyici'de, komut dosyası projenizin sonuna aşağıdaki formatDataset() işlevini ekleyin:

/**
 * Formats the sheet data, excluding the header row and column.
 * Applies the border and banding, formats the 'release_date'
 * column, and autosizes the columns and rows.
 */
function formatDataset() {
  // Get the active sheet and data range.
  var sheet = SpreadsheetApp.getActiveSheet(); 
  var fullDataRange = sheet.getDataRange();

  // Apply row banding to the data, excluding the header
  // row and column. Only apply the banding if the range
  // doesn't already have banding set.
  var noHeadersRange = fullDataRange.offset(
    1, 1,
    fullDataRange.getNumRows() - 1,
    fullDataRange.getNumColumns() - 1);

  if (! noHeadersRange.getBandings()[0]) {
    // The range doesn't already have banding, so it's
    // safe to apply it.
    noHeadersRange.applyRowBanding(
      SpreadsheetApp.BandingTheme.LIGHT_GREY,
      false, false);
  }

  // Call a helper function to apply date formatting
  // to the column labeled 'release_date'.
  formatDates_( columnIndexOf_('release_date') );
  
  // Set a border around all the data, and resize the
  // columns and rows to fit.
  fullDataRange.setBorder(
    true, true, true, true, null, null,
    null,
    SpreadsheetApp.BorderStyle.SOLID_MEDIUM);

  sheet.autoResizeColumns(1, fullDataRange.getNumColumns());
  sheet.autoResizeRows(1, fullDataRange.getNumRows());
}

2. Komut dosyası projenizin sonuna, formatDataset() işlevinden sonra aşağıdaki yardımcı işlevi ekleyin:

/** 
 * Helper method that applies a
 * "Month Day, Year (Day of Week)" date format to the
 * indicated column in the active sheet. 
 *
 * @param {number} colIndex The index of the column
 *   to format.
 */ 
function formatDates_(colIndex) {
  // Exit if the given column index is -1, indicating
  // the column to format isn't present in the sheet.
  if (colIndex < 0)
    return; 

  // Set the date format for the date column, excluding
  // the header row.
  var sheet = SpreadsheetApp.getActiveSheet();
  sheet.getRange(2, colIndex, sheet.getLastRow() - 1, 1)
    .setNumberFormat("mmmm dd, yyyy (dddd)");
}

3. Senaryo projenizi kaydedin.

Kod incelemesi

Bu iki işlevdeki kodu ayrı ayrı inceleyelim:

formatDataset()

Bu işlev, daha önce uyguladığınız biçim işlevleriyle benzer bir kalıba sahiptir. İlk olarak, etkin sayfaya (sheet) ve veri aralığına (fullDataRange) referans tutacak değişkenler alır.

İkincisi, sütun ve satır başlıkları hariç olmak üzere, sayfadaki tüm verileri kapsayan bir aralık (noHeadersRange) oluşturmak için Range.offset(rowOffset, columnOffset, numRows, numColumns) yöntemini kullanır. Ardından kod, bu yeni aralıkta mevcut bantlama olup olmadığını doğrular (Range.getBandings() kullanılarak). Bu işlem, mevcut bir bantlamanın olduğu yere yeni bir bantlama uygulamaya çalıştığınızda Apps Komut Dosyası hata verdiği için gereklidir. Bantlama yoksa işlev, Range.applyRowBanding(bandingTheme, showHeader, showFooter) kullanarak açık gri bir bantlama ekler. Aksi takdirde işlev devam eder.

Bir sonraki adımda, "release_date" etiketli sütundaki tarihleri biçimlendirmek için formatDates_(colIndex) yardımcı işlevi çağrılır (aşağıda açıklanmıştır). Sütun, daha önce uyguladığınız columnIndexOf_(colName) yardımcı işlevi kullanılarak belirtilir.

Son olarak, biçimlendirme işlemi daha önce olduğu gibi başka bir kenarlık eklenerek tamamlanır ve Sheet.autoResizeColumns(columnPosition) ile Sheet.autoResizeColumns(columnPosition) yöntemleri kullanılarak her sütun ve satır, içerdiği verilere uyacak şekilde otomatik olarak yeniden boyutlandırılır.

formatDates_(colIndex)

Bu yardımcı işlev, sağlanan sütun dizinini kullanarak bir sütuna belirli bir tarih biçimi uygular. Özellikle tarih değerlerini "Ay Gün, Yıl (Haftanın Günü)" olarak biçimlendirir.

Not: Komut dosyalarınızda ve e-tablolarınızda kullanabileceğiniz birçok farklı tarih ve sayı biçimi vardır. Daha fazla bilgi için Tarih ve Sayı Biçimleri kılavuzunu inceleyin.

Öncelikle, işlev sağlanan sütun dizininin geçerli olup olmadığını (yani 0 veya daha büyük olup olmadığını) doğrular. Aksi takdirde hiçbir işlem yapmadan geri döner. Bu kontrol, örneğin, sayfada "release_date" sütunu olmaması durumunda oluşabilecek hataları önler.

Sütun dizini doğrulandıktan sonra işlev, bu sütunu kapsayan aralığı (başlık satırı hariç) alır ve biçimlendirmeyi uygulamak için Range.setNumberFormat(numberFormat) kullanır.

Sonuçlar

Biçimlendirme işlevinizin nasıl çalıştığını görmek için aşağıdakileri yapın:

1. Henüz yapmadıysanız komut dosyası projenizi Apps Komut Dosyası Düzenleyici'ye kaydedin.
2. Hızlı biçimler > Veri kümesini biçimlendir menü öğesini tıklayın.

Sonuçlar aşağıdaki gibi görünmelidir:

Bir biçimlendirme görevini daha otomatikleştirdiniz. Bu biçimlendirme komutlarını kullanabildiğinize göre, şimdi de bu komutların uygulanacağı daha fazla veri ekleyelim.

7. API verilerini getirme ve biçimlendirme

Bu codelab'de, e-tablonuzu biçimlendirmek için alternatif bir yöntem olarak Apps Komut Dosyası'nı nasıl kullanabileceğinizi gördünüz. Ardından, herkese açık bir API'den veri çeken, bu verileri e-tablonuza ekleyen ve okunabilir şekilde biçimlendiren bir kod yazacaksınız.

Son codelab'de bir API'den nasıl veri çekeceğinizi öğrenmiştiniz. Burada da aynı teknikleri kullanacaksınız. Bu alıştırmada, elektronik tablonuzu doldurmak için herkese açık Star Wars API'sini (SWAPI) kullanacağız. API'yi, özellikle orijinal üç Star Wars filminde yer alan ana karakterler hakkında bilgi almak için kullanacaksınız.

Kodunuz, API'yi çağırarak büyük miktarda JSON verisi alır, yanıtı ayrıştırır, verileri yeni bir sayfaya yerleştirir ve ardından sayfayı biçimlendirir.

Uygulama

Bu bölümde, bazı ek menü öğeleri ekleyeceksiniz. Her menü öğesi, öğeye özgü değişkenleri ana işleve (createResourceSheet_()) ileten bir sarmalayıcı komut dosyası çağırır. Bu işlevi ve üç yardımcı işlevi daha uygulayacaksınız. Daha önce olduğu gibi, yardımcı işlevler görevin mantıksal olarak bölümlere ayrılmış kısımlarını izole etmeye ve kodun okunabilirliğini korumaya yardımcı olur.

Aşağıdaki işlemleri yapın:

1. Apps Komut Dosyası Düzenleyici'de, komut dosyası projenizdeki onOpen() işlevini aşağıdakiyle eşleşecek şekilde güncelleyin:

/**
 * A special function that runs when the spreadsheet is opened
 * or reloaded, used to add a custom menu to the spreadsheet.
 */
function onOpen() {
  // Get the Ui object.
  var ui = SpreadsheetApp.getUi();

  // Create and add a named menu and its items to the menu bar.
  ui.createMenu('Quick formats')
    .addItem('Format row header', 'formatRowHeader')
    .addItem('Format column header', 'formatColumnHeader')
    .addItem('Format dataset', 'formatDataset')
    .addSeparator()
    .addSubMenu(ui.createMenu('Create character sheet')
                .addItem('Episode IV', 'createPeopleSheetIV')
                .addItem('Episode V', 'createPeopleSheetV')
                .addItem('Episode VI', 'createPeopleSheetVI')
                )
    .addToUi();
}

2. Senaryo projenizi kaydedin.
3. Komut dosyası düzenleyicide, işlevler listesinden onOpen simgesini seçin ve Çalıştır'ı tıklayın. Bu işlem, eklediğiniz yeni seçeneklerle e-tablo menüsünü yeniden oluşturmak için onOpen() komutunu çalıştırır.
4. Apps Komut Dosyası oluşturmak için Dosyalar'ın yanındaki Dosya ekle > Komut Dosyası'nı tıklayın.
5. Yeni komut dosyasına "API" adını verin ve Enter tuşuna basın. (Apps Komut Dosyası, komut dosyası adına otomatik olarak .gs uzantısını ekler.)
6. Yeni API.gs dosyasındaki kodu aşağıdakilerle değiştirin:

/**
 * Wrapper function that passes arguments to create a
 * resource sheet describing the characters from Episode IV.
 */
function createPeopleSheetIV() {
  createResourceSheet_('characters', 1, "IV");
}

/**
 * Wrapper function that passes arguments to create a
 * resource sheet describing the characters from Episode V.
 */
function createPeopleSheetV() {
  createResourceSheet_('characters', 2, "V");
}

/**
 * Wrapper function that passes arguments to create a
 * resource sheet describing the characters from Episode VI.
 */
function createPeopleSheetVI() {
  createResourceSheet_('characters', 3, "VI");
}

/** 
 * Creates a formatted sheet filled with user-specified
 * information from the Star Wars API. If the sheet with
 * this data exists, the sheet is overwritten with the API
 * information.
 *
 * @param {string} resourceType The type of resource.
 * @param {number} idNumber The identification number of the film.
 * @param {number} episodeNumber The Star Wars film episode number.
 *   This is only used in the sheet name.
 */
function createResourceSheet_(
    resourceType, idNumber, episodeNumber) { 
  
  // Fetch the basic film data from the API. 
  var filmData = fetchApiResourceObject_(
      "https://swapi.dev/api/films/" + idNumber);

  // Extract the API URLs for each resource so the code can
  // call the API to get more data about each individually.
  var resourceUrls = filmData[resourceType];
  
  // Fetch each resource from the API individually and push
  // them into a new object list.
  var resourceDataList = []; 
  for(var i = 0; i < resourceUrls.length; i++){
    resourceDataList.push(
      fetchApiResourceObject_(resourceUrls[i])
    ); 
  } 
  
  // Get the keys used to reference each part of data within
  // the resources. The keys are assumed to be identical for
  // each object since they're all the same resource type.
  var resourceObjectKeys = Object.keys(resourceDataList[0]);
  
  // Create the sheet with the appropriate name. It
  // automatically becomes the active sheet when it's created.
  var resourceSheet = createNewSheet_(
      "Episode " + episodeNumber + " " + resourceType);
  
  // Add the API data to the new sheet, using each object
  // key as a column header. 
  fillSheetWithData_(resourceSheet, resourceObjectKeys, resourceDataList);
  
  // Format the new sheet using the same styles the
  // 'Quick Formats' menu items apply. These methods all
  // act on the active sheet, which is the one just created.
  formatRowHeader();
  formatColumnHeader();   
  formatDataset();

}

6. Aşağıdaki yardımcı işlevleri API.gs komut dosyası proje dosyasının sonuna ekleyin:

/** 
 * Helper function that retrieves a JSON object containing a
 * response from a public API.
 *
 * @param {string} url The URL of the API object being fetched.
 * @return {object} resourceObject The JSON object fetched
 *   from the URL request to the API.
 */
function fetchApiResourceObject_(url) {
  // Make request to API and get response.
  var response =
    UrlFetchApp.fetch(url, {'muteHttpExceptions': true});
  
  // Parse and return the response as a JSON object.
  var json = response.getContentText();
  var responseObject = JSON.parse(json); 
  return responseObject; 
}

/** 
 * Helper function that creates a sheet or returns an existing
 * sheet with the same name.
 *
 * @param {string} name The name of the sheet.
 * @return {object} The created or existing sheet
 *   of the same name. This sheet becomes active.
 */ 
function createNewSheet_(name) {
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  
  // Returns an existing sheet if it has the specified
  // name. Activates the sheet before returning.
  var sheet = ss.getSheetByName(name);
  if (sheet) {
    return sheet.activate();
  }
  
  // Otherwise it makes a sheet, set its name, and returns it.
  // New sheets created this way automatically become the active
  // sheet.
  sheet = ss.insertSheet(name); 
  return sheet; 
}

/** 
 * Helper function that adds API data to the sheet.
 * Each object key is used as a column header in the new sheet.
 *
 * @param {object} resourceSheet The sheet object being modified.
 * @param {object} objectKeys The list of keys for the resources.
 * @param {object} resourceDataList The list of API
 *   resource objects containing data to add to the sheet.
 */
function fillSheetWithData_(
    resourceSheet, objectKeys, resourceDataList) {
  // Set the dimensions of the data range being added to the sheet.
  var numRows = resourceDataList.length;
  var numColumns = objectKeys.length;
  
  // Get the resource range and associated values array. Add an
  // extra row for the column headers.
  var resourceRange =
    resourceSheet.getRange(1, 1, numRows + 1, numColumns);
  var resourceValues = resourceRange.getValues(); 
  
  // Loop over each key value and resource, extracting data to
  // place in the 2D resourceValues array.
  for (var column = 0; column < numColumns; column++) {

    // Set the column header.
    var columnHeader = objectKeys[column];
    resourceValues[0][column] = columnHeader;
    
    // Read and set each row in this column.
    for (var row = 1; row < numRows + 1; row++) {
      var resource = resourceDataList[row - 1];
      var value = resource[columnHeader];
      resourceValues[row][column] = value;
    }
  }
  
  // Remove any existing data in the sheet and set the new values.
  resourceSheet.clear()
  resourceRange.setValues(resourceValues);
}

7. Senaryo projenizi kaydedin.

Kod incelemesi

Kısa süre önce çok fazla kod eklediniz. Nasıl çalıştıklarını anlamak için her bir işlevi ayrı ayrı inceleyelim:

onOpen()

Burada, Quick formats menünüze birkaç menü öğesi eklediniz. Ayırıcı çizgi belirledikten sonra Menu.addSubMenu(menu) yöntemini kullanarak üç yeni öğe içeren iç içe menü yapısı oluşturmuşsunuzdur. Yeni öğeler Menu.addItem(caption, functionName) yöntemiyle eklenir.

Sarmalayıcı işlevler

Eklenen menü öğelerinin tümü benzer bir işlem yapıyor: SWAPI'den alınan verilerle bir sayfa oluşturmaya çalışıyorlar. Tek fark, her birinin farklı bir filme odaklanmasıdır.

E-tabloyu oluşturmak için tek bir işlev yazmak ve hangi filmin kullanılacağını belirlemek üzere işlevin bir parametre kabul etmesini sağlamak uygun olacaktır. Ancak Menu.addItem(caption, functionName) yöntemi, menüden çağrıldığında parametreleri iletmenize izin vermez. Peki aynı kodu üç kez yazmaktan nasıl kaçınırsınız?

Yanıt sarmalayıcı işlevlerdir. Bunlar, belirli parametreler ayarlanmış başka bir işlevi hemen çağıran, çağırabileceğiniz basit işlevlerdir.

Burada kodda üç sarmalayıcı işlev kullanılmaktadır: createPeopleSheetIV(), createPeopleSheetV() ve createPeopleSheetVI(). Menü öğeleri bu işlevlere bağlıdır. Bir menü öğesi tıklandığında sarmalayıcı işlev yürütülür ve menü öğesine uygun parametreleri ileterek ana sayfa oluşturucu işlevi createResourceSheet_(resourceType, idNumber, episodeNumber) hemen çağırır. Bu durumda, sayfa oluşturma işlevinden Star Wars filmlerinden birindeki ana karakterlerle ilgili verilerle dolu bir sayfa oluşturması istenir.

Not: İsterseniz farklı türlerdeki sayfaları verilerle doldurmak için daha fazla sarmalayıcı işlev oluşturabilirsiniz. Hangi kaynak türünü isteyeceğinizi ve hangi film kimliğini kullanacağınızı bilmeniz yeterlidir. Örnek kaynak türleri arasında "planets" ve "starships" bulunur. API, film kimliği olarak 1-7 arasındaki sayıları kabul eder.

createResourceSheet_(resourceType, idNumber, episodeNumber)

Bu, bu alıştırmadaki ana sayfa oluşturma işlevidir. Bazı yardımcı işlevlerin yardımıyla API verilerini alır, ayrıştırır, bir sayfa oluşturur, API verilerini sayfaya yazar ve ardından önceki bölümlerde oluşturduğunuz işlevleri kullanarak sayfayı biçimlendirir. Ayrıntıları inceleyelim:

İlk olarak, işlev temel film bilgilerini almak için API'ye istekte bulunmak üzere fetchApiResourceObject_(url) kullanır. API yanıtı, kodun filmlerdeki belirli kişiler (burada kaynaklar olarak bilinir) hakkında daha fazla ayrıntı almak için kullanabileceği bir URL koleksiyonu içerir. Kod, tüm bunları resourceUrls dizisinde toplar.

Ardından, kod resourceUrls içindeki her kaynak URL'si için API'yi çağırmak üzere fetchApiResourceObject_(url) öğesini tekrar tekrar kullanır. Sonuçlar resourceDataList dizisinde saklanır. Bu dizinin her öğesi, filmdeki farklı bir karakteri açıklayan bir nesnedir.

Kaynak veri nesnelerinde, söz konusu karakterle ilgili bilgileri eşleyen çeşitli ortak anahtarlar bulunur. Örneğin, "name" anahtarı, filmdeki karakterin adıyla eşlenir. Ortak nesne yapıları kullanılması amaçlandığından, her kaynak veri nesnesinin anahtarlarının aynı olduğunu varsayıyoruz. Anahtar listesi daha sonra gerektiği için kod, JavaScript Object.keys() yöntemini kullanarak anahtar listesini resourceObjectKeys içinde saklar.

Ardından, oluşturucu işlev, yeni verilerin yerleştirileceği sayfayı oluşturmak için createNewSheet_(name) yardımcı işlevini çağırır. Bu yardımcı işlevi çağırmak yeni sayfayı da etkinleştirir.

Sayfa oluşturulduktan sonra, tüm API verilerini sayfaya eklemek için yardımcı işlev fillSheetWithData_(resourceSheet, objectKeys, resourceDataList) çağrılır.

Son olarak, daha önce oluşturduğunuz tüm biçimlendirme işlevleri, aynı biçimlendirme kurallarını yeni verilere uygulamak için çağrılır. Yeni sayfa etkin olduğundan kod, bu işlevleri değiştirmeden yeniden kullanabilir.

fetchApiResourceObject_(url)

Bu yardımcı işlev, önceki kod laboratuvarı Verilerle çalışma'da kullanılan fetchBookData_(ISBN) yardımcı işlevine benzer. Bu işlev, verilen URL'yi alır ve yanıt almak için UrlFetchApp.fetch(url, params) yöntemini kullanır. Yanıt daha sonra HTTPResponse.getContextText() ve JavaScript JSON.parse(json) yöntemleri kullanılarak bir JSON nesnesine ayrıştırılır. Ardından, ortaya çıkan JSON nesnesi döndürülür.

Not: API'lerle çok çalışıyorsanız bu işlev, API bilgilerini almanız gerektiğinde kullanışlı olabilir. Neredeyse tüm API URL'leriyle çalışacak şekilde genelleştirilmiştir. Bu nedenle, gelecekte kullanmak üzere kaydetmenizi öneririz.

createNewSheet_(name)

Bu yardımcı işlev oldukça basittir. Öncelikle, e-tabloda belirtilen ada sahip bir sayfanın olup olmadığını doğrular. Bu durumda işlev, sayfayı etkinleştirir ve döndürür.

Sayfa yoksa işlev, Spreadsheet.insertSheet(sheetName) ile sayfayı oluşturur, etkinleştirir ve yeni sayfayı döndürür.

fillSheetWithData_(resourceSheet, objectKeys, resourceDataList)

Bu yardımcı işlev, yeni sayfayı API verileriyle doldurmaktan sorumludur. Yeni sayfayı, nesne anahtarlarının listesini ve API kaynak nesnelerinin listesini parametre olarak alır. Her nesne anahtarı, yeni sayfadaki bir sütunu, her kaynak nesnesi ise bir satırı temsil eder.

Öncelikle işlev, yeni API verilerini sunmak için gereken satır ve sütun sayısını hesaplar. Bu, sırasıyla kaynak ve anahtar listesinin boyutudur. Ardından işlev, verilerin yerleştirileceği bir çıkış aralığı (resourceRange) tanımlar ve sütun başlıklarını tutmak için fazladan bir satır ekler. resourceValues değişkeni, resourceRange öğesinden çıkarılan 2 boyutlu değerler dizisini tutar.

Ardından işlev, objectKeys listesindeki her nesne anahtarını döngüye alır. Anahtar, sütun başlığı olarak ayarlanır ve ardından ikinci bir döngü her kaynak nesnesini inceler. Her (satır, sütun) çifti için ilgili API bilgileri resourceValues[row][column] öğesine kopyalanır.

Not: E-Tablolar'daki satır ve sütunların 1 tabanlı, JavaScript dizilerinin ise 0 tabanlı olduğunu unutmayın. Bu fark nedeniyle, Apps Komut Dosyası'nda programlama yaparken genellikle dizinlere 1 eklememiz veya dizinlerden 1 çıkarmamız gerekir.

resourceValues doldurulduktan sonra, önceki menü öğesi tıklamalarından gelen veriler içermesi durumunda hedef sayfa Sheet.clear() kullanılarak temizlenir. Son olarak, yeni değerler sayfaya yazılır.

Sonuçlar

Çalışmanızın sonuçlarını görmek için aşağıdakileri yapabilirsiniz:

1. Henüz yapmadıysanız komut dosyası projenizi Apps Komut Dosyası Düzenleyici'ye kaydedin.
2. Hızlı biçimler > Karakter sayfası oluştur > Bölüm IV menü öğesini tıklayın.

Sonuçlar aşağıdaki gibi görünmelidir:

Artık verileri E-Tablolar'a aktarmak ve otomatik olarak biçimlendirmek için kod yazdınız.

8. Sonuç

Bu codelab'i tamamladığınız için tebrikler. Apps Komut Dosyası projelerinize ekleyebileceğiniz E-Tablolar biçimlendirme seçeneklerinden bazılarını gördünüz ve büyük bir API veri kümesini içe aktarıp biçimlendiren etkileyici bir uygulama oluşturdunuz.

Bu codelab'i faydalı buldunuz mu?

Evet Hayır

Öğrendikleriniz

• Apps Komut Dosyası ile çeşitli E-Tablolar biçimlendirme işlemlerini uygulama
• onOpen() işleviyle alt menü oluşturma
• Getirilen JSON nesneleri listesini Apps Komut Dosyası ile yeni bir veri sayfasına biçimlendirme

Anahtar terimler:

• Etkin (durum): Belirtilen e-tablonun, sayfanın, aralığın veya hücrenin, e-tablo kullanıcısının şu anda görüntülediği ya da vurguladığı öğe olduğunu gösterir.
• Etkin hücre: Etkin sayfada imleç odağıyla vurgulanan tek hücre.
• Etkin aralık: Etkin sayfada şu anda vurgulanan bir veya daha fazla hücre grubu.
• API: Uygulama programlama arayüzü, programların veya komut dosyalarının bilgi istemek ya da belirli işlemleri gerçekleştirmek için çağırabileceği bir hizmettir.
• Yetkilendirme: Kullanıcının, Apps Komut Dosyası'nın ilgili Google hizmetlerindeki kullanıcı verilerine erişmesine veya kullanıcı adına başka işlemler yapmasına izin verme süreci.
• Kapsayıcıya bağlı komut dosyası: Google E-Tablosu veya Google Dokümanı gibi bir Google Workspace dokümanına bağlı olan ve bu dokümandan oluşturulan tüm komut dosyaları.
• Yardımcı işlev: Genellikle özel olan ve küçük bir alt görevi tamamlamak için başka bir işlev tarafından çağrılan işlev. Yardımcı işlevler, alt görevin farklı yerlerde birçok kez tamamlanması gerektiğinde kullanılır.
• JSON: Veri nesnelerini ve özelliklerini metinden tanımlamak için kullanılan dosya biçimi.
• onOpen(): Bir komut dosyasında tanımlanmışsa dosya her açıldığında veya yeniden yüklendiğinde tetiklenen basit bir tetikleyicidir.
• Özel işlevler: Kitaplık kapsamında veya istemciler tarafından sunucu-istemci iletişimi aracılığıyla çağrılamayan işlev. Apps Komut Dosyası'ndaki özel işlevlerin adları _ ile biter.
• Aralık**: Bir sayfadaki bir veya daha fazla bitişik hücre grubu. Range** sınıfı, bir sayfadaki aralıkları okuma ve güncelleme olanağı sunar.
• Komut dosyası düzenleyici: Apps Komut Dosyası için tarayıcı içi kod düzenleyici.
• Basit tetikleyiciler: Apps Komut Dosyası'ndaki tetikleyicilerin bir alt türüdür. Ayrılmış tetikleyici işlev adları ve belirli kısıtlamalar içerir.
• Sayfa**: Bir e-tablonun tek bir sayfası. Bazen Google Drive'daki bir Google E-Tablolar dosyası için kullanılır. Sheet** sınıfı, sayfalara erişmenize ve bunları değiştirmenize olanak tanır.
• SpreadsheetApp: Bu sınıf, E-Tablo hizmetinin üst sınıfı olarak işlev görür ve Google E-Tablolar verilerini okuyan veya değiştiren kod için bir başlangıç noktası sağlar.
• E-tablo**: Google Drive'da bulunan bir Google E-Tablolar dosyası. Spreadsheet** sınıfı, e-tablolara erişmenize ve bunları değiştirmenize olanak tanır.
• E-Tablo hizmeti: Komut dosyalarının Google E-Tablolar dosyalarını oluşturmasına, bunlara erişmesine ve bunları değiştirmesine olanak tanıyan bir Apps Komut Dosyası hizmetidir.
• Tetikleyiciler: Bir Apps Komut Dosyası işlevine göre anahtarlanmış bir etkinlik. Etkinlik (ör. bir e-tablonun açılması) gerçekleştiğinde tetikleyici "çalışır" ve ilişkili Apps Komut Dosyası işlevini otomatik olarak yürütür.
• URL getirme hizmeti: Komut dosyalarının istekte bulunmak ve yanıt almak için URL uç noktalarına bağlanmasına olanak tanıyan Apps Komut Dosyası hizmeti.
• Sarmalayıcı işlevler: Belirli bir parametre grubu iletirken daha karmaşık işlevleri çağırmak için kullanılan basit yardımcı işlevler.

Sırada ne var?

Bu oynatma listesindeki bir sonraki codelab'de, Apps Komut Dosyası'nı kullanarak verileri grafikte görselleştirme ve grafikleri Google Slaytlar sunularına aktarma işlemleri gösterilmektedir.

Bir sonraki codelab'i Slaytlar'da verileri grafik olarak gösterme ve sunma başlıklı makalede bulabilirsiniz.