ユーザー設定フィールド データ入力規則
最終更新日: 2010年3月13日
適用対象: SharePoint Foundation 2010
ユーザー設定フィールド クラスには、データの入力規則を含めることができます。各ユーザー設定フィールド型では、親フィールド クラスから入力規則を継承することも、親の入力規則をオーバーライドすることもできます。また、独自の入力規則ロジックの一部として親の入力規則を呼び出すこともできます。ユーザー設定フィールド クラスのユーザー設定のデータ入力規則と更新前の処理ロジックは、GetValidatedString メソッドのオーバーライドで指定します (既定の実装では、値クラスの ToString メソッドを呼び出すだけです。このため、フィールド クラスが SPField、または GetValidatedString メソッドをオーバーライドしていない派生クラスから直接継承している場合は、必要に応じて、GetValidatedString をオーバーライドして入力規則ロジックを提供する必要があります)。
データ入力規則の適用
データ入力規則は、フォーム コントロールなど、コード内の複数の場所で適用できますが、サーバー側で必要なすべてのデータ入力規則ロジックをユーザー設定フィールド クラスの GetValidatedString メソッドに追加することを強くお勧めします。これにより、フィールド内のデータとコンテンツ データベース内のデータの両方に、必要なデータ入力規則を確実に適用できます。
データを更新する場合、次のような方法があります。
フォーム コントロールを使用する。
ユーザー インターフェイスを使用する。
オブジェクト モデルを使用してプログラムによって更新する。
上記のいずれかの方法でデータが更新された場合、SharePoint Foundation は、SPField または派生クラスにデータが格納されるたびに GetValidatedString メソッドを呼び出します。たとえば、SPListItem.this["field name"] メソッドを使用して SPListItem オブジェクトのフィールド値が設定されると、SharePoint Foundation は GetValidatedString メソッドを呼び出します。
注意
ユーザーは、GetValidatedString メソッドを呼び出さない方法 (つまり、このメソッドに含まれるデータ入力規則ロジックを呼び出さない方法) でフィールドのデータを更新できます。該当する方法として、SPListItem オブジェクトを呼び出さずにフィールド データを更新する、アンマネージ コードまたは Web サービス メソッドを使用することが挙げられます。たとえば、ユーザーがデータシート ビューを使用してリスト アイテム データを更新するときには、GetValidatedString メソッドを呼び出さずにリスト アイテムが更新されます。
さらに、GetValidatedString メソッドを使用すると、文字列に関するエラー メッセージを呼び出し元のアプリケーションまたはフォームに返すことができます。これにより、ユーザー設定フィールド クラスのデータ入力規則エラーの表示および処理を正常に行えます。
エラー メッセージを返すには、GetValidatedString メソッドがエラーとして SPFieldValidationException をスローする必要があります。適切なエラー メッセージを文字列パラメーターとして SPFieldValidationException コンストラクターに渡すことができます。SharePoint Foundation では、ユーザーがフォームで無効な値を入力し、[OK] をクリックすると、(リスト アイテムの) 標準の新規作成フォームと編集フォームの該当のフィールドの横に、赤色のテキストでメッセージが表示されます。
次の例は、GetValidatedString のオーバーライド バージョンを示しています。このオーバーライドでは、必須フィールドに値が含まれていること、および値の文字列バージョンが指定された制限を超えていないことを確認します (Required プロパティは、フィールドが必須かどうかを示します)。
public override String GetValidatedString(Object value)
{
if ((this.Required == true) && (value.ToString() == ""))
{
throw new SPFieldValidationException(this.Title
+ " must have a value.");
}
else if (value.ToString().Length > MAXLENGTH)
{
throw new SPFieldValidationException(this.Title
+ " cannot be longer than " + MAXLENGTH.ToString());
}
return base.GetValidatedString(value);
}
Public Overrides Function GetValidatedString(ByVal value As Object) As String
If (Me.Required = True) AndAlso (value.ToString() = "") Then
Throw New SPFieldValidationException(Me.Title & " must have a value.")
ElseIf value.ToString().Length > MAXLENGTH Then
Throw New SPFieldValidationException(Me.Title & " cannot be longer than " & MAXLENGTH.ToString())
End If
Return MyBase.GetValidatedString(value)
End Function
ユーザー インターフェイスの入力規則
(リスト アイテムの) 標準の新規作成フォームまたは編集フォーム以外の UI でユーザーがフィールドの値を設定できる場合、フィールドの UI コントロールにユーザーが入力するデータにも入力規則を適用する必要があります。特に、フィールドに値を含めることが必須である場合は、この要件を UI レベルで適用することをお勧めします。BaseFieldControl から派生した SharePoint Foundation の組み込みクラスの 1 つを使用してフィールドをレンダリングする場合は、Required の適用を内部の入力規則に依存できます。BaseFieldControl またはその派生クラスの 1 つから独自のコントロールを派生し、Validate メソッドまたは CreateChildControls メソッドをオーバーライドする場合は、Required と共に、必要な他の UI レベルの入力規則を適用する必要があります。
UI の入力規則ロジックは、Validate メソッド、CreateChildControls メソッド、またはこの 2 つの組み合わせに配置できます。入力規則ロジックを CreateChildControls メソッドに配置する場合の欠点の 1 つは、このメソッドが呼び出されるのはフィールドがフォームにレンダリングされるときだけなので、オブジェクト モデルで値を更新したときは入力規則が適用されないという点です。
Validate メソッドのオーバーライドでは、IsValid プロパティを true に設定するか、またはこのプロパティを false に設定したうえで、ErrorMessage を適切なメッセージに設定して、結果を報告する必要があります。
次の例は、Validate メソッドのオーバーライドを示しています。このオーバーライドでは、まず、コントロールの現在のモードが表示モードかどうかを確認します。表示モードの場合はフィールドを変更できないため、フィールドが無効であってもかまいません。このメソッドでは、IsValid プロパティをチェックして、Value プロパティが既に無効であることが判明しているかどうかも確認します。どちらかの確認で true が返されると、何の操作も行われません。どちらの確認でも true が返されず、Value プロパティにも問題が検出されない場合、このメソッドは IsValid を false に設定する基本 Validate を呼び出し、適切な ErrorMessage を設定します。(BaseFieldControl.Validate メソッドは何も実行しません。したがって、Validate メソッドがオーバーライドされるクラスが BaseFieldControl から直接派生する場合は、基本の Validate メソッドの呼び出しは省略できます。) 最後に、このメソッドは Required の値をチェックし、その値を適用します。
public override void Validate()
{
if (ControlMode == SPControlMode.Display || !IsValid)
{
return;
}
base.Validate();
if (Field.Required &&
(Value == null || Value.ToString().Length == 0))
{
this.ErrorMessage = Field.Title + " must have a value."
IsValid = false;
return;
}
}
Public Overrides Sub Validate()
If ControlMode = SPControlMode.Display OrElse (Not IsValid) Then
Return
End If
MyBase.Validate()
If Field.Required AndAlso (Value Is Nothing OrElse Value.ToString().Length = 0) Then
Me.ErrorMessage = Field.Title & " must have a value."
IsValid = False
Return
End If
End Sub
注意
ErrorMessage をレンダリングするには、RenderValidationMessage メソッドを使用します。