راهنمای ساخت و کد نویسی قالب

مقدمه

در این سند اطلاعات لازم درباره ی سیستم قالب های سایت ساز کانی وب معرفی می شود. مخاطب این سند طراحان قالب که قصد طراحی یا ایجاد تغییر در قالب های سیستم سایت ساز کانی وب را دارند، می باشد.

پیش نیاز ها:

  • آشنایی با مفاهیم ابتدایی اینترنت و وب
  • آشنایی با زبان های HTML و CSS
  • آشنایی با نحوه ی کار و امکانات سیستم سایت ساز کانی وب
  • آشنایی مقدماتی با XML
  • آشنایی مقدماتی با زبان انگلیسی


1. ساختار یک قالب

همان طور که می دانید، یک قالب سایت از تعدادی فایل HTML ،CSS ،Javascript، تصویر و ... تشکیل شده است. طرح های ساخته شده بر پایه ی HTML به خودی خود ایستا می باشند؛ یعنی ساختاری معین و ثابت دارند. برای این که چنین طرح های ایستایی را به صورت پویا به سیستم سایت ساز کانی وب معرفی کنید باید علاوه بر ساختار و فایل های خود قالب، اطلاعات دیگری را نیز در اختیار سیستم قرار بدهید.

این اطلاعات در قالب دو بخش مجزا به سیستم معرفی می شوند:

  1. فایل های الگو مبتنی بر زبان Twig: این فایل ها در واقع همان فایل های HTML می باشند که دارای برچسب های اضافی در یک زبان برنامه نویسی به نام Twig می باشند. تگ های اضافی ساختار HTML را پویا کرده و همچنین امکاناتی برای پیاده سازی منطق های پیچیده با زبانی ساده فراهم می کنند.
     
  2. فایل توصیف قالب Template.xml: این فایل شامل اطلاعاتی درباره ی ساختار کلی قالب، امکانات و ساختمان داده های موجود در هر قالب می باشد. همچنین در این فایل معین می شود که قالب دارای چه صفحاتی می باشند و فایل الگوی متناظر با هر صفحه چیست. همچنین در این فایل مشخص می کنید که هر صفحه چه داده هایی را به عنوان گزینه در اختیار کاربر قرار می دهد؛ ساختار این داده ها در قالب ساختمان های داده معین می شوند.

  3. فایل توصیف قالب

    در این بخش به بررسی فایل توصیف قالب می پردازیم.


    1. فایل Template.xml

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

    در فایل توصیف قالب با استفاده از شمای مختص سیستم کانی وب (که در ادامه توضیح داده می شود)، بر اساس XML، ویژگی ها و امکانات قالب را توصیف می کنید.

    جهت جلو گیری از بروز خطا و استاندارد شدن این فایل، کانی وب شمای استانداردی را توسط یک فایل XSD برای Template.xml معین کرده است. در این فایل ترتیب عناصر، ویژگی های قابل استفاده و مقادیر قابل قبول هر ویژگی مشخص می شوند؛ علاوه بر اینکه سیستم کانی وب فایل xml ساخته شده توسط شما را توسط این فایل بررسی خواهد کرد؛ می توانید در برنامه های IDE ز این فایل استفاده کنید تا از ویژگی هایی مانند Code Completion برای سهولت و سرعت طراحی فایل توصیف قالب استفاده کنید.

    هنگام دریافت KTDK این یک فایل نمونه ی XML به شما داده می شود که به طور خودکار به فایل توصیف شمای کانی وب ارجاع دارد.


    2. ساختار کلی

    در زیر ساختار کلی فایل توصیف قالب را مشاهده می کنید، دقت داشته باشید ترتیب المان ها در این لیست مهم می باشد. خصوصیت schema-version معین می کند که فایل توصیف قالب فعلی بر اساس چه نسخه ای از شمای توصیف کانی وب نوشته شده است:

            <?xml version="1.0" encoding="UTF-8"?>
    <Template schema-version="1.0">
        <!-- Template information and meta data -->
        <Info>
            
        </Info>
    
        <!-- Data Structures are defined here -->
        <DataStructuresDefinition>
            
        </DataStructuresDefinition>
    
        <!-- List of template pages -->
        <Pages>
            
        </Pages>
    
        <!-- Here we define which pages are the default for each system page -->
        <DefaultPages>
            
        </DefaultPages>
    
        <!-- Template's global option groups -->
        <GlobalOptions>
            
        </GlobalOptions>
    
        <!-- List of icons in the dashboard specific to this template -->
        <DashboardShortcuts>
            
        </DashboardShortcuts>
    
    </Template>
          
    در ادامه محتویات هر برچسب را بررسی می کنیم.


    3. اطلاعات قالب

    این بخش بزودی تکمیل می شود ...


    4. ساختمان های داده

    این بخش بزودی تکمیل می شود ...


    5. لیست صفحات

    این بخش بزودی تکمیل می شود ...


    6. تعیین صفحات پیش فرض

    این بخش بزودی تکمیل می شود ...


    7. تعیین تنظیمات قالب

    این بخش بزودی تکمیل می شود ...


    8. ایجاد آیکن در داشبورد

    این بخش بزودی تکمیل می شود ...


    زبان قالب نویسی Twig

    در این بخش به بررسی زبان برنامه نویسی Twig می پردازیم؛ از این زبان برای برنامه نویسی قالب های سیستم کانی وب استفاده می شود. با استفاده از این زبان می توانیم ساختار پویای مورد نیاز قالب ها را با استفاده از HTML ایستا تولید کنیم.


    1. فایل الگو

    یک الگو تنها یک فایل متنی است که می تواند هر فرمت بر پایه متن مانند HTML, XML, CSV را تولید کند. قالب ها دارای پسوند خاصی نیستند و عموما از پسوند های .html و .xml استفاده می شود.

    یک فایل الگو دارای متغییرها و عباراتی است که می توانند به هنگام ارزیابی قالب با مقادیری جایگزین شوند. علاوه بر این ها در یک قالب برچسب هایی برای کنترل منطق قالب وجود دارند.

    در متن زیر یک قالب کمینه و کوتاه نشان داده شده است که چتد مفهوم پایه ای را نشان می دهد. در ادامه جزئیات بیشتری ارائه می شود.

    <!DOCTYPE html>
    <html>
        <head>
            <title>My Webpage</title>
        </head>
        <body>
            <ul id="navigation">
            {% for item in navigation %}
                <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
            {% endfor %}
            </ul>
    
            <h1>My Webpage</h1>
            {{ a_variable }}
        </body>
    </html>

    نکته ی مهم:
    همانطور که می بینید دو نوع جداکننده(delimiter) وجود دارد: {% ... %} و {{ ... }} . نوع اول برای اجرای عباراتی مانند دستورات حلقه به کار می رود و نوع دوم نتیجه یک عبارت را در قالب چاپ می کند.
    همچنین می توانید توضیحات را داخل دو علامت {# و #} قرار بدهید. توضیحات فقط برای راهنمایی می باشند و هیچ تاثیری در قالب یا نتیجه ی کار ندارند.


    2. محیط های برنامه نویسی

    محدودیتی در انتخاب IDE وجود ندارد و می توانید از هر IDE که با آن راحت هستید استفاده کنید؛ اما، قبل از ادامه، جهت تسهیل فرایند کد نویسی و استفاده از امکانات رنگی سازی کد و تکمیل خود کار کد، بهتر است از یک محیط با قابلیت پشتیبانی از Twig استفاده کنیم. IDE های زیر به طور native از Twig پشتیبانی می کنند:
    • PhpStorm (native as of 2.1)
    • Komodo and Komodo Edit via the Twig highlight/syntax check mode

    IDE های زیر نیز با استفاده از افزونه قابلیت پشتیبانی از Twig را دارا می باشند:


    3. متغییر ها

    برنامه ها برای دستکاری در قالب متغییرهایی را برای آن ارسال می کنند. متغییرها ممکن است دارای ویژگی ها(attribute) یا عواملی(element) باشند که شما بتوانید به آن ها دسترسی داشته باشید.ارائه تصویری یک متغییر به شدت به برنامه ای که آن را فراهم می کند بستگی دارد.

    برای دستیابی به ویژگی های یک متغییر می توان از نقطه (.) یا دستور زیرنویس ([]) استفاده کرد:

    {{ foo.bar }}
    {{ foo['bar'] }}

    همچنین، زمانی که ویژگی دارای کاراکترهای ویژه است (مانند - که به عنوان عملگر تفریق ترجمه می شود)، می توان از تابع attribute برای دسترسی به خصوصیت مورد نیاز استفاده کرد:

    {# equivalent to the non-working foo.data-foo #}
    {{ attribute(foo, 'data-foo') }}

    باید توجه داشت که براکت ها بخشی از عبارت چاپ هستند نه بخشی از متغییر. هنگامی که در برچسب ها به متغییر دسترسی دارید از براکت استفاده نکنید.


    4. متغییر های جهانی (Global Variables)

    مغییر های زیر همیشه در همه جای کد قالب قابل دسترسی هستند:

    متغیر مرجع به قالب فعلی _self
    متغییر مرجع به context فعلی اجرای برنامه _context
    متغییر مرجع به Character Set قالب _charset


    5. تعریف متغییر جدید

    شما می توانید در درون بلوک کدها به متغیر ها مقدار بدهید. مقدار دهی باعث تعریف متغییر در خوزه ی دید فعلی می شود. این کار از طریق برچسب set صورت می گیرد.

    {% set foo = 'foo' %}
    {% set foo2 = 12 %}
    {% set foo3 = [1, 2] %}
    {% set foo_4 = {'foo': 'bar'} %}

    در کد بالا ابتدا یک متغیر با نام foo از نوع رشته ای تعریف کردیم، سپس به ترتیب متغییر هایی از نوع ، عدد، آرایه و Hash Map درست شده است.

    6. فیلتر ها

    متغییر ها می توانند از طریق فیلترها دستکاری شوند؛ هر فیلتر عمل خاصی را بر روی متغییر انجام می دهد و نتیجه را باز می گرداند. فیلترها از طریق نماد pipe (|) از متغییرها جدا می شوند و می توانند آرگومان های اختیاری داشته باشند.

    {% set name = '<b>ali</b>!' %}
    Name is : {{ name|striptags|title }}

    کد بالا ابتدا از طریق فیلتر striptags تمام تگ های HTML را از رشته حذف کرده و سپس رشته را تبدیل به عنوان می کند؛ یعنی فیلتر title حرف اول نوشته را تبدیل به حرف بزرگ می کند.
    خروجی کد بالا به صورت Name is : Ali خواهد بود. دقت کنید که تگ <b> حذف شده است و متن دیگر توپر نیست!

    برخی از فیلتر ها نیاز به دریافت پارامتر هایی به عنوان آرگومان دارند؛ این پارامتر ها را داخل پرانتز می نویسیم. پارامتر های متعدد از طریق کاما از هم جدا می شوند.

    در مثال زیر با استفاده از فیلتر join یک لیست را توسط کاما به هم متصل می کنیم:

    {% set list = ['Amir','Ali','Gholi'] %}
    {{ list|join(', ') }}

    نتیجه ی کد بالا Amir, Ali, Gholi می باشد.

    برای به کار گرفتن یک فیلتر بر روی یک بخش کد باید کد را درون برچسب فیلتر بگذارید، کد زیر تمام عبارت بین دو بخش را به حروف بزرگ تبدیل می کند:

    {% filter upper %}
        This text becomes uppercase
    {% endfilter %}

    برای دسترسی به لیست فیلر های قابل استفاده اینجا کلیک کنید.


    7. توابع

    از توابع برای تولید مقادیر استفاده می کنیم. برای فراخوانی یک تابع ابتدا نام آن را نوشته و سپس از ( و ) استفاده می کنیم. اگر تابع دارای آرگومان باشد، آرگومان ها داخل پرانتز نوشته می شوند.

    به عنوان مثال در کد زیر تابع range یک آرایه شامل لیست اعداد 0 تا 3 را باز می گرداند؛ مقدار بازگشتی توسط for مورد استفاده قرار گرفته است.

    {% for i in range(0, 3) %}
        {{ i }}<br>
    {% endfor %}

    استفاده از آرگومان های اسم دار قالب شما را در مورد معنی متغییرهایی که ارسال می کنید شفاف تر می کند.

    {% for i in range(low=1, high=10, step=2) %}
        {{ i }},
    {% endfor %}

    همچنین این امکان را برای شما فراهم می کند تا آرگومان هایی را که نمی خواهید مقدرا پیش فرض آنها را عوض کنید را رد کنید:

    {{ data|convert_encoding('UTF-8', 'iso-2022-jp') }}
    
    {# versus #}
    
    {{ data|convert_encoding(from='iso-2022-jp', to='UTF-8') }}

    همان طور که در بالا می بینید تابع convert_encoding با استفاده از آرگومان های نام دار در خط دوم، با معنی تر از خط اول نوشته شده است. خوانایی کد دوم نیز بیشتر است.

    همچنین این امکان را برای شما فراهم می کند تا آرگومان هایی را که نمی خواهید مقدرا پیش فرض آنها را عوض کنید را رد کنید:

    {# the first argument is the date format, which defaults to the global date format if null is passed #}
    {{ "now"|date(null, "Europe/Paris") }}
    
    {# or skip the format value by using a named argument for the time zone #}
    {{ "now"|date(timezone="Europe/Paris") }}

    می توانید آرگومان های مکانی و اسمی را به طور همزمان در یک فراخوانی استفاده کنید. در این صورت آرگومان های مکانی باید قبل از آرگومان های اسمی بیایند:

    {{ "now"|date('d/m/Y H:i', timezone="Europe/Paris") }}

    برای دسترسی به لیست توابع قابل استفاده اینجا کلیک کنید.


    8. ساختار های کنترلی

    منظور از ساختارهای کنترلی تمام دستوراتی است که جریان داده را کنترل می کنند مانند دستورات شرطی، حلقه و بلوک ها. ساختارهای کنترلی در درون بلوک {% ... %} قرار می گیرند.

    به عنوان مثال برای نمایش لیستی از کارکنان که در متغییر users فراهم شده اند از برچسب for استفاده می شود:

    <h1>Members</h1>
    <ul>
        {% for user in users %}
            <li>{{ user.username|e }}</li>
        {% endfor %}
    </ul>

    برچسب if می تواند برای بررسی صحت یک عبارت به کار رود، به عنوان مثال در کد زیر کل بلوک فقط در صورتی نمایش داده می شود که تعداد کاربران، یعنی خصوصیت length از متغییر users، بزرگتر از صفر باشد؛ در واقع یعنی زمانی که حداقل یک کاربر در آرایه ی users وجود داشته باشد:

    {% if users.length > 0 %}
        <ul>
            {% for user in users %}
                <li>{{ user.username|e }}</li>
            {% endfor %}
        </ul>
    {% endif %}

    در دستور if می توانید از عبارات منطقی استفاده کنید. به عنوان مثال در کد زیر محتوا زمانی نمایش داده خواهد شد که متغییر color برابر red و همچنین متغییر show_box برابر مقدار منطقی true باشد:

    {% if color == "red" and show_box == true %}
            I am a red box!
    {% endif %}

    برای دسترسی به لیست برچسب های قابل استفاده اینجا کلیک کنید.


    9. توضیحات

    توضیحات فقط برای راهنمایی می باشند و هیچ تاثیری در قالب یا نتیجه ی کار ندارند، همچنین کد های درون برچسب توضیحات اجرا نخواهند شد؛ از این ویژگی می توانید برای غیر فعال کردن موقتی بخشی از کد قالب استفاده کنید. برای قرار دادن یک خط در توضیحات از دستور {# ... #} استفاده کنید. بجای ... می توانید توضیحات مورد نظر خود را بنویسید.

    {# note: disabled template because we no longer use this
        {% for user in users %}
            ...
        {% endfor %}
    #}

    10. اضافه کردن قالب های دیگر

    جهت استفاده ی مجدد از یک کد و جلو گیری از تکرار کد، می توانید بخش های مختلف قالب را به صورت فایل های جدا گانه تعریف کنید. سپس از این فایل در مکان های متعددی استفاده کنید؛ با این روش اگر نیاز به تغییر در بخش تکراری از کد باشد، دیگر نیازی به عوض کردن فایل های مختلف نیست، کافی است تغییرات را در فایل اولیه اعمال کنید.

    یک مثال خوب برای این موضوع بخش کد header در قالب ها می باشد. معمولا بخش سرتیتر قالب در همه ی صفحات یکسان است و کد آن تکرار می شود؛ لذا می توان با این روش بخش سرتیتر را به عنوان یک فایل جداگانه تعریف کرده و در صفحات مختلف آن را فراخوانی کنیم.

    از برچسب include برای اضافه کردن یک قالب و برگرداندن محتوای اعمال شده آن ها در قالب فعلی استفاده می شود:

    {% include 'header.html' %}

    نکته: آنچه را که در قالب فعلی (قالب والد) تعریف کنید، برای قالبی که اضافه کردید هم قابل مشاهده و دسترسی خواهد بود. به عنوان مثال در کد زیر در یک صفحه برای نمایش مجموعه ای از جعبه ها از یک قالب دیگر استفاده کرده ایم. قالب render_box.html می تواند به متغییر box دسترسی داشته باشد.


    11. ارث بری در قالب ها

    قدرتمندترین بخش Twig وراثت قالب آن است. وراثت قالب به شما اجازه می دهد تا یک قالب اسکلت پایه برای سایت خود درست کنید و بخش هایی را در آن تعبیه کنید که قالب های فرزند آن ها را بازنویسی کنند. این امر به نظر پیچیده می آید اما اصولا بسیار ساده است. درک این مفهوم با یک مثال بهتر است. ابتدا یک قالب پایه ای به نام base.html طراحی می کنیم که یک اسکلت ساده برای سایت دو ستونی را تعبیه می کند:

    <!DOCTYPE html>
    <html>
        <head>
            {% block head %}
                <link rel="stylesheet" href="style.css" />
                <title>{% block title %}{% endblock %} - My Webpage</title>
            {% endblock %}
        </head>
        <body>
            <div id="content">{% block content %}{% endblock %}</div>
            <div id="footer">
                {% block footer %}
                    &copy; Copyright 2011 by <a href="http://domain.invalid/">you</a>.
                {% endblock %}
            </div>
        </body>
    </html>

    در این مثال برچسب block چهار بلوک را که قالب های فرزند می توانند بازنویسی کنند را مشخص می کند. تمام کاری که این برچسب ها انجام می دهند این است که به موتور قالب بگویند که یک قالب فرزند می تواند این بخش های قالب را بازنویسی کند.

    قالب فرزند این مثال می تواند به صورت زیر تعریف شود:

    {% extends "base.html" %}
    
    {% block title %}Index{% endblock %}
    {% block head %}
        {{ parent() }}
        <style type="text/css">
            .important { color: #336699; }
        </style>
    {% endblock %}
    {% block content %}
        <h1>Index</h1>
        <p class="important">
            Welcome to my awesome homepage.
        </p>
    {% endblock %}

    برچسب extend کلید این بخش است. این برچسب برای موتور مشخص می کند که این قالب یک قالب دیگر را توسعه می دهد. زمانی که سیستم قالب این قالب را ارزیابی می کند ابتدا قالب والد را پیدا می کند. برچسب extend باید اولین برچسب این قالب باشد.

    توجه داشته باشید از آنجایی که قالب فرزند بلوک footer را دستکاری نمی کند، مقادیر موجود در قالب والد به جای آن استفاده می شوند.

    هم چنین می توان با استفاده از تابع parent بلوک های والد را اجرا کرد. مانند:

    {% block sidebar %}
        <h3>Table Of Contents</h3>
        ...
        {{ parent() }}
    {% endblock %}

    نکته: برای یاد گیری کامل کار با سیستم ارث بری Twig و مشاهده ی امکانات بیشتری مانند ارث بری پویا، ارث بری شرطی، حوزه ی دید، بلوک ها تو در تو و ... اینجا کلیک کنید.


    12. گریز HTML

    هنگام تولید کد HTML توسط قالب، همیشه این خطر وجود دارد که یک متغییر دارای کاراکترهایی باشد که کد نهایی HTML را تحت تاثیر قرار دهند. برای این مسئله دو رویکرد وجود دارد: یا اینکه هر متغییر را به صورت دستی گریز (Escape) دهیم یا تمام متغییر ها را به صورت پیش فرض گریز دهیم.

    Twig از هر دو رویکرد پشتیبانی می کند و روش خودکار به صورت پیش فرض در آن فعال است.

    کار کردن با گریز دستی

    اگر گریز دستی فعال باشد، وظیفه گریز دادن متغییر ها در صورت نیاز به گردن شما می افتد. ممکن است بپرسید که چه چیزی را گریز دهیم؟ پاسخ هر متغییری است که به آن اعتماد ندارید. عمل گریز دادن به وسیله عملگرPipe(|) از طریق فیلتر e انجام می شود:

    {{ user.username|e }}

    به صورت پیش فرض این فیلتر از استراتژی HTML استفاده می کند اما شما ممکن است بخواهید بر اساس متن گریز داده شده استراتژِی دیگری را در نظر بگیرید:

    {{ user.username|e('js') }}
    {{ user.username|e('css') }}
    {{ user.username|e('url') }}
    {{ user.username|e('html_attr') }}

    کارکردن با گریز خودکار

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

    {% autoescape %}
        Everything will be automatically escaped in this block (using the HTML strategy)
    {% endautoescape %}

    به ضورت پیش فرض گریز خودکار از استراتژی HTML پیروی می کند. در غیر این صورت شما باید صراحتا استراتژی خود را بیان کنید:

    {% autoescape 'js' %}
        Everything will be automatically escaped in this block (using the JS strategy)
    {% endautoescape %}

    گریز عبارات خاص:

    گاهی اوقات مطلوب است که Twig از بخش هایی از کد صرف نظر کند. مانند:

    {{ '{{' }}

    13. ماکرو ها

    ماکروها با توابع زبان های معمولی برنامه نویسی قابل مقایسه هستند. ماکروها برای استفاده مجدد از قطعات HTML سودمند هستند و از اینکه آن ها را تکرار کنید جلوگیری می کنند.

    ماکروها با استفاده از برچسب macro تعریف می شوند:

    {% macro input(name, value, type, size) %}
        <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
    {% endmacro %}

    ماکرو ها می توانند در هر قالبی تعریف شوند. برای استفاده از یک ماکرو متعلق به قالبی دیگر باید ابتدا با استفاده از برچسب import ماکرو را بارگزاری کنیم:

    {% import "forms.html" as forms %}
    
    <p>{{ forms.input('username') }}</p>

    به شیوه دیگرشما می توانید ماکرو های منحصری را از یک قالب با استفاده از برچسب from به فضای نام خود اضافه کنید:

    {% from 'forms.html' import input as input_field %}
    
    <dl>
        <dt>Username</dt>
        <dd>{{ input_field('username') }}</dd>
        <dt>Password</dt>
        <dd>{{ input_field('password', '', 'password') }}</dd>
    </dl>

    برای آرگومان های یک ماکرو می توان مقادیر پیش فرض را در نظر گرفت:

    {% macro input(name, value = "", type = "text", size = 20) %}
        <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}" />
    {% endmacro %}

    14. عبارت ها

    Twig اجازه استفاده از عبارت ها را در هر جایی می دهد. این روش بسیار شبیه به PHP است و حتی اگر شما با PHP کار نکرده باشید، سادگی عبارات برای شما بسیار کاربردی خواهد بود:

    {% set greeting = 'Hello ' %}
    {% set name = 'Fabien' %}
    
    {{ greeting ~ name|lower }}   {# Hello fabien #}
    
    {# use parenthesis to change precedence #}
    {{ (greeting ~ name)|lower }} {# hello fabien #}

    در مثال بالا به اولویت عملگر ها دقت کنید! اولیت عملگر ها به ترتیب از کم به زیاد به صورت زیر می باشد:

    b-and, b-xor, b-or, or, and, ==, !=, <, >, >=, <=, in, matches, starts with, ends with, .., +, -, ~, *, /, //, %, is, **, |, [], .

    نکته: هر چیزی بین دو علامت نقل قول یعنی ' یا " یک رشته حساب می شود. در صورتی که بخواهید بین دو نقل قول از یک نقل قول دیگر استفاده کنید باید بجای " از \" و بجای ' از \' استفاده کنید، مانند: 'It\'s good'

    عملگر های ریاضی:
    Twig اجازه محاسبه مقادیر را می دهد. با وجود اینکه این مسئله بسیار کم مورد استفاده قرار می گیرد اما به دلیل کاملی در آن تغبیه شده است. عملگرهای زیر پشتیبانی می شوند:

    جمع - {{ 1 + 1 }} برابر 2 می شود. +
    تفریق - {{ 3 - 2 }} برابر 1 می شود. -
    تقسیم - {{ 1 / 2 }} برابر {{ 0.5 }} می شود. /
    باقیمانده - {{ 11 % 7 }} برابر 4 می شود. %
    تقسیم صحیح - {{ 20 // 7 }} برابر 2 می شود. //
    ضرب - {{ 2 * 2 }} برابر 4 می شود. *
    توان - {{ 2 ** 3 }} برابر 8 می شود. **

    شما می توانید چندین عبارت منطقی را با استفاده از عملگرهای زیر ترکیب کنید (نکته: عملگر ها به بزرگی و کوچکی حروف حساس هستند.):

    عملگر عطف (و) منطقی and
    عملگر فصل (یا) منطقی or
    عملگر NOT منطقی (نقیض) not
    گروهی از عبارات را مشخص می کند (عبارت)

    عملگر های مقایسه ی پشتیبانی شده به صورت زیر می باشند:

    تساوی ==
    نامساوی !=
    کوچکتر <
    بزرگتر >
    بزرگتر مساوی >=
    کوچکتر مساوی <=

    در مثال زیر به ازای آیتم های فرد رنگ آبی و به ازای آیتم های زوج رنگ قرمز را نمایش می دهیم:

    {% set count = 1 %}
    {% for item in navigation %}
      {% if count % 2 == 0 %}
            <div style="color:red;"></div>
      {% else %}
            <div style="color:blue;"></div>
      {% endif %}
    {% set count = count + 1 %}
    {% endfor %}

    count در هر بار اجرای حلقه یک عدد اضافه می شود، با مقایسه ی باقیمانده ی تقسیم count بر 2 با 0 می توانیم بفهمیم آیا در تکرار زوج حلقه هستیم، یا تکرار فرد.

    همچنین می توانید بررسی کنید که آیا یک عبارت با عبارتی دیگر شروع می شود یا با عبارتی دیگر پایان می یابد:

    {% if 'Fabien' starts with 'F' %}
    {% endif %}
    
    {% if 'Fabien' ends with 'n' %}
    {% endif %}

    می توانید برای بررسی های پیچیده تر از عبارات با قاعده ی مبتنی بر PCRE استفاده کنید:

    {% if phone matches '/^[\\d\\.]+$/' %}
    {% endif %}

    عملگر دربرداشتن (contaiment):

    عملگر in تست در بر داشتن را انجام می دهد. اگر عملوند چپ در عملوند راست باشد مقدار true را باز می گرداند.

    {# returns true #}
    
    {{ 1 in [1, 2, 3] }}
    
    {{ 'cd' in 'abcde' }}

    برای انجام تست عدم وجود می توانید از عملگر not استفاده کنید:

    {% if 1 not in [1, 2, 3] %}
    
    {# is equivalent to #}
    {% if not (1 in [1, 2, 3]) %}

    عملگر تست:

    عملگر is عمل تست را انجام می دهد. از این عملگر برای تست یک متغییر در مقابل یک یک غبات معمول استفاده می شود. عملوند سمت راست نام تست است:

    {# find out if a variable is odd #}
    
    {{ name is odd }}

    در مثال بالا اگر متغییر نام، فرد باشد نتیجه ی درست بازگردانده می شود. تست ها می توانند آرگومان هم قبول کنند:

    {% if post.status is constant('Post::PUBLISHED') %}

    تست ها می توانند با عملگر is not منفی شوند:

    {% if post.status is not constant('Post::PUBLISHED') %}
    
    {# is equivalent to #}
    {% if not (post.status is constant('Post::PUBLISHED')) %}

    برای مشاهده ی لیست تمام تست های موجود اینجا کلیک کنید.


    عملگر های کاربردی:

    عملگر های زیر بسیار مفید هستند اما در هیچ یک از دسته های بالا قرار نمی گیرند:

    جهت اعمال فیلتر استفاده می شود. |
    جهت ایجاد بازه استفاده می شود؛ {{ 1..5 }} معادل {{ range(1, 5) }} می باشد. ..
    تک تک عملوند ها را به رشته تبدیل کرده و با هم الحاق می کند. مثلا اگر name برابر Ali باشد، {{ "Hello " ~ name ~ "!" }} عبارت Hello Ali! را چاپ می کند. ~
    دسترسی به ویزگی های یک شیئ - مثلا website.title عنوان وب سایت را باز می گرداند .
    یک خصوصیت از یک شیئ را باز می گرداند. مثلا
    website["title"]
    عنوان سایت را باز می گرداند.
    [attribute-name]
    نسخه ی کوتاه شده ی if می باشد.
    {{ foo ? 'yes' : 'no' }}
    یعنی اگر foo صحیح بود Yes را چاپ کن و در غیر این صورت No را چاپ کن.
    {{ foo ? 'yes' }}
    معادل
    {{ foo ? 'yes' : '' }}
    و نیز
    {{ foo ?: 'no' }}
    معادل
    {{ foo ? foo : 'no' }}
    می باشد.
    ?:

    15. الحاق رشته ها

    عملگر الحاق رشته ها ( #{expression} ) به شما اجازه می دهد که هر عبارت معتبری در درون رشته ها قرار بگیرد.

    {{ "foo #{bar} baz" }}
    {{ "foo #{1 + 2} baz" }}

    16. کنترل فضای خالی (whitespace)

    اولین خط جدید بعد از برچسب قالب به طور خودکار حذف می شود. به غیر از این فضاهای خالی توسط موتور دستکاری نمی شوند.

    از برچسب spaceless برای حذف فضاهای خالی بین برچسب های HTML استفاده کنید:

    {% spaceless %}
        <div>
            <strong>foo bar</strong>
        </div>
    {% endspaceless %}
    
    {# output will be <div><strong>foo bar</strong></div> #}

    علاوه بر این برچسب شما می توانید فضای خالی را در سطح هر برچسب کنترل کنید. از طریق دستکاری کننده فضای خالی بر روی هر برچسب شما می توانید برچسب بعدی یا قبلی را درستکاری کنید.

    {% set value = 'no spaces' %}
    {#- No leading/trailing whitespace -#}
    {%- if true -%}
        {{- value -}}
    {%- endif -%}
    
    {# output 'no spaces' #}

    مثال بالا دستکاری کننده پیش فرض را نشان می دهد. این امکان وجود دارد که حذف فضای خالی بر روی یک سمت برچسب صورت بگیرد.

    {% set value = 'no spaces' %}
    
  4. {{- value }}
  5. {# outputs '
  6. no spaces
  7. ' #}

    کد های سیستم کانی وب

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


    1. API کانی وب

    API به معنی رابط کاربردی برنامه نویسی یا Application Programming می باشد. در این جا منظور از API مجموعه ی اشیاء خاصی می باشد که توسط کانی وب برای قالب های شما تامین می شوند. این اشیاء دارای متد ها و خصوصیت هایی می باشند که با استفاده از آن ها می توانید به امکانات و اطلاعات سیستم کانی وب دسترسی داشته باشید.

    اشیاء زیر در همه ی فایل های قالب مبتنی بر Twig شما قابل دسترس می باشند:

    امکانات و قابلیت های سیستمی را فراهم می کند. System
    اطلاعات مربوط به سایت را فراهم می کند. ٌWebsite
    اطلاعات مربوط به صفحه ی فعلی را فراهم می کند که با توجه به درخواست کاربر می تواند دارای ویژگی های متفاوتی باشد. CurrentPage
    اطلاعات و مقادیر تنظیمات کلی قالب فعلی را فراهم می کند. Template
    دسترسی به افزونه های نصب شده Extentions

    به عنوان مثال:

    <!DOCTYPE html>
    <html>
        <head>
            <title>{{ CurrentPage.WindowTitle }}</title>
        </head>
        <body>
            <ul id="navigation">
            {% if System.getCurrentUser().isGuest() %}
                Hello geust!
            {% else %}
                Hello {{ System.getCurrentUser().getName() }}, <a href="{{ Website.getLogOutLink() }}">click here</a> to logout! 
            {% endif %}
            </ul>
    
            <h1>{{ CurrentPage.Title }}</h1>
            The escaped code for this page is:
            <textarea style="width:400px; height:300px;">
                    {{ CurrentPage.HTML|e }}
            </textarea> 
    
        </body>
    </html>

    2. شیئ System

    این بخش بزودی تکمیل می شود ...


    3. شیئ Website

    این بخش بزودی تکمیل می شود ...


    4. شیئ CurrentPage

    این بخش بزودی تکمیل می شود ...


    5. شیئ Template

    این بخش بزودی تکمیل می شود ...


    6. شیئ Extentions

    این بخش بزودی تکمیل می شود ...


    توسعه ی قالب

    حالا نوبت آن رسیده است که اولین قالب خود را درست کنید. در این بخش به نحوه ی شروع توسعه ی اولین قالب می پردازیم.


    1. کیت توسعه ی قالب KTDK

    KTDK مخفف عبارت Kaniweb Template Development Kit می باشد. این یک بسته ی نرم افزاری است که بر روی رایانه ی خود نصب می کنید و بوسیله ی آن برای سایت ساز کانی وب قالب طراحی می کنید. ویژگی مثبت این کیت امکان اتصال به کانی وب و تست قالب به صورت زنده می باشد. سرعت توسعه ی قالب با استفاده از KTDK افزایش چشمگیری پیدا خواهد کرد.

    برای دریافت KTDK اینجا کلیک کنید.


    2. استاندارد ها و ملزومات

    این بخش بزودی تکمیل می شود ...


    3. درج در فروشگاه کانی وب

    این بخش بزودی تکمیل می شود ...

توجه: این سند در طول زمان ممکن است تغییر کرده یا به طور جزئی بروز رسانی بشود!