You can load JavaScript before the Turnkey AngularJS client compiles by adding an AppWideAngularScriptIncludes.html file; use it when your scripts must register directives, modules, or functions before the application renders.

What this file does

In the AngularJS client of MDriven Turnkey, the contents of AppWideAngularScriptIncludes.html are inserted early in page rendering, before AngularJS compiles the page. Put <script> tags in this file to make custom JavaScript available at that point.

This is useful when a script:

• Registers an AngularJS directive used by an EXT Component.
• Adds an AngularJS module dependency needed by a custom editor.
• Defines a browser function that you later call through ClientScriptExecute.

For example, a board directive must be loaded before AngularJS encounters markup that uses that directive. See A Trello-like Board in MDriven Turnkey for that pattern.

Choose where to place the include file

You can use a global include file in EXT_Scripts, or an include file associated with an EXT Component.

Location	Use it when	Example
EXT_Scripts/AppWideAngularScriptIncludes.html	A script is shared by the application or is not owned by one component.	Load MyThings.js containing a function called from a ViewModel action.
An AppWideAngularScriptIncludes.html file in an EXT_Components component folder	A script belongs to one component and should travel with that component.	A chart component loads its own JavaScript dependency and directive-registration script.

Turnkey also loads appwideangularscriptincludes.html from each EXT_Components folder. A component-local include makes the component more self-contained, because its required script references stay with the component instead of being collected in the global EXT_Scripts include file.

Use one location for a given script reference. Do not add the same script to both a global and a component-local include file unless you intend it to load twice.

Add application-wide scripts

1. Open the Turnkey application's EXT_Scripts folder.
2. Create AppWideAngularScriptIncludes.html if it does not already exist.
3. Add one <script> element for each JavaScript file that must load before AngularJS compilation.
4. Place the referenced JavaScript files in EXT_Scripts, or use the appropriate path to their actual location.
5. Reload the application and use the browser developer tools to confirm that each script is requested and that no JavaScript errors occur before the view renders.

Example EXT_Scripts/AppWideAngularScriptIncludes.html:

<script src="/EXT_Scripts/BoardComponentScriptsThatUseDirectivesAndSuch.js"></script>
<script src="/EXT_Scripts/GanttComponentScriptsThatUseDirectivesAndSuch.js"></script>
<script src="/EXT_Scripts/MyThings.js"></script>

The order of the tags is the load order. If one script depends on another, list the dependency first.

Add scripts with an EXT Component

Use a component-local include when the script is part of a reusable EXT Component. Keep the component markup, CSS, JavaScript, and its early-load script references together in that component's folder.

For example, a component named test1 can contain its markup, stylesheet, and JavaScript directive implementation. If that component also needs a script to load before AngularJS compiles, add its script reference in that component folder's AppWideAngularScriptIncludes.html. This avoids requiring an application-wide EXT_Scripts/AppWideAngularScriptIncludes.html entry solely for test1.

The component JavaScript can register its directive against the MDriven AngularJS application module, as shown in EXT Components. Ensure that the script is loaded before markup uses the directive.

Create the file from TK Live View

If you work from TK Live View, open the AssetsTK Synk section and use Ensure EXTScripts/appwideangularscriptincludes.html. This creates the application-wide include file in the assets structure for the current running model.

Example: expose a function for a ViewModel action

To call a browser function from a ViewModel action, load the file early and define the function in that file.

1. Add this reference to EXT_Scripts/AppWideAngularScriptIncludes.html:

<script src="/EXT_Scripts/MyThings.js"></script>

1. Create EXT_Scripts/MyThings.js:

function ThisIsMyFunction(param1) {
    window.alert('This is my function alert(' + param1 + ')');
}

1. In the ViewModel action, assign vClientScriptExecute an expression such as vClientScriptExecute:='ThisIsMyFunction("hello man")'.

When the action changes vClientScriptExecute, the client calls the named function. The argument must be enclosed in double quotes for the client-side matching used by ClientScriptExecute. See ClientScriptExecute for the supported call format and further details.

File-name casing on Linux

Linux file systems are case-sensitive. The include file is accessed using lower-case characters:

appwideangularscriptincludes.html

Use the expected filename casing when deploying or copying assets to Linux. A filename that differs only by capitalization can work on a case-insensitive development machine but fail to load on Linux.

Common problems

Symptom	Check
A directive is unknown or markup renders before custom behavior is available.	Confirm that the script reference is in an AppWideAngularScriptIncludes file and that it loads before AngularJS compilation. Confirm that the directive registration code runs without an error.
The browser returns a missing-file error for a script.	Verify the src path, the file location, and filename casing. This is especially important on Linux.
A component works only when a global include file exists.	Move the component-specific script reference to the component's own AppWideAngularScriptIncludes.html so the component carries its dependency.
A script appears to run twice.	Check whether the same <script> reference exists in both the global include file and a component-local include file.

Related use cases

For a chart component that requires all chart data to be present in its ViewModel, see Using Google Charts. For TinyMCE, load the required editor and AngularJS integration scripts through an AppWideAngularScriptIncludes file, then follow TinyMCE editor for its module registration requirement.

See also

• Documentation:EXT Components
• Documentation:AngularJS Client
• Documentation:TK Live View
• Documentation:ClientScriptExecute
• Documentation:Using Google Charts
• Documentation:TinyMCE editor