$$.BasicScript.jsxlib

/*******************************************************************************

		Name:           BasicScript
		Desc:           Facade of a simple Yalt/Settings/Dialog script.
		Path:           /etc/$$.BasicScript.jsxlib
		Require:        Yalt, Settings, Dom.Dialog (forcibly included.)
		Encoding:       ÛȚF8
		Core:           NO
		Kind:           Module.
		API:            =run() init() changeLocaleTo()
		                onEngine() onLoad() onUnload()
		                Context() UserInterface() Server()
		DOM-access:     ---
		Todo:           ---
		Created:        180307 (YYMMDD)
		Modified:       240131 (YYMMDD)

*******************************************************************************/

#include '$$.Yalt.jsxlib'
#include '$$.Settings.jsxlib'
#include '$$.Dom.Dialog.jsxlib'

;if( $$.ModalScript ){ alert(__("%1 cannot work with the %2 module.",'BasicScript','ModalScript')); exit(); }
;$$.hasOwnProperty('BasicScript') || eval(__(MODULE, $$, 'BasicScript', 240131, 'run'))

	//==========================================================================
	// NOTICE
	//==========================================================================

	/*

	The present module offers a full template system for creating InDesign scripts.
	It integrates the localization engine (Yalt), the settings manager (Settings),
	and the Dom.Dialog so your UI is easily declared and ready to run.
	
	BasicScript is a 'facade' in that it hides many IdExtenso intricacies and just
	shows you the essential bricks to get your script working fast, safely, and
	with all $$ features still available if need be (log, JSON, etc.)


	THE 'CONTEXT/UI/SERVER' PARADIGM

	BasicScript implements a Context/UI/Server paradigm. It fits well a
	wide variety of scripts, under the following requirements:

	(a) The program primarily needs to check a Context,
	    which highly determines what can/may be done.

	    In DOM terms this refers to any condition on the current selection,
	    existence or status of the active document, constraints on some object,
	    layer, spread, layout, style name(s), preference, units, coordinates.
	    Anything that is now visible, or selected, from the user perspective.
	    Any data, parameter, or condition that can be found in the environment.
	    
	REM As an abstraction the Context is responsible for extracting, reading,
	    parsing data. It isn't intended to create things or perform 'actual'
	    tasks altering the DOM (unless it can restore the initial state.)
	
	(b) Before processing, the program opens a simple dialog (UI),
	    from which the user validates options and tasks, or cancel.

	    The dialog has to be *simple* in the sense it only handle native
	    DOM widgets (checkboxes, dropdowns, edit fields, radio options...)
	    and does not require additional interactions, nor dynamic update.
	    Basically, it gathers both contextual data and user preferences
	    for this particular program. The UI makes the Context and the User
	    meet in order to define a process.
	
	(c) Once properly defined and requested, the process can be 'served'
	    as a consistent, airtight, set of tasks.

	    The process must be 'strongly decoupled' from the previous stages.
	    Ideally, it just has to take as input the current settings (incl.
	    some contextual data) and run. It is the heavy component, the one
	    that acts (layout processing, font/style report, preflight, XML,
	    graphic adjustments, text cleaning, etc.)


	ABSTRACT COMPONENTS
	
	BasicScript handles and interacts with three child modules: Context,
	UserInterface, and Server. They are built and loaded as abstract
	components, that is, formal placeholders ready to receive specific
	features.
	
	The constant part of each abstract component is coded in its
	respective `jsxlib` file (`etc/BasicScript/<Component>.jsxlib`).
	You don't want to change any code there. Instead, you will extend
	each module from your own project (as we shall see) by defining
	callback functions, also called 'hooks', which the system invokes
	when needed. If a certain hook is missing, then the default
	scenario goes on to the next step.
	
	For example, the Context module supports a `beforeActivate` hook.
	If you define it, it is automatically called before settings
	activation so you can provide a specific DOM host for those
	settings that require to wake up from DOM data.
	
	
	COMPONENT      PURPOSE AND SUPPORTED HOOKS
	------------------------------------------------------------------
	Context        Manage settings (activate, backup) and contexual data.
	               Hooks: beforeActivate, onActive, beforeBackup, onQuit.
	------------------------------------------------------------------
	UserInterface  Run and close the UI dialog (if available).
	               Hooks: beforeShow, onClose.
	------------------------------------------------------------------
	Server         Full container of the 'hot' process.
	               Hook:  run.
	------------------------------------------------------------------
	
	
	BasicScript exposes a public `run` function that performs the
	following steps:
	
	1. Load IdExtenso now ($$.load).
	2. Get the Context active (in particular, activate the settings.)
	3. If all is fine, call the UserInterface (show/close steps).
	4. If all is fine, call the Server (run step).
	5. Quit the Context (in particular, save the settings if needed.)


	BOILERPLATE

	Below is a template that shows how your final program (the main JSX)
	will look like:

	----------------------------------------------------------

	      // Use "main" to discard session-persistence.
	      #targetengine "MyGreatScript"

	      #include 'path/to/idextenso/$$.jsxinc'
	      #include 'path/to/idextenso/etc/$$.BasicScript.jsxlib'
	      // #include. . . (additional $$ modules you may need)

	      ;if( $$.isBooting() )
	      {
	         $$.BasicScript.init
	         (
	         <yourSettings>,
	         <yourYaltPackage>,
	         <yourXmlUI>
	         )
	        ;
	         // Your specific Context API.
	         // ---
	         ($.global.µ=$$.BasicScript['Context'])
	         #include '<yourContext>.jsxinc'
	        ;
	         // Your specific UserInterface API.
	         // ---
	         ($.global.µ=$$.BasicScript['UserInterface'])
	         #include '<yourUI>.jsxinc'
	        ;
	         // Your specific Server API.
	         // ---
	         ($.global.µ=$$.BasicScript['Server'])
	         #include '<yourServer>.jsxinc'
	      }

	      $$.BasicScript();

	----------------------------------------------------------

	Use `$$.BasicScript.init(...)` to load (once for all) the fixed
	data, or 'resources,' of your program:
	
	      <yourSettings>, if supplied, is the Object that
	      declares all settings key/value pairs.
	      -> See $$.Settings for further detail.
	      
	      <yourYaltPackage>, if supplied, is a String that
	      encodes all L10N strings used in your project,
	      formatted as a Yalt package.
	      -> See $$.Yalt for further detail.

	      <yourXmlUI>, if supplied, is the XML object that
	      describes your dialog, as specified in Dom.Dialog.
	      -> See $$.Dom.Dialog for further detail.

	[REM]  Each of these three optional arguments can be loaded
	       through a local `#include ...` directive, which
	       helps keep your 'resource' distinct from the program.

	Finally, you provide the local implementation of each abstract
	component (if used) in your own `jsxinc` files:
	
	      . . .
	      #include '<yourContext>.jsxinc'
	      . . .
	      #include '<yourUI>.jsxinc'
	      . . .
	      #include '<yourServer>.jsxinc'


	[REM] The lines of the form `($.global.µ=$$.BasicScript[...])`
	      in the template may look obscure. Keep them as written!
	      They just allow to inject your `jsxinc` files in the
	      corresponding module space while preserving the general
	      syntax and conventions used in the framework.
	
	Now, what is left to you? Only implementing the desired 'hooks'
	(see above) in the respective `jsxinc` files. For example,
	<yourContext>.jsxinc may look like:

	----------------------------------------------------------
	
	      [PRIVATE]
	      ({

	          MY_FUNC: function()
	          // ----------------------
	          // For some reason you need a private method...
	          {
	              $$.trace("Just to say HELLO to the log!"):
	          },
	          
	          // etc

	      })
	
	      [PUBLIC]
	      ({

	          onActive: function onActive_O_(ss)
	          // ----------------------
	          // This is the `onActive` hook. Great news is,
	          // it provides the active settings as 1st arg.
	          {
	              $$.success(__("Script name is %1",ss.$NAME));
	          },
	          
	          // etc

	      })
	
	----------------------------------------------------------
	
	Note that the code has the form we already see anywhere else
	in IdExtenso modules. You will use the [PRIVATE] and [PUBLIC]
	clusters to separate inner members from public API. You can use
	`.setup(...)` on incoming functions, and so on. Strictly
	speaking, your own `jsxinc` code becomes a *part* of the
	respective modules, it is injected at including time in either
	Context.jsxlib, UserInterface.jsxlib, or Server.jsxlib.

	In fact, when your program is very simple in terms of settings
	and UI, all you have to do is to create the `<yourServer>.jsxinc`
	snippet and implement the `run` hook!

	*/

	//==========================================================================
	// MAIN MODULE
	//==========================================================================

	#include 'AnyScript/$$.initialize.jsxinc'

	#include 'BasicScript/$$.dialog.jsxinc'
	#include 'BasicScript/$$.public.jsxinc'

	#include 'AnyScript/$$.run.jsxinc'

	//==========================================================================
	// SUBMODULES
	//==========================================================================

;$$.BasicScript.hasOwnProperty('Context') || eval(__(MODULE, $$.BasicScript.toSource(), 'Context', 210405))
	#include 'AnyScript/$$.context.jsxinc'

	#include 'BasicScript/$$.UserInterface.jsxlib'

;$$.BasicScript.hasOwnProperty('Server') || eval(__(MODULE, $$.BasicScript.toSource(), 'Server', 210405))
	#include 'AnyScript/$$.server.jsxinc'

	//==========================================================================
	// [ADD220816] ALIASES --> $$.Context ; $$.UserInterface ; $$.Server
	//==========================================================================

;if( $$.isBooting() )
{
	$.global.µ = $$.BasicScript;
	$$.setup({ Context:µ.Context, UserInterface:µ.UserInterface, Server:µ.Server });
}