Framework



#@title@#


	1. Before reading this readme, it should be autogenerated.
	   To refresh engine for documentation, do cd and run finalize_package.sh:

			cd .../play/deployer
			$ ./finalize_package.sh 
			read this readme by landing on doc/app_developer_readme.htm 

	2. Download: git clone git@github.com:lancelab/Boardspirator.git
	   or download as zip file.

	3. Land browser on .../play/index_prod.htm or .../play/index_dev.htm
	   Perhaps only FireFox will allow to do this.
	   For "strict browsers" put folder play under locally runnig web server like Apache and run as
	   http://localhost..../play/index...
	   


O v e r v i e w

	This package is strictly JavaScript. Its working site is whirlio.com.
	Its twin database project, boardspirator.com, is yet in alpha stage.

	It is "extreme" JavaScript because:
		whith some minor exceptions
			no CSS files are used,
			no CSS id's are used,
			no HTML markup used,
			no canvases are used,
			no image files used in controls.
			it is HTML 4.01,
			it does not need web-serverk and and server-back-end language like PHP,
			all is generated by JS, ( even triangles on scroll buttons. ),
			it uses jQuery for events, tiles, positioning, and ajax.

		The bulk of the package is vanilla JS.
		Most of the data downloaded as configuration files json or jwon.

		Game, Album objects inheritance moved outside of JS and exposed to users who are able to
		extend them via submitted text files by creating new games.

	Entire package is written using "closure-style functional" object instantiation inspired by Douglas Crockford.
	You will never see there operator "new" like in "new Game()".
	You will never see there word "prototype" like in "MyConstructor.prototype = never".
	This is not because we "dislike" "prototype" or "new", but for style consistency.

	Since version 1.201 above style changes, some canvases added, probably some key HTML fragments like login or ads
	will be written as in-line HTML.

#@full_description_table@#





S o f t w a r e   O v e r v i e w


	#@title@# is a part of tp-package.
	#@title@# is jQuery subplugin: jQuery.fn.tp$.gio with little use of window.tp$ functions.
	So, tp's readme and coding conventions  are applicable to #@title@#.
	There are only three global variables window.jQuery, window.$, window.tp$.
	In development version, there is also a shortcut to console.log: window.cccc.


	In contrary to tp, #@title@#
	   ... uses images, which are used only in game boards,
	   ... uses css-ids in ads in some web pages.


	Here are #@title@# source code files:
		application: local: ../core and web: project_files.htm#did_core,
		tp: local: ../tp and web: project_files.htm#did_tp


	Usage readme is here: guest_readme.htm.
	Application Design Concepts is here: app_design_concepts.htm



	Play folder tree:
		core         - core source code
		def          - definitiions: games, albums, skins, ...
		tp           - generic JS libraries
		prod         - production script. Compiled from development part.
		deployer     - Ruby script which deploys application from dev. version to production.
		google_apps  - have nothing to do with application. Ignored if disabled in configuration.



	
	H o w    t o   r u n   o r    t o    d e b u g 

	  Adding ...&debug parameter to URL-query enables debug mode:
	  index_dev.htm?debug.




	M a i n t e n a n c e

		Keep browser detection code updated in tp.$core.



	C o d i n g   c o n v e n t i o n s

		Attempt made to hold following convensions:

			1. No css class attribute ever used except one case,
		 	   class="dontload_external" in derive.js

			2. No css id attribute ever used except for debug when id = "...._debug" and
			   for optional debug console which has id.

		
	

A p p l i c a t i o n    A r c h i t e c t u r e .   D r a f t

	Finally functioned at run-time album object is like:

		album
			game
			dresses
			collections
					collection
						maps
							map
								board
								rounds
									round
										playpaths
								dresses
									merged dresses from parent album and from map-script

		Front page captions reflect this tree.
		When user toggles captions from from game to game, then album-collection-map-round
		user-gameplay-state is preserved in background.

		There are 3 lists of albums.
		The master list is: gio.session.stemmed_albums. It contains all loaded albums.
		The albums listed in GUI: session.alist and session.alist_by_key. They have the same content, index is different.


	Execution steps are: 
		Load
			phase 1
			document-header-time-startup
						scripts inserted into index.htm are executed
						they prepare
								main methods,
								game definition hierachy,
								event handlers,
								call google analytics
							
			phase 2 -
			window.onload-time-startup
						executes on window.onload event,
							gio.session.init.entry();
								finalizes base definitions: gdef.procs.spawn_base_game_and_dress();
								other tasks: game def. load, albums load, ...
								...
								picks up default game or and loads its default collection from data sources,
								if all collections are failed, default map is displayed
								ggi.control_events();
								ggi.step_events();

		Play
			phase 3
			execution - user plays, creates maps, runs solver
			user-time-initializations
						user selects different collection or game and its data loads
						user creates maps


		Map's script validated in two places.
			First, in play/def/map_format modules - syntax validation.
			Second, in normalize_map() function - logical validation.
			Maps state is kept in map.load. States are:
				map.load	= 'parsed' - passed syntax validation
							= 'invalid'
							= 'finalized' - passed both validations and supplied
											borad, rounds, and all necessary properties for run-time. 

		If even single map in collection is failed validation, then all collection is invalid.
		Valid collection has property collection.maps_loaded ='success'.





D i a r y

	is a collection of step by step versions.
	They are stand-alone snapshots of application at specific time.


	1. It is good to have backup versions when current version is
	   overengineered and one can fork from earlier ...
	2. Diary is a storage of abandoned ideas. Not every good idea can find its way to a final.

	For example, version 49 does not use css and images for dynamic "beautified" select box
	control. Can be a base for future browsers, with good CSS3 support.

	For example, in version 34, /var/www/bgame/gio/diary/34/games/sokoban/config.js
	has clear layout for tiles_map. This is a basic internal format for map
	which is used at least till verions 53, but it is not documented and abandoned later.




Thank you for your interest to Bs.

When JS finds this token, #@title@# , then JS will make this div visible.