SharePoint 2010 以降(Online を含む)では、大量の JavaScript ファイルを読み込み、また、実行し動作しています。この大量の JavaScript ファイルは、毎回のページ ロードで全て読み込まれるわけではなく、ユーザー操作に応じて動的に(オンデマンドに)読み込むことができる仕組みが用意されています。これは「スクリプト オンデマンド(SOD)」と呼ばれており、この仕組みを利用するための JavaScript メソッドが SharePoint の JavaScript Library に実装されています。

自分でもよく動作を調べ直すことがあるので、メモ代わりに残しておきます。

読み込むスクリプト ファイルの登録

スクリプト ファイルをオンデマンドに呼び出すためには、あらかじめページ上の処理で読み込まれる可能性のあるスクリプト ファイルを登録しておく必要があります。この処理は、標準の状態の SharePoint ページでも多くが登録がされており、ソース コードを見ると下記のように記述されています。

RegisterSod("sp.js", "<FilePath>");

これは、<FilePath> のファイルを sp.js という “キー” で読み込むことができることを表しています。

SP.SOD.registerSod(key, url) Method
https://msdn.microsoft.com/en-us/library/office/ff411760(v=office.14).aspx

また、次のような記述もあります。

RegisterSodDep("sp.js", "sp.ui.dialog.js");

これは、sp.js は、sp.ui.dialog.js に依存していることを表しており、sp.js キーのスクリプト ファイルを読み込むさいには、sp.ui.dialog.js キーのスクリプト ファイルも合わせて読み込まれます。

SP.SOD.registerSodDep(key, dep) Method
https://msdn.microsoft.com/en-us/library/office/ff410388(v=office.14).aspx

スクリプト ファイルを読み込む

例えば、下記のようにスクリプト ファイルを読み込んで実行ができます。

SP.SOD.execute("myscript.js", "myFunction", arg1);

これは、myscript.js キーで読み込まれるスクリプト ファイル内に記述されている myFunction というメソッドに arg1 という引数を渡して実行するという意味です。ただ、正直なところほとんど利用したことがありません…。

SP.SOD.execute(key, functionName, args) Method
https://msdn.microsoft.com/en-us/library/office/ff407807(v=office.14).aspx

SharePoint のカスタマイズで良く使うのは、次の 2 つかと思います。次に紹介するのは、指定したスクリプト ファイルを読み込み、ファイル内の指定したメソッドを実行した後に、自身が作成したメソッドを実行するというものです。

SP.SOD.executeFunc("sp.js", "SP.ClientContext", myFunction);

上記の例では、sp.js キーのスクリプト ファイルを読み込んだ後に、SP.ClientContext メソッドが実行されます。その後に、自身が作成した myFunction メソッドが実行されます。このように記述することで SP.ClientContext を myFunction メソッドの処理で確実に利用ができるようになります。

なお、第 2 引数は null の指定が許可されていますが、null を指定した場合には動作が少し異なり、第 1 引数のスクリプト ファイルが “既に読み込み済みの場合” には、第 3 引数のメソッドは実行されないようです。

SP.SOD.executeFunc(key, functionName, fn) Method
https://msdn.microsoft.com/en-us/library/office/ff409592(v=office.14).aspx

そして最後に、こちらもよく目にする方法ですが、指定したスクリプト ファイルが読み込まれるまで、自身が作成したメソッドの実行を待機するというものです。

SP.SOD.executeOrDelayUntilScriptLoaded(myFunction, "sp.js");

上記の例では、myFunction メソッドの実行は、sp.js キーが指定されたスクリプト ファイルが読み込まれるまで待機されます(キューに入ります)。executeFunc との違いは、キーで指定されたスクリプト ファイルを別の方法や他の処理で読み込まれるまでは、myFunction メソッドは実行されないということです。さらには、キーで指定されたスクリプト ファイルが既に読み込み済みの場合は、myFunction メソッドは即時に実行されます。

ちなみに、スクリプト ファイルが読み込まれたという判定ですが、SharePoint の標準スクリプト ファイルでは最後に SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs(scriptFileName) が実行され、読み込み終了を通知するという決まりになっているようです。

SP.SOD.executeOrDelayUntilScriptLoaded(func, depScriptFileName) Method
https://msdn.microsoft.com/en-us/library/office/ff411788(v=office.14).aspx

SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs(scriptFileName) Method
https://msdn.microsoft.com/en-us/library/office/ff408340(v=office.14).aspx

さいごに

ここ最近は、SharePoint Online を利用されているユーザーさんも多く、JavaScript を利用したカスタマイズが多く見受けられます。他のサンプルを読み解く場合でも、これらのようなスクリプト ファイルの読み込み順がわかるとスムーズに理解できるかと思います。