Permalink
Browse files

[BUG #6230] more introductory text for the components

- also add dedicated page for 'create-application.py'
  • Loading branch information...
1 parent c14242f commit 0bb5316189d03e17d9d571ee0545b6e93ad39587 @thron7 thron7 committed Mar 26, 2012
@@ -1,6 +1,9 @@
Desktop
***********
+qooxdoo Desktop is the component to build rich and interactive, desktop-like applications. Its prominent feature is the comprehensive set of GUI widgets and controls, like buttons, sliders, tabviews, trees and tables. Layout managers organize the elements on the screen. Unified keyboard and mouse events provide cross-browser event handling. A dedicated theming system allows the application of styles to the graphical elements independent of the behavioral aspects. Text element like labels can be internationalized. qooxdoo Desktop requires that you use the :doc:`qooxdoo SDK </pages/tool>` with its tool chain. See Overview for a more in-depth introduction.
+
+
.. _index#documents:
.. toctree::
@@ -3,19 +3,6 @@
Overview
********
-.. _pages/ui_overview#server:
-
-Server
-======
-
-Developing a qooxdoo application does not require a server. Its static application contents (initial html file, JavaScript files, images, etc.) may just be loaded from your local file system.
-
-Of course, for the actual deployment of your final app you would use a web server to deliver the (static) contents. For developing a qooxdoo app it is not a prerequisite to setup a web server, so you can start right away on your local computer.
-
-Any practical qooxdoo client application will communicate with a server, for instance to retrieve and store certain application data, to do credit card validation and so on. qooxdoo includes an advanced :doc:`RPC mechanism </pages/communication/rpc>` for direct calls to server-side methods. It allows you to write true client/server applications without having to worry about the communication details. qooxdoo offers such *optional* `RPC backends <http://qooxdoo.org/contrib/project#backend>`_ for Java, PHP, Perl and Python. If you are missing your favorite backend language, you can even create your own RPC server by following a generic :doc:`server writer guide </pages/communication/rpc_server_writer_guide>`.
-
-If you already have an existing backend that serves HTTP (or HTTPS) requests and you do not want to use those optional RPC implementations, that's fine. It should be easy to integrate your qooxdoo app with your existing backend using traditional AJAX calls.
-
.. _pages/ui_overview#widgets:
Widgets
@@ -73,3 +60,16 @@ There are different applications which could be used as a starting point for a c
* `Inline <http://demo.qooxdoo.org/%{version}/apiviewer/#qx.application.Inline>`__: Uses the ``Page`` root to build traditional web page based application which are embedded into isles in the classic HTML page.
* `Native <http://demo.qooxdoo.org/%{version}/apiviewer/#qx.application.Native>`_: This class is for applications that do not involve qooxdoo's GUI toolkit. Typically they make only use of the IO ("Ajax") and BOM functionality (e.g. to manipulate the existing DOM).
+.. _pages/ui_overview#communication:
+
+Communication
+=============
+
+Developing a qooxdoo application does not require a server. Its static application contents (initial html file, JavaScript files, images, etc.) may just be loaded from your local file system.
+
+Of course, for the actual deployment of your final app you would use a web server to deliver the (static) contents. For developing a qooxdoo app it is not a prerequisite to setup a web server, so you can start right away on your local computer.
+
+Any practical qooxdoo client application will communicate with a server, for instance to retrieve and store certain application data, to do credit card validation and so on. qooxdoo includes an advanced :doc:`RPC mechanism </pages/communication/rpc>` for direct calls to server-side methods. It allows you to write true client/server applications without having to worry about the communication details. qooxdoo offers such *optional* `RPC backends <http://qooxdoo.org/contrib/project#backend>`_ for Java, PHP, Perl and Python. If you are missing your favorite backend language, you can even create your own RPC server by following a generic :doc:`server writer guide </pages/communication/rpc_server_writer_guide>`.
+
+If you already have an existing backend that serves HTTP (or HTTPS) requests and you do not want to use those optional RPC implementations, that's fine. It should be easy to integrate your qooxdoo app with your existing backend using traditional AJAX calls.
+
@@ -1,6 +1,6 @@
.. _pages/frame_apps_testrunner#the_qooxdoo_test_runner:
-The qooxdoo Test Runner
+Test Runner
***********************
"Test Runner" is a `unit testing <http://en.wikipedia.org/wiki/Unit_test>`_ framework that fully supports testing qooxdoo classes. It is similar to but does not require JSUnit or any other JavaScript unit testing framework. If you look at the component section of a qooxdoo distribution under ``component/testrunner/``, you will find the Test Runner sources, together with a mockup test class. In the ``framework/`` section you can create a Test Runner instance with all test classes from the qooxdoo framework by running:
@@ -1,10 +1,10 @@
.. _pages/tool#tooling:
Tooling
-=======
+*********
Introduction
-------------
+=============
.. toctree::
:maxdepth: 1
@@ -17,7 +17,7 @@ Introduction
tool/code_structure
Generator
-----------
+=============
.. toctree::
:maxdepth: 1
@@ -28,33 +28,49 @@ Generator
tool/generator_optimizations
tool/generator_config_articles
tool/generator_config_background
+
+Tutorials
+------------
+
+.. toctree::
+ :maxdepth: 1
+
+ tool/tutorial_basics
+
.. tool/generator_config_howto
.. :download:`Generator Cheat Sheet (PDF) <pages/tool/generator_cheat_sheet_1.0.0-1.pdf>`
+References
+------------
+* :doc:`tool/generator_default_jobs`
+* :doc:`tool/generator_config_ref`
+* :doc:`tool/generator_config_macros`
-Further Tools
--------------
+Lint
+=============
.. toctree::
:maxdepth: 1
- Source code validation ("lint") <tool/source_code_validation>
+ Source code validation <tool/source_code_validation>
-Tutorials
-----------
+Application Wizard
+===================
.. toctree::
:maxdepth: 1
- tool/tutorial_basics
+ tool/create_application
-References
---------------------
+Other Tools
+====================
-* :doc:`tool/generator_default_jobs`
-* :doc:`tool/generator_config_ref`
-* :doc:`tool/generator_config_macros`
+Some of the tools that come with the SDK are described elsewhere in this manual. Here are some pointers:
+* :doc:`application/apiviewer`
+* :doc:`development/frame_apps_testrunner`
+* :doc:`development/simulator`
+* :doc:`application/featureconfigeditor`
@@ -0,0 +1,67 @@
+
+.. _pages/tool/create_application#create_application:
+
+Create Application
+******************
+
+There is a command-line tool from the *tool/bin* directory named ``create-application.py`` that helps you start a new application or library. It basically creates a folder structure with some essential files filled in. This basic setup already comprises a minimal working application which you can build and run, with no changes. But of course the intention is that you then go ahead and change the files' contents, particularly the %{JS} source files, add new classes, and evolve this skeleton into your desired application.
+
+The same file structure is suitable to hold a library, i.e. a set of classes that you want to reuse in several applications. You can even have libraries that only hold images or other static resources, like CSS files.
+
+You start it at the command prompt. The minimal set of options you have to provide is an output folder name (*-n*), and optionally an application type (*-t*). Other options let you select an output directory, a different application namespace, or a log file.
+
+Here is a simple example:
+
+.. code-block:: bash
+
+ $ create-application.py -n foo -t native
+
+Several tutorials in this manual make use of *create-application.py*, e.g. the :doc:`helloworld` tutorial. There is also a dedicated page that describes the :doc:`various application types </pages/development/skeletons>`.
+
+For the most current information about the options please refer to the interactive help you get with ``create-application.py --help``. Here is a sample capture:
+
+.. code-block:: none
+
+ $ create-application.py --help
+ Usage: create-application.py --name APPLICATIONNAME [--out DIRECTORY]
+ [--namespace NAMESPACE] [--type TYPE]
+ [-logfile LOGFILE] [--skeleton-path PATH]
+
+ Script to create a new qooxdoo application.
+
+ Example: For creating a regular GUI application 'myapp' you could execute:
+ create-application.py --name myapp
+
+ Options:
+ -h, --help show this help message and exit
+ -n APPLICATIONNAME, --name=APPLICATIONNAME
+ Name of the application. An application folder with
+ identical name will be created. (Required)
+ -o DIRECTORY, --out=DIRECTORY
+ Output directory for the application folder. (Default:
+ .)
+ -s NAMESPACE, --namespace=NAMESPACE
+ Applications's top-level namespace. (Default:
+ APPLICATIONNAME)
+ -t TYPE, --type=TYPE Type of the application to create, one of: ['basic',
+ 'bom', 'contribution', 'gui', 'inline', 'mobile',
+ 'native'].'basic' -- for non-browser run times like
+ Rhino, node.js; 'bom' -- can be used to build low-
+ level qooxdoo applications; 'contribution' -- is
+ suitable for qooxdoo-contrib ; 'gui' -- is a standard
+ qooxdoo GUI application; 'inline' -- is an inline
+ qooxdoo GUI application; 'mobile' -- is a qooxdoo
+ mobile application with full OO support and mobile GUI
+ classes; 'native' -- is a qooxdoo application with
+ full OO support but no GUI classes. (Default: gui)
+ -l LOGFILE, --logfile=LOGFILE
+ Log file
+ -p PATH, --skeleton-path=PATH
+ (Advanced) Path where the script looks for skeletons.
+ The directory must contain sub directories named by
+ the application types. (Default:
+ /home/thron7/workspace/qooxdoo.git/component/skeleton)
+ --cache=PATH Path to the cache directory; will be entered into
+ config.json's CACHE macro (Default:
+ ${TMPDIR}/qx${QOOXDOO_VERSION}/cache)
+
@@ -1,6 +1,10 @@
Website
*******************
+You use qooxdoo Website to build light-weight, integrated, low-level components for web sites or other browser-like environments where you don't want to add graphical elements with qooxdoo. It features a DOM selector engine (Sizzle), BOM and HTML abstraction layers, and a cross-browser keyboard and mouse events. As it does not contain visual elements, it is independent of image resources and theming. Its code can be shrink-wrapped into a single %{JS} file, and is available as an individual download. You can include it like any other %{JS} library in your projects.
+
+This section provides tutorials and introductory material. For your daily work with qooxdoo Website the only other thing you need is the `API reference <http://api.qooxdoo.org/%{version}/>`_.
+
General
=======
@@ -32,7 +32,7 @@ Communication
Pulling data from remote sources is also one of the most common use cases and usually the next logical step when it comes to improving your existing JavaScript powered website / application. However, you expect that the underlying framework is providing you a nice abstracted cross-browser solution you can easily use. qooxdoo offers you multiple implementations to pull data.
-The first option is to use `XHR <http://en.wikipedia.org/wiki/XHR>`__. This browser API is widely used and qooxdoo comes with :ref:`a wrapper of this API <pages/communication#website_requests>` which hides away inconsistencies and works around bugs. However, to gain more comfort the recommended way is to use the :doc:`Higher-level requests </pages/communication/request_io>`.
+The first option is to use `XHR <http://en.wikipedia.org/wiki/XHR>`__. This browser API is widely used and qooxdoo comes with :ref:`a wrapper of this API <pages/communication#low_level_requests>` which hides away inconsistencies and works around bugs. However, to gain more comfort the recommended way is to use the :doc:`Higher-level requests </pages/communication/request_io>`.
The second option is to use `JSONP <http://en.wikipedia.org/wiki/JSONP>`__. With that approach you can overcome the `same orgin policy <http://en.wikipedia.org/wiki/Same_origin_policy>`__ and can talk to any server which is offering a JSON API like e.g `Twitter <https://dev.twitter.com/>`__ does. qooxdoo is offering a :doc:`nice and powerful API </pages/communication/request_io>` with the same interface as the XHR transport to let you easily adapt any JSONP API out there.
@@ -78,4 +78,4 @@ You can create this application using the ``create-application.py`` script:
path_to_SDK/tool/bin/create-application.py -n myLowLevelApp -t native
-The result is a new low-level application skeleton named ``myLowLevelApp`` in the current folder. Dive into the :ref:`Getting started <pages/getting_started/helloworld#helloworld>` tutorial for further infos about creating your application.
+The result is a new low-level application skeleton named ``myLowLevelApp`` in the current folder. Dive into the :ref:`Getting started <pages/getting_started/helloworld#helloworld>` tutorial for further infos about creating your application.

0 comments on commit 0bb5316

Please sign in to comment.