repo_zf1/documentation/manual/de/module_specs/Zend_View-Helpers-HeadScript.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect3 id="zend.view.helpers.initial.headscript">
    <title>HeadScript Helfer</title>

    <para>
        Das <acronym>HTML</acronym> <emphasis>&lt;script&gt;</emphasis> Element wird verwendet um
        entweder Clientseitige Skriptelemente Inline zu ermöglichen oder um eine entfernte Ressource
        zu verlinken die Clientseitigen Skriptcode enthält. Der <classname>HeadScript</classname>
        Helfer erlaubt es beides zu Managen.
    </para>

    <para>
        Der <classname>HeadScript</classname> Helfer unterstützt die folgenden Methoden für das
        Setzen und Hinzufügen von Skripten:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <command>appendFile($src, $type = 'text/javascript', $attrs = array())</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>offsetSetFile($index, $src, $type = 'text/javascript', $attrs =
                    array())</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>prependFile($src, $type = 'text/javascript', $attrs = array())</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>setFile($src, $type = 'text/javascript', $attrs = array())</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>appendScript($script, $type = 'text/javascript', $attrs =
                    array())</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>offsetSetScript($index, $script, $type = 'text/javascript', $attrs =
                    array())</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>prependScript($script, $type = 'text/javascript', $attrs =
                    array())</command>
            </para>
        </listitem>

        <listitem>
            <para>
                <command>setScript($script, $type = 'text/javascript', $attrs = array())</command>
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Im Falle der *<methodname>File()</methodname> Methoden ist <varname>$src</varname> der
        entfernte Ort des Skriptes das geladen werden soll; das ist üblicherweise in der Form einer
        <acronym>URL</acronym> oder eines Pfades. Für die *<methodname>Script()</methodname>
        Methoden sind <varname>$script</varname> die clientseitigen Skript Direktiven die in diesem
        Element verwendet werden sollen.
    </para>

    <note>
        <title>Abhängige Kommentare setzen</title>

        <para>
            <classname>HeadScript</classname> erlaubt es ein Script Tag in abhängige Kommentare zu
            setzen, das es erlaubt es vor speziellen Browsern zu verstecken. Um abhängige Tags zu
            setzen, muß der abhängige Wert als Teil des <varname>$attrs</varname> Parameters im
            Methodenaufruf übergeben werden.
        </para>

        <example id="zend.view.helpers.initial.headscript.conditional">
            <title>Headscript mit abhängigen Kommentaren</title>

            <programlisting language="php"><![CDATA[
// Scripte hinzufügen
$this->headScript()->appendFile(
    '/js/prototype.js',
    'text/javascript',
    array('conditional' => 'lt IE 7')
);
]]></programlisting>
        </example>
    </note>

    <para>
        <classname>HeadScript</classname> erlaubt auch das Erfassen von Skripten; das kann nützlich
        sein wenn man ein Clientseitiges Skript programmtechnisch erstellen und es dann woanders
        platzieren will. Seine Verwendung wird in einem Beispiel anbei gezeigt.
    </para>

    <para>
        Letztendlich kann die <methodname>headScript()</methodname> Methode verwendet werden um
        Skript Elemente schnell hinzuzufügen; die Signatur hierfür ist <methodname>headScript($mode
            = 'FILE', $spec, $placement = 'APPEND')</methodname>. Der <varname>$mode</varname> ist
        entweder 'FILE' oder 'SCRIPT', anhängig davon ob das Skript verlinkt oder definiert wird.
        <varname>$spec</varname> ist entweder die Skriptdatei die verlinkt wird, oder der Skriptcode
        selbst. <varname>$placement</varname> sollte entweder 'APPEND', 'PREPEND' oder 'SET' sein.
    </para>

    <para>
        <classname>HeadScript</classname> überschreibt <methodname>append()</methodname>,
        <methodname>offsetSet()</methodname>, <methodname>prepend()</methodname>, und
        <methodname>set()</methodname> um um die Verwendung der speziellen Methoden wie vorher
        gezeigt zu erzwingen. Intern wird jedes Element als <property>stdClass</property> Token
        gespeichert, welches später mit Hilfe der <methodname>itemToString()</methodname> Methode
        serialisiert wird. Das erlaubt es Prüfungen an den Elementen im Stack vorzunehmen, und diese
        Elemente optional zu ändern, einfach durch das Modifizieren des zurückgegebenen Objektes.
    </para>

    <para>
        Der <classname>HeadScript</classname> Helfer ist eine konkrete Implementation des
        <link linkend="zend.view.helpers.initial.placeholder">Platzhalter Helfers</link>.
    </para>

    <note>
        <title>InlineScript für HTML Body Skripte verwenden</title>

        <para>
            <classname>HeadScript</classname>'s Schwester Helfer,
            <link linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>, sollte
            verwendet werden wenn man Inline Skripte im <acronym>HTML</acronym>
            <emphasis>body</emphasis> inkludieren will. Die Platzierung von Skripten am Ende des
            Dokuments ist eine gängige Praxis für die schnellere Auslieferung von Seiten, speziell
            wenn 3rd Party Analyse Skripte verwendet werden.
        </para>
    </note>

    <note>
        <title>Andere Attribute werden stanadrdmäßig ausgeschaltet</title>

        <para>
            Standardmäßig wird <classname>HeadScript</classname> nur
            <emphasis>&lt;script&gt;</emphasis> Attribute darstellen die von W3C abgesegnet sind.
            Diese beinhalten 'type', 'charset', 'defer', 'language', und 'src'. Trotzdem, verwenden
            einige Javascript Frameworks, vorallem <ulink
                url="http://www.dojotoolkit.org/">Dojo</ulink>, eigene Attribute um Verhalten
            zu ändern. Um solche Attribute zu erlauben, können diese über die
            <methodname>setAllowArbitraryAttributes()</methodname> Methode eingeschaltet werden:
        </para>

        <programlisting language="php"><![CDATA[
$this->headScript()->setAllowArbitraryAttributes(true);
]]></programlisting>
    </note>

    <example id="zend.view.helpers.initial.headscript.basicusage">
        <title>Grundsätzliche Verwendung des HeadScript Helfers</title>

        <para>
            Neue Skript Tags können jederzeit spezifiziert werden. Wie vorher beschrieben können
            diese Links auf externe Ressourcen Dateien oder Skripte sein.
        </para>

        <programlisting language="php"><![CDATA[
// Skripte hinzufügen
$this->headScript()->appendFile('/js/prototype.js')
                   ->appendScript($onloadScript);
]]></programlisting>

        <para>
            Die Reihenfolge ist oft wichtig beim Clientseitigen Skripting; es kann notwendig sein
            sicherzustellen das Bibliotheken in einer speziellen Reihenfolge geladen werden da Sie
            Abhängigkeiten zueinander haben; die verschiedenen append, prepend und offsetSet
            Direktiven können hierbei helfen:
        </para>

        <programlisting language="php"><![CDATA[
// Skripte in eine Reihenfolge bringen

// An einem bestimmten Offset Platzieren um Sicherzustellen
// das es als letztes geladen wird
$this->headScript()->offsetSetFile(100, '/js/myfuncs.js');

// Scriptige Effekte verwenden (append verwendet den nächsten Index, 101)
$this->headScript()->appendFile('/js/scriptaculous.js');

// Aber Basis Prototype Skripte müssen immer als erstes geladen werden
$this->headScript()->prependFile('/js/prototype.js');
]]></programlisting>

        <para>
            Wenn man letztendlich damit fertig ist am alle Skripte im Layoutskript darzustellen, muß
            der Helfer einfach ausgegeben werden:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->headScript() ?>
]]></programlisting>
    </example>

    <example id="zend.view.helpers.initial.headscript.capture">
        <title>Skripte einfachen mit Hilfe des HeadScript Helfers</title>

        <para>
            Manchmal mit ein Clientseitiges Skript programmtechnisch erstellt werden. Wärend man
            Strings zusammenhängen, Heredocs und ähnliches verwenden könnte, ist es oft einfacher
            nur das Skript zu erstellen und in <acronym>PHP</acronym> Tags einzubetten.
            <classname>HeadScript</classname> lässt das zu, und erfasst es in den Stack:
        </para>

        <programlisting language="php"><![CDATA[
<?php $this->headScript()->captureStart() ?>
var action = '<?php echo $this->baseUrl ?>';
$('foo_form').action = action;
<?php $this->headScript()->captureEnd() ?>
]]></programlisting>

        <para>
            Die folgenden Annahmen werden gemacht:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Das Skript wird an den Stack angefügt. Wenn es den Stack ersetzen soll oder an
                    den Anfang hinzugefügt werden soll, muß 'SET' oder 'PREPEND' als erstes Argument
                    an <methodname>captureStart()</methodname> übergeben werden.
                </para>
            </listitem>

            <listitem>
                <para>
                    Der <acronym>MIME</acronym> Typ des Skripts wird mit 'text/javascript'
                    angenommen; wenn ein anderer Typ spezifiziert werden soll muß dieser als zweites
                    Argument an <methodname>captureStart()</methodname> übergeben werden.
                </para>
            </listitem>

            <listitem>
                <para>
                    Wenn irgendwelche zusätzlichen Attribute für das
                    <emphasis>&lt;script&gt;</emphasis> Tag spezifiziert werden sollen, müssen diese
                    in einem Array als drittes Argument an <methodname>captureStart()</methodname>
                    übergeben werden.
                </para>
            </listitem>
        </itemizedlist>
    </example>
</sect3>