Oluşturma işlemleriyle oluşturma kullanıcı arayüzünü genişletme

Google Workspace'i genişleten Google Workspace eklentileri, kullanıcı Gmail iletilerini okurken kart tabanlı bir arayüz sağlamanın yanı sıra yeni iletiler oluştururken veya mevcut iletilere yanıt verirken de başka bir arayüz sağlayabilir. Bu sayede Google Workspace eklentileri, kullanıcı için e-posta oluşturma görevini otomatik hale getirebilir.

Eklenti oluşturma kullanıcı arayüzüne erişme

Eklentinin oluşturma kullanıcı arayüzünü görüntülemenin iki yolu vardır. İlk yöntem, eklenti açıkken yeni bir taslak oluşturmaya veya yanıtlamaya başlamaktır. İkinci yöntem ise taslak oluştururken eklentiyi başlatmaktır.

Her iki durumda da eklenti, eklenti manifest dosyasında tanımlanan ilgili oluşturma tetikleyici işlevini yürütür. Oluşturma tetikleyici işlevi, oluşturma işlemi için oluşturma kullanıcı arayüzünü oluşturur. Gmail, bu kullanıcı arayüzünü kullanıcıya gösterir.

E-posta oluşturma eklentisi oluşturma

Aşağıdaki genel adımları uygulayarak eklentiye e-posta oluşturma işlevi ekleyebilirsiniz:

1. gmail.composeTrigger alanını eklenti komut dosyası projesinin manifest dosyasına ekleyin ve manifest kapsamlarını, oluşturma işlemleri için gerekenleri içerecek şekilde güncelleyin.
2. Tetikleyici tetiklendiğinde oluşturma kullanıcı arayüzü oluşturan bir oluşturma tetikleyici işlevi uygulayın. Oluşturma tetikleyici işlevleri, oluşturma işlemi için oluşturma kullanıcı arayüzünü oluşturan tek bir Card nesnesi veya Card nesne dizisi döndürür.
3. Kullanıcının Compose kullanıcı arayüzü etkileşimlerine yanıt vermek için gereken ilişkili geri çağırma işlevlerini uygulayın. Bu işlevler, yalnızca oluşturma kullanıcı arayüzünün görünmesine neden olan oluşturma işlemi değildir. Bunun yerine, oluşturma kullanıcı arayüzünün farklı öğeleri seçildiğinde ne olacağını yöneten ayrı işlevlerdir. Örneğin, düğme içeren bir kullanıcı arayüzü kartında genellikle kullanıcı bu düğmeyi tıkladığında yürütülen ilişkili bir geri çağırma işlevi bulunur. Taslak ileti içeriğini güncelleyen widget'ların geri çağırma işlevi bir UpdateDraftActionResponse nesnesi döndürmelidir.

Tetikleyici işlevi oluşturma

Eklentilerin oluşturma kullanıcı arayüzü, eklentilerin mesaj kullanıcı arayüzüyle aynı şekilde oluşturulur. Kart hizmeti, kartlar oluşturmak ve bunları widget'larla doldurmak için kullanılır.

Manifest dosyanızda tanımladığınız gmail.composeTrigger.selectActions[].runFunction uygulamanız gerekir. Oluşturma tetikleyici işlevi, söz konusu işlem için oluşturma kullanıcı arayüzünü oluşturan tek bir Card nesnesi veya Card nesneleri dizisi döndürmelidir. Bu işlevler, bağlamsal tetikleyici işlevlere çok benzer ve kartları aynı şekilde oluşturmalıdır.

Uyarı: Eklentiler, güvenlik nedeniyle Google Workspace veya üçüncü taraf dosya erişim izinlerini sessizce değiştiremez. Örneğin, bir eklenti, e-posta alıcılarını bir Dropbox dosyasını görüntüleyebilecek hesaplar kümesine sessizce ekleyemez. Bunun yerine, eklenti kullanıcıları izin değişikliği hakkında bilgilendirmelidir. Bu tür değişiklikler hakkında kullanıcıları bilgilendirmeyen eklentiler eklenti incelemesini geçemez.

