From 5be52c0c8cb507d04a5bd17a846035597831ee0d Mon Sep 17 00:00:00 2001 From: ArnaudBuchholz Date: Thu, 19 Oct 2017 22:34:57 -0400 Subject: [PATCH] Documentation (#168) --- doc/tutorials/REQUIRE.md | 52 +++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/doc/tutorials/REQUIRE.md b/doc/tutorials/REQUIRE.md index 10a7e1f2..c5a1e0c6 100644 --- a/doc/tutorials/REQUIRE.md +++ b/doc/tutorials/REQUIRE.md @@ -1,43 +1,46 @@ -The library offers a way to organize the project by creating separate resources files and link them -using dependencies. The {@see gpf.require.define} API is the main entry point. +The library offers a way to organize any project by creating separate resources files and reference them +like dependencies. The {@see gpf.require.define} API is the main entry point. -A resource is referenced using its path. A resource may reference other resources using a relative path. -For the initial call, a base path might be defined using {@see gpf.require.configure}. -The resolved resource name correspond to the concatenation of the base path and the resource path. +A resource file is referenced using its path. A resource may reference another resource using a path that is relative +to the current one. For the initial call, a base path may be defined using {@see gpf.require.configure}. +The resource resolved path correspond to the resource absolute path. -Several type of resources files can be linked, type detection is based on the extension (case insensitive): +The library handles several type of resources files. Type detection is based on the path extension (case insensitive): - **.json** JSON static resource file - **.js** JavaScript module +- by default, any other type is handled as a text file -Once a resource file is loaded, its associated output is cached using the resolved file name. +Once a resource file is loaded, its associated output *(see below)* is cached and indexed using the resolved file path. Consequently (considering the cache is never cleared): -- If the same resource is accessed twice (using relative path but with the same resolved file name), -the file will be loaded only once +- If the same resource (i.e. the same resolved path) is accessed twice, the file will be loaded only once - Any modification applied to the output will be reflected globally ## JSON static resource file -A JSON file is loaded, parsed and the result object is associated to the resource name. - +A JSON file is loaded, parsed and the result value is the output. ## JavaScript Module -resources => module or static resources +Modules are designed to enforce best practices: +- The module scope is private, public exposure has to be +[explicit](https://carldanley.com/js-revealing-module-pattern/). This reduces the global namespace cluttering. + *(see the different supported formats below)* +- Dependencies are loaded first and then made available to the module through +[injection](https://en.wikipedia.org/wiki/Dependency_injection) -A module has several properties: -- Its scope is private, it decides what is exposed -- Dependencies are loaded first and then made available to the module +Whatever the chosen module format, the top level call must be {@see gpf.require.define}. +The factory function is optional and a promised is returned to know when the dependant resources are loaded. -Whatever the chosen module format, the very first call must be {@see gpf.require.define}. -The factory function is optional and a promised is returned to know whe nthe dependant modules are loaded. -Once the initial call is made, the API supports several formats. +The library supports several module formats. In general, the `gpf` symbol is always available. +If you need an access to the global context, use the `{@see gpf.context}` API. +### GPF Module -In general, the `gpf` symbol is always available. It allows you to access the global context through the -`{@see gpf.context}` API. -In particular, you may define a gpf module using {@see gpf.require.define}. +This module format is similar to the [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition) one but +it limits the number of parameters inside the factory function. Indeed, dependencies are explicitly named in a +dictionary and consolidated with the same name in one parameter. -### GPF Module +The module public API (i.e. resource output) is the result of the factory function. ```JavaScript gpf.require.define({ @@ -74,7 +77,7 @@ gpf.require.define({ ### Asynchronous Module Definition (AMD) -The [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition) format +The library supports the [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition) format. ```JavaScript define("amd", [ @@ -171,7 +174,8 @@ define(function () { ### CommonJS -The [CommonJS](https://en.wikipedia.org/wiki/CommonJS) format: +The library also supports the [CommonJS](https://en.wikipedia.org/wiki/CommonJS) format with one restriction. +Only static requires can be used (i.e. the require parameter **must** be a string). ```JavaScript "use strict";