AJAXリクエストの使用方法

CS-Cart における AJAX の基礎

CS-Cart では、jQueryのAjaxメソッドに独自の拡張を行っています。コードは、js/tygh/ajax.jsファイルに記載されています。こちらを呼び出すには以下の手順で行います。

  • submitForm(フォームのみ) ：フォーム内のデータを抽出し、送信できるように準備します。
  • request：それぞれのコントローラーにAJAXリクエストを送信します (dispatchから解析されます)。jQueryのAjaxメソッドを使用します。
  • response：リクエストが正常に実行されると呼び出されます。実際のサーバの応答を処理し、結果を表示します。
  • inProgress：AJAX リクエストが進行中かどうかを判断します。
  • clearCache：レスポンスのキャッシュをクリアします。

サーバ上での AJAXリクエストの処理中に、AJAXリクエストのサブシステムの初期化がfn_init_ajax( app/functions/fn.init.php )機能によって実行されます。

  • AJAXクラス ( app/Tygh/Ajax.php )のオブジェクトが作成されます。
  • AJAXリクエストの前後に必要な変換を実行します。
  • さらにresponseに変換するためのJSON配列も生成します。

AJAX_REQUEST定数は、PHP コードで使用するためにtrueに設定されています。

PHPファイルでAJAX_REQUEST定数を使用すると、AJAXリクエスト時にのみ実行する必要があるコードを指定できます。

例：

if (defined('AJAX_REQUEST')) { fn_set_notification('E', fn_get_lang_var('warning'), $msg, true, 'insecure_password'); }

AJAXリクエスト スクリプトの実行が完了したとき、または終了関数exit()が明示的に呼び出されたときに、AJAXクラス ( app/Tygh/Ajax.php ) のデストラクタが実行されます。デストラクタは、ドキュメントに表示すべき情報を JSON配列に渡し、その配列をresponseJS 関数 ( /js/tygh/ajax.js ) に渡します。

コントローラーは次の形式で応答を返します。

data:
    notifications:
        id:
            text
            title
        id:
            text
            title
        ...
    html:
        block_id:
            block_content
        block_id:
            block_content
        ...

マイクロフォーマットでAJAXを呼び出す

AJAXリクエストはリンクとフォームによって送信できます。どちらの場合も、cm-ajaxそれぞれの要素にマイクロフォーマットを割り当てる必要があります。

フォーム

フォームにcm-ajaxというクラスがある場合、そのコンテンツはアクション属性で定義されたURLにAJAXリクエストとして送信されます。

このようなフォームには、 result_idsという名前の非表示の入力要素があります。この要素には、AJAXデータで更新される要素の識別子が含まれている必要があります。

以下は AJAX を利用したフォームの例です。

<!-- Form with the class cm-ajax; defines that AJAX requests should be sent to index.php -->
<form class="cm-ajax" action="index.php" method="post" name="product_form_817">

<!-- Hidden input field with the identifiers of the HTML elements to be updated -->
    <input type="hidden" name="result_ids" value="my_id" />
    ...

<!-- When this submit button is clicked, an AJAX request will be sent to index.php -->
     <input id="button_cart_817" type="submit" name="dispatch[checkout.add..817]" value="Add to cart" />
    ...
</form>

リンク

cm-ajaxのクラスを持つリンクは、クリックされると、hrefで指定されたURLにAJAXリクエストを送信します。

更新する要素のIDは、data-ca-target-id属性に指定する必要があります。

AJAX を利用したリンクの例

<a class="cm-ajax" data-ca-target-id="cart_items,checkout_totals,cart_status*,checkout_steps,checkout_cart" href="{""|fn_url}"><i class="icon-cancel-circle"></i></a>

追加のマイクロフォーマット

cm-ajaxのAJAXフォームとリンクにはマイクロフォーマットが必須です。ただし、CS-Cartでは開発者がAJAXをより細かく制御できるようにするオプションのマイクロフォーマットが多数あります。

AJAXリクエストを直接使用する

CS-Cartのコーディング・ガイドラインでは、明示的なメソッド呼び出しは推奨されていません。すべての JavaScript 関数は別々のファイルに配置し、CSSセレクター (id、class など) を使用してHTML要素に割り当てる必要があります。

それでも、$.ceAjax()メソッドの直接インライン呼び出しを介して AJAXリクエストを送信できます。

<input id="enable_block_1" type="checkbox" name="enable_block_1" value="Y" onclick="$.ceAjax(‘request’, '{$index_script}?dispatch=block_manager.enable_disable&amp;block_id=1&amp;enable=' + (this.checked ? this.value : 'N'), {literal}{method: 'POST', cache: false}{/literal});" />

AJAX経由でコンテナを再読み込みする

CS-Cartでは以下のように、コンテナのコンテンツを動的にリロードできます。

  • cm-ajaxクラスとresult_ids要素を含むフォームを送信します(マイクロフォーマットに関する記事を参照してください)。
  • cm-ajaxクラスとdata-ca-target-id属性を持つリンクを使用します(マイクロフォーマットに関する記事を参照してください)。
  • $.ceAjax()からカスタムリクエストを行ってください。

コンテナは適切にフォーマットされている必要があります。

  • idは開始タグの最後の属性である必要があります。
  • idは閉じタグの前に「マジックコメント」を置く必要があります。

例：

<div class="foo" data-ca-bar="bar" id="foobar">
    This content will be reloaded by AJAX
<!--foobar--></div>