diff --git a/doc/source/apps/system.rst b/doc/source/apps/system.rst new file mode 100644 index 0000000..5fee5ce --- /dev/null +++ b/doc/source/apps/system.rst @@ -0,0 +1,3 @@ +system application +=============================================================================== + diff --git a/doc/source/ref/i18n.rst b/doc/source/ref/i18n.rst index 75c0bb1..581cf0a 100644 --- a/doc/source/ref/i18n.rst +++ b/doc/source/ref/i18n.rst @@ -23,6 +23,8 @@ Localization .. warning:: Not implemented yet. +.. _i18n-m10n: + Multilingualization ------------------------------------------------------------------------------- diff --git a/doc/source/tutorial/helper.rst b/doc/source/tutorial/helper.rst new file mode 100644 index 0000000..e19321d --- /dev/null +++ b/doc/source/tutorial/helper.rst @@ -0,0 +1,2 @@ +Helper function development +=============================================================================== diff --git a/doc/source/tutorial/index.rst b/doc/source/tutorial/index.rst index a888422..3241486 100644 --- a/doc/source/tutorial/index.rst +++ b/doc/source/tutorial/index.rst @@ -7,7 +7,8 @@ This capter shows you how to develop your application running on sunrise step by :maxdepth: 2 introduction - helloworld + view + controller db_access design_doc helper diff --git a/doc/source/tutorial/introduction.rst b/doc/source/tutorial/introduction.rst index 491fd3d..209b0c0 100644 --- a/doc/source/tutorial/introduction.rst +++ b/doc/source/tutorial/introduction.rst @@ -41,7 +41,6 @@ Then your site directory is as follows. :: - $ tree -L 1 . ├── _attachments ├── app.js @@ -62,10 +61,12 @@ To make a applicatin, use ``sunrise:create`` command with ``-a`` option, that ge $ sunrise\:create -a apps/myapp /Users/yssk22/tmp/sunrise-site/apps/myapp has been created successfully +Now we call ``myapp`` directory as ``APP_ROOT``. + Install the template application +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -And you need to install your ``myapp`` in your site. To do this, modify ``init`` function in ``{SITE_ROOT}/app.js`` (NOT ``{SITE_ROOT}/apps/myapp/app.js``), adding ``site.install('myapp', '/myapp/')``. +And you need to install your ``myapp`` in your site. To do this, modify ``init`` function in ``{SITE_ROOT}/app.js`` (NOT ``{APP_ROOT}/app.js``), adding ``site.install('myapp', '/myapp/')``. .. code-block:: javascript @@ -79,7 +80,7 @@ And you need to install your ``myapp`` in your site. To do this, modify ``init`` } -``site.install('app', '/approot/', options)`` is a function that install a sunrise application in to the site. On installing the application, ``init`` function in ``{SITE_ROOT}/apps/myapp/app.js`` is also invoked by sunrise. +``site.install('app', '/approot/', options)`` is a function that install a sunrise application in to the site. On installing the application, ``init`` function in ``{APP_ROOT}/app.js`` is also invoked by sunrise. In the default template, @@ -101,9 +102,10 @@ Launch the site to confirm the template application Then launch your site, visit go to http://localhost:8888/, you can see the link to myapp in the menu bar. And you can visit the application root URL, http://localhost:8888/myapp/. -``init`` function in your ``{SITE_ROOT}/apps/myapp/app.js`` is a entry point for your application. You can add some paths for your web services, booting scripts for setup your database, ... etc, acorrding to the manner of sunrise. +``init`` function in your ``{APP_ROOT}/app.js`` is a entry point for your application. You can add some paths for your web services, booting scripts for setup your database, ... etc, acorrding to the manner of sunrise. And ``app.js`` is a design document on CouchDB. You can define MapReduce views, list, show functions, and also add attachements for static file hosting. .. warning:: The feature of static file hosting is provided by Node engine, not by CouchDB currently. So you can define attachments for future use. +Next step, we will describe the view feature of the sunrise. diff --git a/doc/source/tutorial/view.rst b/doc/source/tutorial/view.rst new file mode 100644 index 0000000..2c66fbf --- /dev/null +++ b/doc/source/tutorial/view.rst @@ -0,0 +1,155 @@ +View development +-------------------------------------------------------------------------------- + +Directory Structure +================================================================================ + +Application view consist of several directories located under ``_attachments`` directory. +All of files are pused into CouchDB as attachement files of the design document so that your client-side javascript and server-side javascript can share the view resources via HTTP. + +Here are the files generated by default. + +:: + + _attachments/ + ├── css + │   └── myapp.less + ├── js + │   └── myapp.js + ├── messages + │   └── en.json + └── templates + └── index.ejs + + +View Template +================================================================================ + +``templates`` directory is the view root directory. The file path given in ``render`` function is searched from this directory. + +.. code-block:: javascript + + render('index.ejs') + // => use {APP_ROOT}/templates/index.ejs + +The ``layout`` file is searched from ``{APP_ROOT}/_attachments/templates`` directory, which is same as Express. And if not found, it is tried to be searched from ``{SITE_ROOT}/_attachments/templates`` directory at ``site`` application to provide uniform design views. + +By default ``layout`` file is ``'layout.ejs'`` and ``{SITE_ROOT}/_attachments/templates/layout.ejs``is used according to that rule. + +More details about generated files +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +``index.ejs`` file is as follows: + +.. code-block:: html + + + <% title('My App') %> + <% css('css/myapp.css') %> + <% js('js/myapp.js') %> +
+

