導入 (Previous)

(Next) Contact_Vcard_Parse

View this page in	Last updated: Sun, 05 Oct 2008
English \| Dutch \| French \| German \| Hungarian \| Japanese \| Polish \| Russian \| Spanish \| Plain HTML

使用法

使用法 -- Contact_VCard_Build の使用法

説明

Contact_Vcard_Build の基本的な使用法は簡単です。ビルダオブジェクトのインスタンスを作成し、値とパラメータを追加し、その結果の vCard を読み込みます。

インスタンスの作成

Contact_Vcard_Build ("ビルダ") オブジェクトのインスタンスを作成するには、クラスファイルをインクルードして new を実行します。


<?php
    require_once 'Contact_Vcard_Build.php';
    $vcard =& new Contact_Vcard_Build();
?>

デフォルトでは、バージョン 3.0 の vCard 用のビルダオブジェクトを作成します。バージョン 2.1 の vCard を作成したい場合は、'2.1' をコンストラクタの引数で指定します。


<?php
    $vcard =& new Contact_Vcard_Build('2.1');
?>

コンポーネントの値を設定する方法

コンポーネントの値を設定する方法は二通りあります。追加したいコンポーネントに特化したメソッドを使用する方法と、汎用的な setValue() および addValue() メソッドを使用する方法です。汎用的なメソッドは、すべてのコンポーネント、繰り返し、構造化パートや値を扱うことができます。一方、コンポーネント固有のメソッドは、簡単に使用できます。

注意 FN (formatted name) および N (personal name) コンポーネントを指定する必要があります。これらは、2.1 および 3.0 の両方の vCard で必須となります。

たとえば、二つの ADR コンポーネントを vCard に追加するには、ADR 固有のメソッドを使用して


<?php
    // 最初の住所を指定します
    $vcard->addAddress($pobox0, $extend0, $street0, $city0, 
        $state0, $zip0, $country0);

    // 二番目の住所を指定します
    $vcard->addAddress($pobox1, $extend1, $street1, $city1, 
        $state1, $zip1, $country1);
?>

とするか、汎用的なメソッドを使用して以下のようにします。


<?php
    // 最初の住所 (iteration = 0) を指定します
    $vcard->addValue('ADR', 0, VCARD_ADR_POB,      $pobox0);
    $vcard->addValue('ADR', 0, VCARD_ADR_EXTEND,   $extend0);
    $vcard->addValue('ADR', 0, VCARD_ADR_STREET,   $street0);
    $vcard->addValue('ADR', 0, VCARD_ADR_LOCALITY, $city0);
    $vcard->addValue('ADR', 0, VCARD_ADR_REGION,   $state0);
    $vcard->addValue('ADR', 0, VCARD_ADR_POSTCODE, $zip0);
    $vcard->addValue('ADR', 0, VCARD_ADR_COUNTRY,  $country0);

    // 二番目の住所 (iteration = 1) を指定します
    $vcard->addValue('ADR', 1, VCARD_ADR_POB,      $pobox1);
    $vcard->addValue('ADR', 1, VCARD_ADR_EXTEND,   $extend1);
    $vcard->addValue('ADR', 1, VCARD_ADR_STREET,   $street1);
    $vcard->addValue('ADR', 1, VCARD_ADR_LOCALITY, $city1);
    $vcard->addValue('ADR', 1, VCARD_ADR_REGION,   $state1);
    $vcard->addValue('ADR', 1, VCARD_ADR_POSTCODE, $zip1);
    $vcard->addValue('ADR', 1, VCARD_ADR_COUNTRY,  $country1);
?>

Contact_Vcard_Build.php のインラインコメントで、コンポーネント固有の各メソッドの使用法をご確認ください。

パラメータの値を設定する方法

パラメータを追加する方法はひとつだけです。 addParam() メソッドを使用します。値を追加する場合と異なり、コンポーネント固有のメソッドはありません。

一般に、コンポーネントのパラメータを追加するのは、コンポーネントの値を設定し終えた直後です。なぜなら、最後に値が追加されたコンポーネントが何であるかをビルダオブジェクトが知っているからです (コンポーネント固有のパラメータ追加メソッドがない理由はこれです)。

たとえば、上のコードの ADR コンポーネントにパラメータを設定するには、次のようにします。


<?php
    // 最初の住所を追加します
    $vcard->addAddress($pobox0, $extend0, $street0, $city0, 
        $state0, $zip0, $country0);

    // 最初の住所のパラメータを追加します
    $vcard->addParam('TYPE', 'HOME');
    $vcard->addParam('TYPE', 'PREF');

    // 二番目の住所を追加します
    $vcard->addAddress($pobox1, $extend1, $street1, $city1, 
        $state1, $zip1, $country1);

    // 二番目の住所のパラメータを追加します
    $vcard->addParam('TYPE', 'WORK');
?>

このようにして、最初の住所には TYPE=HOME,PREF そして二番目の住所には TYPE=WORK というパラメータを指定します。

別の方法として、同じ addParam() メソッドに追加の引数を指定することで、パラメータを直接追加することもできます。


<?php
    // 最初の住所
    // (component = ADR, iteration = 0) にパラメータを追加します
    $vcard->addParam('TYPE', 'HOME', 'ADR', 0);
    $vcard->addParam('TYPE', 'PREF', 'ADR', 0);

    // 二番目の住所
    // (component = ADR, iteration = 1) にパラメータを追加します
    $vcard->addParam('TYPE', 'WORK', 'ADR', 1);
?>

これは、先ほどの addParam() のコードと同じことを行います。

注意バージョン 2.1 の仕様では、パラメータの種類を指定せずに値だけを指定する (つまり "TYPE=HOME" ではなく "HOME" とする) ことも許可しています。しかし Contact_Vcard_Build クラスはそれほど寛容ではありません。 Contact_Vcard_Builder を使用する場合は、パラメータの種類と値の両方を指定する必要があります。

vCard を取得する方法

値とパラメータを追加したら、vCard に戻って fetch() メソッドを使用します。これはそのコンポーネント、パラメータそして値 (BEGIN:VCARD および END:VCARD を含む) を、vCard のバージョンにあわせた適切な書式で返します。


<?php
    $text = $vcard->fetch();
?>

注意選択した vCard のバージョンにないコンポーネントの値やパラメータを指定した場合は、それは取得した vCard テキストには含まれません。

注意 FN (formatted name) および N (personal name) コンポーネントは必ず設定しなければなりません。そうしないと fetch() メソッドは PEAR_Error オブジェクトを返します。 FN および N コンポーネントは、バージョン 2.1 および 3.0 の両方の vCard で必須となります。

導入 (Previous)

(Next) Contact_Vcard_Parse

Download Documentation	Last updated: Sun, 05 Oct 2008
Do you think that something on this page is wrong? Please file a bug report or add a note.
User Notes:
There are no user contributed notes for this page.