DIR : /home/kozerus/public_html/pn/uize/site-source/guides/getting-started.simple

/home/kozerus/public_html/pn/uize/site-source/guides

Introduction
	This document takes you step by step through the process of setting up a Web project to use the UIZE JavaScript Framework. "Hello, world" awaits you.

Download UIZE
	If you haven't already downloaded the zip archive of the UIZE Web site, [[../download.html][DOWNLOAD IT NOW]].

	Then come back to this page and continue on with the rest of the instructions.

Unzip the Archive
	Locate the archive file that you downloaded (probably on your desktop) and unzip it (probably by double-clicking on it).

	Extract the contents of the archive to a folder on your desktop, or any other desired location. You'll end up with a =UIZE-JavaScript-Framework-master= folder that contains a local copy of the UIZE JavaScript source code along with the source code for the =uize.com= Web site.

Run the UIZE Dev Server
	If you have NodeJS installed on your machine, then you can easily run the UIZE dev server (if you don't have NodeJS installed yet, [[http://nodejs.org/][go ahead]] - it's easy).

	Go into a Bash window, change your current / working directory to the =UIZE-JavaScript-Framework= folder, and then execute the command...

	.............................................
	node build.js Uize.Build.WebServer isDev=true
	.............................................

	In your terminal window, you should immediately get the confirmation message *"Server running at http://127.0.0.1:1337/"*. Now you should be able to go to that URL in your Web browser and view the *uize.com* Web site running in from your local machine.

	The cool thing about the UIZE dev server is that it has a build-on-demand process that will result in built files being automatically rebuilt upon request when they become invalid because some source file they're derived from has been updated. That means that you can hack around with the source code of examples and JavaScript modules, reload the page, and all the neceesary bits get rebuilt for your automatically. This is a great way to hack and learn, especially when it comes to fiddling with the widget source files like the *.js.jst* HTML template files and the *.csst* CSS template files.

Build the Web Site
	The UIZE [[../download.html][download]] contains only the source code for the framework, so the site needs to be built so you can browse working pages and hack the examples.

	The Web site can be built very easily, either using Windows Script Host in Windows, or using NodeJS on any operating system.

	Mac OS & Linux
		On Mac OS or Linux, the Web site can be built by running the build script in NodeJS.

		First make sure that you have NodeJS installed on your system. Once you do, go into a Bash window, change your current / working directory to the =UIZE-JavaScript-Framework= folder, and then execute the command...

		............................
		node build.js Uize.Build.All
		............................

	Windows
		On Windows, the Web site can be built by running the build script in either WSH (Windows Script Host) or NodeJS.

		- *WSH* - To run the build using WSH (Windows Script Host), which is built into Windows, simple double click on the =WSH-Uize.Build.All.bat= batch file that is at the root of the =UIZE-JavaScript-Framework= folder.
		- *NodeJS* - To run the build using NodeJS on Windows, just follow the steps for building the site on `Mac OS & Linux`.

	The Full Build Takes a While
		The full build of the *uize.com* Web site may take a couple of minutes (you may want to step away for a moment and brew a cup of coffee).

		There's lots of stuff to build and your terminal window will be subjected to a torrent of log output - don't worry, it can handle it.

	The Built Web Site
		Once you've built the Web site, there will be a =site-built= folder under the =UIZE-JavaScript-Framework= folder.

		The =site-built= folder will contain the entire built Web site for the UIZE JavaScript Framework - the very same Web site that is available online at *uize.com*. To view the Web site locally without a Web server, you can simply drag the =index.html= file into your Web browser of choice.

Create Your UIZE Project
	.

### Copy the JavaScript Files
	What If I Already Have a "js" Folder?
		If you already have a folder named "js" and don't wish to interfere with its contents, you can choose to copy the =UIZE-JavaScript-Framework= folder's "js" folder to your Web site project under a different name, like "uize_js" or whatever makes the most sense for you.

		NOTE
		This folder doesn't have to be the folder where *ALL* the JavaScript files for your site live, but it must be the folder where all JavaScript *modules* built around the UIZE JavaScript Framework live - so the various =Uize.*= modules, and any UIZE-powered modules that you write specifically for your site.

