View Helper Phalcon

Menulis dan memelihara markup HTML dengan cepat bisa menjadi tugas yang membosankan karena kaidah penamaan dan berbagai atribut yang harus dipertimbangkan. Phalcon menanggapi kompleksitas ini dengan menawarkan Phalcon \ Tag , yang pada gilirannya view helper phalcon akan memudahkan pekerjaan untuk menghasilkan HTML markup.

Komponen ini dapat digunakan di view plain HTML + PHP atau dalam Template Volt.

Panduan ini tidak dimaksudkan untuk menjadi dokumentasi lengkap helper yang tersedia dan argumen mereka. Silakan kunjungi halaman Phalcon\Tag dalam API untuk referensi yang lengkap.

Tipe Dokumen Konten 

Phalcon menyediakan helper Phalcon\Tag::setDoctype() untuk seting jenis dokumen konten. Seting jenis dokumen dapat mempengaruhi hasil HTML yang dihasilkan oleh helper tag lainnya. Misalnya, jika Anda menetapkan jenis dokumen XHTML, helper yang mengembalikan return atau yg akan menghasilkan output  tag HTML akan memberikan tag penutup untuk mengikuti standar XHTML yg valid.

Konstanta jenis dokumen Tersedia dalam Phalcon \ Tag namespace adalah:

Konstan Jenis Dokumen
HTML32 HTML 3.2
HTML401_STRICT HTML 4.01 Strict
HTML401_TRANSITIONAL HTML 4.01 Transitional
HTML401_FRAMESET HTML 4.01 Frameset
HTML5 HTML 5
XHTML10_STRICT XHTML 1.0 Strict
XHTML10_TRANSITIONAL XHTML 1.0 Transitional
XHTML10_FRAMESET XHTML 1.0 Frameset
XHTML11 XHTML 1.1
XHTML20 XHTML 2.0
XHTML5 XHTML 5

Menetapkan jenis dokumen.

<?php $this->tag->setDoctype(\Phalcon\Tag::HTML401_STRICT); ?>

Mendapatkan jenis dokumen.

<?= $this->tag->getDoctype() ?>
<html>
<!-- your HTML code -->
</html>

HTML berikut akan diproduksi.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
        "http://www.w3.org/TR/html4/strict.dtd">
<html>
<!-- your HTML code -->
</html>

Volt sintaks:

{{ get_doctype() }}
<html>
<!-- your HTML code -->
</html>

Membuat Formulir 

Formulir dalam aplikasi web memainkan bagian penting dalam mengambil input pengguna. Contoh berikut ini menunjukkan bagaimana menerapkan suatu formulir pencarian sederhana menggunakan view helper:

<!-- Sending the form by method POST -->
<?= $this->tag->form("products/search") ?>
    <label for="q">Search:</label>
    <?= $this->tag->textField("q") ?>
    <?= $this->tag->submitButton("Search") ?>
</form>

<!-- Specifying another method or attributes for the FORM tag -->
<?= $this->tag->form(array("products/search", "method" => "get")); ?>
    <label for="q">Search:</label>
    <?= $this->tag->textField("q"); ?>
    <?= $this->tag->submitButton("Search"); ?>
</form>

Kode terakhir ini akan menghasilkan HTML berikut:

<form action="/store/products/search/" method="get">
     <label for="q">Search:</label>
     <input type="text" id="q" value="" name="q" />
     <input type="submit" value="Search" />
</endform>

Bentuk yang sama dihasilkan dalam Volt:

<!-- Specifying another method or attributes for the FORM tag -->
{{ form("products/search", "method": "get") }}
    <label for="q">Search:</label>
    {{ text_field("q") }}
    {{ submit_button("Search") }}
</form>

Phalcon juga menyediakan pembuatan form untuk membuat bentuk-bentuk secara object-oriented.

Helpers untuk Menghasilkan Elemen Form 

Phalcon menyediakan serangkaian helper untuk menghasilkan bentuk elemen seperti kolom teks, tombol dan banyak lagi. Parameter pertama dari setiap helper selalu nama elemen yang akan dihasilkan. Bila formulir dikirimkan, nama tersebut akan diteruskan dengan data formulir. Dalam controller Anda bisa mendapatkan nilai-nilai ini dengan menggunakan nama yang sama dengan menggunakan metode getPost() dan getQuery()  pada objek request ($this->request).

<?php echo $this->tag->textField("username") ?>

<?php echo $this->tag->textArea(array(
    "comment",
    "This is the content of the text-area",
    "cols" => "6",
    "rows" => 20
)) ?>