Tetikleyici etkinlik nesneleri oluşturma

Bir oluşturma işlemi seçildiğinde, ilgili oluşturma tetikleyici işlevi yürütülür ve işlev, parametre olarak bir etkinlik nesnesi geçirir. Etkinlik nesnesi, eklenti bağlamı ve tetikleyici işlevine gönderilen taslak hakkında bilgi taşıyabilir.

Bilgilerin etkinlik nesnesinde nasıl düzenlendiğiyle ilgili ayrıntılar için Etkinlik nesnesi yapısı başlıklı makaleyi inceleyin. Etkinlik nesnesinde yer alan bilgiler, gmail.composeTrigger.draftAccess manifest alanı değerine göre kısmen kontrol edilir:

• gmail.composeTrigger.draftAccess manifest alanı NONE ise veya dahil edilmemişse etkinlik nesnesi yalnızca minimum bilgileri içerir.

• gmail.composeTrigger.draftAccess METADATA olarak ayarlanırsa oluşturma tetikleyici işlevine iletilen etkinlik nesnesi, oluşturulan e-postanın alıcılarının listeleriyle doldurulur.

Not: METADATA taslak erişiminin kullanılabilmesi için eklenti manifestinin https://www.googleapis.com/auth/gmail.addons.current.message.metadata Gmail kapsamını içermesi gerekir.

Etkin taslaklara içerik ekleme

Google Workspace eklentilerinin oluşturma kullanıcı arayüzü genellikle kullanıcılara ileti oluşturmaya yardımcı olan seçenekler ve kontroller sunar. Bu kullanım alanlarında, kullanıcı arayüzünde seçimler yapıldıktan sonra eklenti bu seçimleri yorumlar ve mevcut e-posta taslağını buna göre günceller.

Mevcut taslak e-postanın güncellenmesini kolaylaştırmak için Card service aşağıdaki sınıflarla genişletildi:

• ContentType: Değiştirilebilir HTML, değiştirilemez HTML (Gmail kullanıcıları tarafından düzenlenemez) veya düz metin içeriği eklenip eklenmeyeceğini tanımlayan bir enum.
• UpdateDraftActionResponse: Mevcut e-posta taslağını güncelleyen bir işleme verilen yanıtı gösterir.
• UpdateDraftActionResponseBuilder—UpdateDraftActionResponse nesneleri için bir derleyici.
• UpdateDraftBodyAction: Mevcut taslak e-postanın gövdesini güncelleyen bir işlemi temsil eder.
• UpdateDraftBodyType: Gövdenin nasıl değiştirileceğini tanımlayan bir enum.
• UpdateDraftSubjectAction: Mevcut taslak e-postanın konu alanını güncelleyen bir işlemi temsil eder.
• UpdateDraftToRecipientsAction: Mevcut taslak e-postanın alıcılarını güncelleyen bir işlemi temsil eder.
• UpdateDraftCcRecipientsAction: Mevcut taslak e-postanın Cc alıcılarını güncelleyen bir işlemi gösterir.
• UpdateDraftBccRecipientsAction: Mevcut taslak e-postanın Bcc alıcılarını güncelleyen bir işlemi gösterir.

Genellikle bir eklenti oluşturma kullanıcı arayüzünde, kullanıcının kullanıcı arayüzünde seçim yapmayı tamamladığını ve seçimlerinin oluşturduğu e-postaya eklenmesini istediğini belirtmek için tıklayabileceği bir "Kaydet" veya "Ekle" widget'ı bulunur. Bu etkileşimi eklemek için widget'ta, widget tıklandığında eklentiye belirli bir geri çağırma işlevini çalıştırmasını söyleyen ilişkili bir Action nesnesi olmalıdır. Bu geri arama işlevlerini uygulamanız gerekir. Her geri çağırma işlevi, mevcut taslak e-postada yapılacak değişiklikleri ayrıntılı olarak açıklayan yerleşik bir UpdateDraftActionResponse nesnesi döndürmelidir.