My Application

+

+ <%= _("myapp.helloworld") %> +

+
+ +``title()``, ``css()`` and ``js()`` functions in ``index.ejs`` configure ``page.*`` object ``layout.ejs``. + +- ``title()`` set the value of ``page.title``. +- ``css()`` adds stylesheet resource path to ``page.stylesheets`` array. +- ``js()`` adds javascript file path to ``page.javascripts`` array. + +And ``_()`` function is a function for :ref:`i18n-m10n`. ``"myapp.helloworld"`` is defined in ``{APP_ROOT}/_attachments/messages/en.json`` file. See complete description at :doc:`/ref/helper`. + +Now check the ``layout.ejs`` file. + +.. code-block:: html + + + <% $system.required() /* to add static resources required by $system helper */ %> + + + + <%= page.title %> - sunrise + <% if( page.feed ){ %><% } %> + <% if( page.canonical ){ %><% } %> + + + + + + <% for(var i in page.stylesheets){ %> + + <% } %> + + + + +
+
+ <%- body %> +
+
+ + + + <% for(var i in page.javascripts){ %> + + <% } %> + + + +There are 3 points we should mention. + +First, ``page.*`` values are used for constructing meta tags (as mentioned above). + +Second, there are some functions that start with ``$system``. ``$name`` is a helper object defined by the ``name`` application. ``$system`` is a object that contains helper functions defined in ``system`` application. You can refer to :doc:`/tutorial/helper` to define your helper methods open to other applications. + +``$system`` helper functions are descibed at :doc:`/apps/system` + +And last, several third party resources are used in ``layout.ejs``. + +- `blueprint `_ css framework. This is important to compile .less file. +- `jQuery `_ and `jQuery UI `_ javascript framework. + +These are not configurable in the current version of sunrise, which will be fixed in the future. + +Message bundles +================================================================================ + +.. warning:: under consturction. See :ref:`i18n-m10n` for your help. + +Stylesheet +================================================================================ + +As same as Express, you can use ``.less`` file for dynamic compilation of stylesheet files. In addition to this, you can get more powerful feature in ``.less`` development. + +Sunrise compiles your ``.less`` files with integrating blueprint so that you can use blueprint style definitions [#f1]_ in your ``.less`` files. For example, + +.. code-block:: css + + div.something { + .span-19; + .append-1; + } + +``.span-19`` and ``.append-1`` is defined in blueprint and sunrise compile this style definition into: + +.. code-block:: css + + div.something { + width:750px; + padding-right:40px; + } + +.. [#f1] Cheat sheet is available at http://blueprintcss.org/media/BlueprintV0.8byGJMS.pdf