### Get the Test Page Running
	Now that you've copied over the necessary JavaScript files, you're ready to get the special test page running in your own Web site project.

	Copy the Page
		The test page is named =HELLO-WORLD.html= and is located at the root of the =UIZE-JavaScript-Framework= folder.

		Copy this file over to the root of your own Web site project's main folder.

	Modify the Script Tag, If Necessary
		If you didn't copy the UIZE JavaScript modules as the folder "js" in the root folder of your project, but instead named it something else or located it somewhere else in your project's folder structure, then you should edit the script tag that sources in the =Uize.js= file (in your version of the =HELLO-WORLD.html= file, of course) so that it points to the correct location.

		EDIT THIS LINE, IF NECESSARY
		........................................................
		<script type="text/javascript src="js/Uize.js"></script>
		........................................................

		*NOTE:* The =script= tag is located inside the =head= of the test page.

	Test the Page
		When you're happy that your version of the =HELLO-WORLD.html= file is pulling in the JavaScript from the correct location, load the page in your Web browser and confirm that it works.

		When the page loads in, the text *"HELLO,WORLD!"* should fade in, and then an effect should animate the color and size of the letters from left to right. If this works, for you, then you've successfully set up the UIZE JavaScript Framework. Congratulations! That wasn't too hard.

		NOTES
		- If your test page doesn't animate as it should, check that your path to the =Uize.js= file is correct.
		- To see how the page should behave, you can [[http://www.uize.com/HELLO-WORLD.html][view the original HELLO-WORLD.html]].
		- If you're using Internet Explorer, you may need to select the option to *"Allow Blocked Content..."* from the security warning bar that might appear at the top of the browser window.

### Start Hacking
	The many example pages, documentation pages, guides, and other pages of this Web site all use the UIZE JavaScript Framework to some degree or another - some of them only minimally, and others quite extensively.

	By far the most heavily UIZE'd pages are the example pages, while the documentation pages typically just wire up a tree widget for their contents list. The example pages are fair game for hacking, since they show off features that may be compelling for your own projects and provide working examples of the use of various features and widgets.

	Hacking the Examples
		To hack the example pages, you can either hack them inside the =UIZE-JavaScript-Framework/examples= folder, or you can copy the files over to your own Web site project.

		Hacking In Situ
			Hacking the example pages inside the =UIZE-JavaScript-Framework/examples= folder is easy and convenient.

			If you just want to experiment in order to gain an understanding of how things work, or play around with the settings for some widget, then hacking the example pages inside the =UIZE-JavaScript-Framework/examples= folder will be easier, since the pages are already set up to utilize assets and CSS from the UIZE Web site project.

		Hacking Copies
			If you want to use an example page as a starting point for a page in your own Web site project, then you can copy the example over and start hacking.

			In this case, you'll need to follow the few steps below...

			Modify the Script Tag
				In your copy of the example page, make sure that the =Uize.js= file is being sourced in correctly, taking into account both the location of the copied JavaScript files and the location of the example file in your site's folder structure.

				EDIT THIS LINE
				...........................................................
				<script type="text/javascript src="../js/Uize.js"></script>
				...........................................................

			Kill the .library File Reference
				The example pages in the =UIZE-JavaScript-Framework/examples= folder use a JavaScript library file called =UizeSite.Page.Example.library=.

				This is a library file that is specific to the UIZE Web site, and that bundles a bunch of the commonly required JavaScript modules into a single file to reduce HTTP requests and improve page load performance. Eventually, you can make these library files for your own Web site, but for the time being it is not necessary to use the UIZE Web site's version. The example pages will still function correctly without this optimization.

				To remove the reference, just do a text search for "UizeSite.Page.Example.library" and then remove the entire entry in the =required= block, including the quotes and comma, as shown in the example below...

				INSTEAD OF...
				..............................................................
				... ... ...
				required:[
					'UizeSite.Page.Example.library',  // <-- DELETE THIS LINE
					'UizeSite.Page.Example',
					...,
					...,
					...
				],
				... ... ...
				..............................................................

				USE...
				.............................
				... ... ...
				required:[
					'UizeSite.Page.Example',
					...,
					...,
					...
				],
				... ... ...
				.............................

			Use the Plain Vanilla Page Widget
				The example pages in the =UIZE-JavaScript-Framework/examples= folder use the page widget class =UizeSite.Page.Example=.

				This page widget class is a subclass of the plain vanilla page widget class =Uize.Widget.Page=, and is specific to the UIZE Web site. To change this, just do a text search for "UizeSite.Page.Example" and replace it with "Uize.Widget.Page". To illustrate how the required block will change, consider the following example...

				INSTEAD OF...
				......................................................
				... ... ...
				required:[
					'UizeSite.Page.Example',  // <-- CHANGE THIS LINE
					...,
					...,
					...
				],
				... ... ...
				......................................................

				USE...
				...........................
				... ... ...
				required:[
					'Uize.Widget.Page',
					...,
					...,
					...
				],
				... ... ...
				...........................

			Remove Constructor Argument
				When switching to using the plain vanilla page widget class, you should remove the constructor argument, if there is one.

				Some example pages have the constructor argument ={evaluator:function (code) {eval (code)}}=. The =evaluator= property is specific to the =UizeSite.Page.Example= class and doesn't exist in the =Uize.Widget.Page= class. You don't need this and you should remove it from the parentheses.

				Consider the following example...

				INSTEAD OF...
				......................................................................
				var page = window.page =
					UizeSite.Page.Example ({evaluator:function (code) {eval (code)}})
				;
				......................................................................

				USE...
				.............................................
				var page = window.page = Uize.Widget.Page ();
				.............................................

			CSS, Assets, JavaScript
				Realize that the example pages use CSS and assets contained inside the =UIZE-JavaScript-Framework= folder.

				You'll either have to copy those over, or otherwise massage your copies of the example pages so that they use your own CSS and assets. Also, some example pages use JavaScript code that is specific to the UIZE Web site, such as compiled JavaScript templates used for generating HTML for widgets, or JavaScript files that define test data to drive some of the examples.

### Setting Up the Build Scripts
	The UIZE JavaScript Framework provides a number of convenient build scripts that will ease tasks like scrunching (aka compressing or minifying) JavaScript files.

	These build scripts can be run using Windows Script Host on a Windows machine, or using NodeJS on MacOS, Linux, as well as Windows machines. If you choose to go the NodeJS route, you will need to install NodeJS on your system (if you don't already have it installed).

	Setting up the build scripts is quite easy...

	+. copy the "build.js" file, the "uize-config.json" file, and all the batch files with the prefix "WSH-" (if you plan to use Windows Script Host) to the root folder of your Web site
	+. then, crack open your version of the =uize-config.json= file and edit the values of the various config options to suit your application

	Most likely you'll be interested in the =Uize.Build.Files.JsModules= build script. If you're using Windows Script Host, you can double-click on the =WSH-Uize.Build.Files.JsModules.bat= batch file to run this build script. For NodeJS, you can enter the comman =node build.js Uize.Build.Files.JsModules=. After executing the build script, a long file should be created inside the "logs" folder. For a more in-depth discussion of the various build scripts and tips on different configuration settings, consult the guide [[javascript-build-scripts.html][JavaScript Build Scripts]].

### Removing Unnecessary JavaScript Files
	There are some JavaScript files that you can remove from your "js" folder, if you wish to tidy things up a bit.

	In an earlier step you copied the =UIZE-JavaScript-Framework= folder's "js" folder to your Web site project. Now, because this folder is used by the UIZE Web site, it contains a number of JavaScript modules that are specific to the UIZE Web site. You don't need these modules for your own Web site project, since they are not part of the framework, per se. These modules are the ones under the =UizeSite= namespace. You can delete all the JavaScript files prefixed with "UizeSite" (e.g. =UizeSite.Page.js=) from the "js" folder that you copied over, and from the "~source" folder inside the "js" folder. You don't need the source or the scrunched versions of these files.

	A PACKAGE DEAL

	Beyond the obviously unnecessary =UizeSite= files, there are likely to be a bunch of framework JavaScript files that you won't end up using, but it might be more bother than it's worth trying to whittle down the contents of the "js" folder any further, and you might remove some files that you end up wanting later on, or you might accidentally remove some files that you don't think you'll need but actually will. If server space is a major concern, you can try to handpick just what you need, but that won't be fun.

Getting Support
	To get support, you can join the official [[http://groups.google.com/group/uize][UIZE JavaScript Framework Group]].

	Join the Online Users' Group
		You may want to consider joining the UIZE JavaScript Framework Group, so you can ask other developers questions as you start using the UIZE JavaScript Framework.

		The official [[http://groups.google.com/group/uize][UIZE JavaScript Framework Group]] is the place where developers can discuss ways that they're using UIZE in their own projects. Join up so you can get support, give support, learn tips and tricks, show off your cool projects built on UIZE, and generally get involved in the discussion on all things UIZE. [[http://groups.google.com/group/uize][JOIN NOW]]

	And for additional support tips, consult the [[../support.html][SUPPORT]] page.

What Next?
	Now that you have successfully installed the UIZE JavaScript Framework and set up a Web site project to use it, you will want to learn more about the many feature areas of the framework and how you might use different parts of its large feature set in your own projects.

	To get an overview of the functionality of the UIZE JavaScript Framework, consult the guide [[overview-of-features.html][Overview of Features]].
	### Or, if you're ready to start building your own UIZE-powered Web pages, consult the guide [[building-uize-powered-pages.html][Building UIZE Powered Pages]].