1. Örnek

Aşağıdaki kod snippet'inde, mevcut e-posta taslağının konusunu, alıcılarını (To), kopyalarını (Cc) ve gizli alıcılarını (Bcc) güncelleyen bir Compose kullanıcı arayüzünün nasıl oluşturulacağı gösterilmektedir.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getComposeUI(e) {
      return [buildComposeCard()];
    }

    /**
     * Build a card to display interactive buttons to allow the user to
     * update the subject, and To, Cc, Bcc recipients.
     *
     * @return {Card}
     */
    function buildComposeCard() {

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('Update email');
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update subject')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('applyUpdateSubjectAction')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update To recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateToRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Cc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateCcRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Bcc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateBccRecipients')));
      return card.addSection(cardSection).build();
    }

    /**
     * Updates the subject field of the current email when the user clicks
     * on "Update subject" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateSubjectAction() {
      // Get the new subject field of the email.
      // This function is not shown in this example.
      var subject = getSubject();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftSubjectAction(CardService.newUpdateDraftSubjectAction()
              .addUpdateSubject(subject))
          .build();
      return response;
    }

    /**
     * Updates the To recipients of the current email when the user clicks
     * on "Update To recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateToRecipientsAction() {
      // Get the new To recipients of the email.
      // This function is not shown in this example.
      var toRecipients = getToRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftToRecipientsAction(CardService.newUpdateDraftToRecipientsAction()
              .addUpdateToRecipients(toRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Cc recipients  of the current email when the user clicks
     * on "Update Cc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateCcRecipientsAction() {
      // Get the new Cc recipients of the email.
      // This function is not shown in this example.
      var ccRecipients = getCcRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftCcRecipientsAction(CardService.newUpdateDraftCcRecipientsAction()
              .addUpdateToRecipients(ccRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Bcc recipients  of the current email when the user clicks
     * on "Update Bcc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateBccRecipientsAction() {
      // Get the new Bcc recipients of the email.
      // This function is not shown in this example.
      var bccRecipients = getBccRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBccRecipientsAction(CardService.newUpdateDraftBccRecipientsAction()
              .addUpdateToRecipients(bccRecipients))
          .build();
      return response;
    }

2. Örnek

Aşağıdaki kod snippet'inde, mevcut taslak e-postaya resim ekleyen bir Compose kullanıcı arayüzünün nasıl oluşturulacağı gösterilmektedir.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getInsertImageComposeUI(e) {
      return [buildImageComposeCard()];
    }

    /**
     * Build a card to display images from a third-party source.
     *
     * @return {Card}
     */
    function buildImageComposeCard() {
      // Get a short list of image URLs to display in the UI.
      // This function is not shown in this example.
      var imageUrls = getImageUrls();

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('My Images');
      for (var i = 0; i < imageUrls.length; i++) {
        var imageUrl = imageUrls[i];
        cardSection.addWidget(
            CardService.newImage()
                .setImageUrl(imageUrl)
                .setOnClickAction(CardService.newAction()
                      .setFunctionName('applyInsertImageAction')
                      .setParameters({'url' : imageUrl})));
      }
      return card.addSection(cardSection).build();
    }

    /**
     * Adds an image to the current draft email when the image is clicked
     * in the compose UI. The image is inserted at the current cursor
     * location. If any content of the email draft is currently selected,
     * it is deleted and replaced with the image.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @param {event} e The incoming event object.
     * @return {UpdateDraftActionResponse}
     */
    function applyInsertImageAction(e) {
      var imageUrl = e.parameters.url;
      var imageHtmlContent = '<img style=\"display: block\" src=\"'
           + imageUrl + '\"/>';
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
              .addUpdateContent(
                  imageHtmlContent,
                  CardService.ContentType.MUTABLE_HTML)
              .setUpdateType(
                  CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
          .build();
      return response;
    }