<?php echo $this->tag->passwordField(array(
    "password",
    "size" => 30
)) ?>

<?php echo $this->tag->hiddenField(array(
    "parent_id",
    "value"=> "5"
)) ?>

Volt sintaks:

{{ text_field("username") }}

{{ text_area("comment", "This is the content", "cols": "6", "rows": 20) }}

{{ password_field("password", "size": 30) }}

{{ hidden_field("parent_id", "value": "5") }}

Membuat Select Box 

membuat kotak select sangatlah mudah, terutama jika data terkait disimpan dalam PHP berupa array asosiatif. Helper untuk elemen select adalah Phalcon\Tag::select() dan Phalcon\Tag::selectStatic(). Phalcon\Tag::select() telah secara khusus dirancang untuk bekerja dengan Phalcon \ MVC \ Model , sedangkan Phalcon\Tag::selectStatic() dapat digunakan dengan array PHP.

<?php

// Using data from a resultset
echo $this->tag->select(
    array(
        "productId",
        Products::find("type = 'vegetables'"),
        "using" => array("id", "name")
    )
);

// Using data from an array
echo $this->tag->selectStatic(
    array(
        "status",
        array(
            "A" => "Active",
            "I" => "Inactive",
        )
    )
);

HTML berikut akan dihasilkan:

<select id="productId" name="productId">
    <option value="101">Tomato</option>
    <option value="102">Lettuce</option>
    <option value="103">Beans</option>
</select>

<select id="status" name="status">
    <option value="A">Active</option>
    <option value="I">Inactive</option>
</select>

Anda dapat menambahkan pilihan “empty”  ke HTML yang dihasilkan:

<?php

// Creating a Select Tag with an empty option
echo $this->tag->select(
    array(
        "productId",
        Products::find("type = 'vegetables'"),
        "using" => array("id", "name"),
        "useEmpty" => true
    )
);
<select id="productId" name="productId">
    <option value="">Choose..</option>
    <option value="101">Tomato</option>
    <option value="102">Lettuce</option>
    <option value="103">Beans</option>
</select>
<?php

// Creating a Select Tag with an empty option with default text
echo $this->tag->select(
    array(
        'productId',
        Products::find("type = 'vegetables'"),
        'using' => array('id', "name"),
        'useEmpty' => true,
        'emptyText' => 'Please, choose one...',
        'emptyValue' => '@'
    )
);
<select id="productId" name="productId">
    <option value="@">Please, choose one..</option>
    <option value="101">Tomato</option>
    <option value="102">Lettuce</option>
    <option value="103">Beans</option>
</select>

Sintaks Volt untuk contoh di atas:

{# Creating a Select Tag with an empty option with default text #}
{{ select('productId', products, 'using': ['id', 'name'],
    'useEmpty': true, 'emptyText': 'Please, choose one...', 'emptyValue': '@') }}

Menetapkan atribut HTML 

Semua helper menerima array sebagai parameter pertama yang dapat berisi atribut HTML tambahan untuk elemen yang dihasilkan.

<?php $this->tag->textField(
    array(
        "price",
        "size"        => 20,
        "maxlength"   => 30,
        "placeholder" => "Enter a price",
    )
) ?>

atau menggunakan Volt:

{{ text_field("price", "size": 20, "maxlength": 30, "placeholder": "Enter a price") }}

HTML berikut dihasilkan:

<input type="text" name="price" id="price" size="20" maxlength="30"
    placeholder="Enter a price" />

Mengatur Nilai Helper 

Dari Controller 

Ini adalah prinsip pemrograman yang baik untuk framework MVC untuk menetapkan nilai-nilai tertentu untuk bentuk elemen dalam tampilan. Anda dapat mengatur nilai-nilai secara langsung dari controller menggunakan Phalcon\Tag::setDefault(). Helper ini mengisi default nilai (preload) untuk setiap helper yg hadir dalam tampilan. Jika ada helper dalam view yg memiliki nama yang sesuai dengan nilai preloaded, elemen tsb akan menggunakannya, kecuali nilai secara langsung diberikan pada helper dalam view.

<?php

class ProductsController extends \Phalcon\Mvc\Controller
{

    public function indexAction()
    {
        $this->tag->setDefault("color", "Blue");
    }

}

Pada view, helper selectStatic menyesuaikan dengan indeks yang disebut untuk preset nilai. Dalam hal ini “color”:

<?php

echo $this->tag->selectStatic(
    array(
        "color",
        array(
            "Yellow" => "Yellow",
            "Blue"   => "Blue",
            "Red"    => "Red"
        )
    )
);

Ini akan menghasilkan berikut pilih tag dengan nilai “Biru” yang dipilih:

<select id="color" name="color">
    <option value="Yellow">Yellow</option>
    <option value="Blue" selected="selected">Blue</option>
    <option value="Red">Red</option>
</select>

Dari Request 

Sebuah fitur khusus yg helper Phalcon \ Tag miliki adalah menjaga nilai-nilai dr form helper antar request. Dengan cara ini Anda dapat dengan mudah menampilkan pesan validasi tanpa kehilangan data yang dimasukkan.

Menentukan nilai-nilai secara langsung 

Setiap form helper mendukung parameter “value”. Dengan itu Anda dapat menentukan nilai untuk helper secara langsung. Ketika parameter ini hadir, setiap nilai preset menggunakan setDefault() atau melalui request akan diabaikan.

Mengubah Title Dokumen Secara Dinamis 

Phalcon \ Tag menawarkan helper untuk berubah secara dinamis judul dokumen dari controller. Contoh berikut menunjukkan hal itu:

<?php

class PostsController extends \Phalcon\Mvc\Controller
{

    public function initialize()
    {
        $this->tag->setTitle("Your Website");
    }

    public function indexAction()
    {
        $this->tag->prependTitle("Index of Posts - ");
    }

}
<html>
    <head>
        <?php echo $this->tag->getTitle(); ?>
    </head>
    <body>

    </body>
</html>

HTML berikut akan dihasilkan:

<html>
    <head>
        <title>Index of Posts - Your Website</title>
    </head>
      <body>

      </body>
</html>

Static Content Helpers 

Phalcon \ Tag juga menyediakan helper untuk menghasilkan tag seperti script, link atau img. Fungsi ini membantu dalam generasi cepat dan mudah dari sumber daya statis aplikasi Anda

Gambar 

<?php

// Generate <img src="/your-app/img/hello.gif">
echo $this->tag->image("img/hello.gif");

// Generate <img alt="alternative text" src="/your-app/img/hello.gif">
echo $this->tag->image(
    array(
       "img/hello.gif",
       "alt" => "alternative text"
    )
);

Volt sintaks:

{# Generate <img src="/your-app/img/hello.gif"> #}
{{ image("img/hello.gif") }}

{# Generate <img alt="alternative text" src="/your-app/img/hello.gif"> #}
{{ image("img/hello.gif", "alt": "alternative text") }}

Stylesheet 

<?php

// Generate <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Rosario" type="text/css">
echo $this->tag->stylesheetLink("http://fonts.googleapis.com/css?family=Rosario", false);

// Generate <link rel="stylesheet" href="/your-app/css/styles.css" type="text/css">
echo $this->tag->stylesheetLink("css/styles.css");

Volt sintaks:

{# Generate <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Rosario" type="text/css"> #}
{{ stylesheet_link("http://fonts.googleapis.com/css?family=Rosario", false) }}

{# Generate <link rel="stylesheet" href="/your-app/css/styles.css" type="text/css"> #}
{{ stylesheet_link("css/styles.css") }}

Javascript 

<?php

// Generate <script src="http://localhost/javascript/jquery.min.js" type="text/javascript"></script>
echo $this->tag->javascriptInclude("http://localhost/javascript/jquery.min.js", false);

// Generate <script src="/your-app/javascript/jquery.min.js" type="text/javascript"></script>
echo $this->tag->javascriptInclude("javascript/jquery.min.js");

Volt sintaks:

{# Generate <script src="http://localhost/javascript/jquery.min.js" type="text/javascript"></script> #}
{{ javascript_include("http://localhost/javascript/jquery.min.js", false) }}

{# Generate <script src="/your-app/javascript/jquery.min.js" type="text/javascript"></script> #}
{{ javascript_include("javascript/jquery.min.js") }}

Elemen HTML5 – helper HTML generik 

Phalcon menawarkan HTML helper generik yang memungkinkan generasi apapun dari elemen HTML. Terserah pengembang untuk menghasilkan nama elemen HTML yang valid untuk helper.

<?php

// Generate
// <canvas id="canvas1" width="300" class="cnvclass">
// This is my canvas
// </canvas>
echo $this->tag->tagHtml("canvas", array("id" => "canvas1", "width" => "300", "class" => "cnvclass"), false, true, true);
echo "This is my canvas";
echo $this->tag->tagHtmlClose("canvas");

Volt sintaks:

{# Generate
<canvas id="canvas1" width="300" class="cnvclass">
This is my canvas
</canvas> #}
{{ tag_html("canvas", ["id": "canvas1", width": "300", "class": "cnvclass"], false, true, true) }}
    This is my canvas
{{ tag_html_close("canvas") }}

Tag Service 

Phalcon \ Tag tersedia melalui layanan ‘tag’ , ini berarti Anda dapat mengaksesnya dari setiap bagian dari aplikasi di mana wadah layanan berada:

<?php echo $this->tag->linkTo('pages/about', 'About') ?>

Anda dapat dengan mudah menambahkan helper baru untuk komponen kustom menggantikan layanan ‘tag’ dalam wadah layanan:

<?php

class MyTags extends \Phalcon\Tag
{
    //...

    //Create a new helper
    static public function myAmazingHelper($parameters)
    {
        //...
    }

    //Override an existing method
    static public function textField($parameters)
    {
        //...
    }
}

Kemudian mengubah definisi layanan ‘tag’:

<?php

$di['tag'] = function() {
    return new MyTags();
};

Membuat helper Anda sendiri 

Anda dapat dengan mudah membuat helper Anda sendiri. Pertama, mulailah dengan membuat folder baru dalam direktori yang sama dengan direktori controller dan model (sejajar). Beri judul yang relatif sesuai terhadap apa yang Anda ciptakan. Misalnya kita di sini, kita bisa menyebutnya “customhelpers”. Selanjutnya kita akan membuat file baru berjudul  MyTags.php  dalam direktori baru ini. Pada titik ini, kita memiliki struktur yang kurang lebih: /app/customhelpers/MyTags.php. Di  file  MyTags.php, kita akan extend Phalcon \ Tag dan menerapkan helper Anda sendiri. Di bawah ini adalah contoh sederhana dari helper kustom:

<?php

class MyTags extends \Phalcon\Tag
{

    /**
     * Generates a widget to show a HTML5 audio tag
     *
     * @param array
     * @return string
     */
    static public function audioField($parameters)
    {

        // Converting parameters to array if it is not
        if (!is_array($parameters)) {
            $parameters = array($parameters);
        }

        // Determining attributes "id" and "name"
        if (!isset($parameters[0])) {
            $parameters[0] = $parameters["id"];
        }

        $id = $parameters[0];
        if (!isset($parameters["name"])) {
            $parameters["name"] = $id;
        } else {
            if (!$parameters["name"]) {
                $parameters["name"] = $id;
            }
        }

        // Determining widget value,
        // \Phalcon\Tag::setDefault() allows to set the widget value
        if (isset($parameters["value"])) {
            $value = $parameters["value"];
            unset($parameters["value"]);
        } else {
            $value = self::getValue($id);
        }

        // Generate the tag code
        $code = '<audio id="'.$id.'" value="'.$value.'" ';
        foreach ($parameters as $key => $attributeValue) {
            if (!is_integer($key)) {
                $code.= $key.'="'.$attributeValue.'" ';
            }
        }
        $code.=" />";

        return $code;
    }

}

Setelah membuat helper kostum, kita akan autoload direktori baru yang berisi kelas helper dari “index.php” yg berada di direktori publik.

<?php

try {

    $loader = new \Phalcon\Loader();
    $loader->registerDirs(array(
        '../app/controllers',
        '../app/models',
        '../app/customhelpers' // Add the new helpers folder
    ))->register();

    $di = new Phalcon\DI\FactoryDefault();

    // Assign our new tag a definition so we can call it
    $di->set('MyTags',  function()
    {
        return new MyTags();
    });

    $application = new \Phalcon\Mvc\Application($di);
    echo $application->handle()->getContent();

    } catch(\Phalcon\Exception $e) {
         echo "PhalconException: ", $e->getMessage();
    }

}

Sekarang Anda siap untuk menggunakan helper baru Anda dalam view Anda:

<body>

    <?php
    echo MyTags::audioField(array(
        'name' => 'test',
        'id' => 'audio_test',
        'src' => '/path/to/audio.mp3'
        ));
    ?>

</body>

Dalam bab berikutnya, kita akan berbicara tentang Volt. mesin template untuk PHP yg lebih cepat, di mana Anda dapat menggunakan sintaks yang lebih ramah untuk menggunakan helper yang disediakan oleh Phalcon \ Tag.

 

Terjemahan dari View Helper Phalcon
http://docs.phalconphp.com/en/latest/reference/tags.html