سرویس HTML: HTML الگو

شما می‌توانید از قالب‌ها برای ترکیب کد اسکریپت گوگل اپس و HTML استفاده کنید تا صفحات پویا را با حداقل تلاش بسازید. اگر از زبان‌های قالب‌سازی که کد و HTML را ترکیب می‌کنند، مانند PHP، ASP یا JSP، استفاده کرده‌اید، سینتکس آنها باید برایتان آشنا باشد.

اسکریپتلت‌ها

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

اگر مثال زیر را در ویرایشگر اسکریپت قرار دهید، محتویات برچسب <?= ... ?> (یک اسکریپت‌لت چاپ ) به صورت ایتالیک ظاهر می‌شود. این کد قبل از اینکه صفحه به کاربر ارائه شود، روی سرور اجرا می‌شود. از آنجا که کد اسکریپت‌لت قبل از ارائه صفحه اجرا می‌شود، فقط می‌تواند یک بار در هر صفحه اجرا شود. برخلاف توابع جاوا اسکریپت سمت کلاینت یا اسکریپت برنامه‌ها که از طریق google.script.run فراخوانی می‌کنید، اسکریپت‌لت‌ها نمی‌توانند پس از بارگذاری صفحه دوباره اجرا شوند.

کد.gs 

function doGet() {
  return HtmlService
      .createTemplateFromFile('Index')
      .evaluate();
}

فهرست.html 

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    Hello, World! The time is <?= new Date() ?>.
  </body>
</html>

توجه داشته باشید که تابع doGet برای HTML قالب‌بندی شده با مثال‌هایی که برای ایجاد و ارائه HTML پایه ارائه می‌شوند، متفاوت است. تابعی که در اینجا نشان داده شده است، یک شیء HtmlTemplate را از فایل HTML تولید می‌کند، سپس متد evaluate خود را برای اجرای اسکریپت‌لت‌ها و تبدیل الگو به یک شیء HtmlOutput که اسکریپت می‌تواند به کاربر ارائه دهد، فراخوانی می‌کند.

اسکریپت‌های استاندارد

اسکریپت‌های استاندارد که از سینتکس <? ... ?> استفاده می‌کنند، کد را بدون ارسال صریح محتوا به صفحه اجرا می‌کنند. با این حال، همانطور که این مثال نشان می‌دهد، نتیجه کد درون یک اسکریپتلت همچنان می‌تواند بر محتوای HTML خارج از اسکریپتلت تأثیر بگذارد:

کد.gs 

function doGet() {
  return HtmlService
      .createTemplateFromFile('Index')
      .evaluate();
}

فهرست.html 

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <? if (true) { ?>
      <p>This is always served!</p>
    <? } else  { ?>
      <p>This is never served.</p>
    <? } ?>
  </body>
</html>

اسکریپت‌های چاپ‌شده، که از سینتکس <?= ... ?> استفاده می‌کنند، نتایج کد خود را با استفاده از escape کردن متنی در صفحه نمایش می‌دهند.

گریز متنی به این معنی است که Apps Script متن خروجی را در صفحه - درون یک ویژگی HTML، درون یک تگ script سمت کلاینت یا هر جای دیگر - ردیابی می‌کند و به طور خودکار کاراکترهای گریز را برای محافظت در برابر حملات اسکریپت نویسی بین سایتی (XSS) اضافه می‌کند.

در این مثال، اولین اسکریپتِ چاپ، مستقیماً یک رشته را چاپ می‌کند؛ به دنبال آن یک اسکریپتِ استاندارد می‌آید که یک آرایه و یک حلقه را تنظیم می‌کند و به دنبال آن یک اسکریپتِ چاپِ دیگر برای چاپ محتویات آرایه می‌آید.

کد.gs 

function doGet() {
  return HtmlService
      .createTemplateFromFile('Index')
      .evaluate();
}

فهرست.html 

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <?= 'My favorite Google products:' ?>
    <? var data = ['Gmail', 'Docs', 'Android'];
      for (var i = 0; i < data.length; i++) { ?>
        <b><?= data[i] ?></b>
    <? } ?>
  </body>
</html>

توجه داشته باشید که یک اسکریپت چاپ فقط مقدار اولین دستور خود را چاپ می‌کند؛ سایر دستورات طوری رفتار می‌کنند که گویی در یک اسکریپت استاندارد قرار دارند. بنابراین، برای مثال، اسکریپت <?= 'Hello, world!'; 'abc' ?> فقط عبارت "Hello, world!" را چاپ می‌کند.

چاپ اجباری اسکریپتلت‌ها

اسکریپت‌لت‌های چاپ اجباری، که از سینتکس <?!= ... ?> استفاده می‌کنند، مانند اسکریپت‌لت‌های چاپ هستند، با این تفاوت که از escape کردن متن اجتناب می‌کنند.

اگر اسکریپت شما اجازه ورود ورودی‌های غیرقابل اعتماد از کاربر را می‌دهد، گریز از متن مهم است. در مقابل، اگر خروجی اسکریپت‌لت شما عمداً شامل HTML یا اسکریپت‌هایی باشد که می‌خواهید دقیقاً مطابق با مشخصات وارد کنید، باید از چاپ اجباری استفاده کنید.

به عنوان یک قاعده کلی، از چاپ اسکریپتلت‌ها به جای چاپ اجباری اسکریپتلت‌ها استفاده کنید، مگر اینکه بدانید که باید HTML یا جاوا اسکریپت را بدون تغییر چاپ کنید.

کد اسکریپت برنامه‌ها در اسکریپت‌لت‌ها

اسکریپت‌لت‌ها محدود به اجرای جاوااسکریپت معمولی نیستند؛ شما همچنین می‌توانید از هر یک از سه تکنیک زیر برای دسترسی قالب‌های خود به داده‌های اسکریپت برنامه‌ها استفاده کنید.

با این حال، به یاد داشته باشید که از آنجا که کد قالب قبل از ارائه صفحه به کاربر اجرا می‌شود، این تکنیک‌ها فقط می‌توانند محتوای اولیه را به صفحه ارائه دهند. برای دسترسی تعاملی به داده‌های اسکریپت برنامه‌ها از یک صفحه، به جای آن از API google.script.run استفاده کنید.

فراخوانی توابع اسکریپت برنامه‌ها از یک الگو

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

کد.gs 

function doGet() {
  return HtmlService
      .createTemplateFromFile('Index')
      .evaluate();
}

function getData() {
  return SpreadsheetApp
      .openById('1234567890abcdefghijklmnopqrstuvwxyz')
      .getActiveSheet()
      .getDataRange()
      .getValues();
}

فهرست.html 

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
  </head>
  <body>
    <? var data = getData(); ?>
    <table>
      <? for (var i = 0; i < data.length; i++) { ?>
        <tr>
          <? for (var j = 0; j < data[i].length; j++) { ?>
            <td><?= data[i][j] ?></td>
          <? } ?>
        </tr>
      <? } ?>
    </table>
  </body>
</html>

فراخوانی مستقیم APIهای اسکریپت برنامه‌ها

همچنین می‌توانید از کد Apps Script مستقیماً در اسکریپت‌لت‌ها استفاده کنید. این مثال با بارگذاری داده‌ها در خود قالب به جای بارگذاری از طریق یک تابع جداگانه، همان نتیجه مثال قبلی را به دست می‌آورد.

کد.gs 

function doGet()