view development

yssk22 · May 26, 2011 · dbf6f48 · dbf6f48
1 parent 284ba92
commit dbf6f48
Show file tree

Hide file tree

Showing 6 changed files with 170 additions and 5 deletions.
diff --git a/doc/source/apps/system.rst 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
@@ -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
@@ -0,0 +1,2 @@
+Helper function development
+===============================================================================
diff --git 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
@@ -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
@@ -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
+
+   <!-- {APP_ROOT}/_attachments/templates/index.ejs -->
+   <% title('My App') %>
+   <% css('css/myapp.css') %>
+   <% js('js/myapp.js') %>
+   <div class="my_app">
+     <h2>My Application</h2>
+     <p>
+       <%= _("myapp.helloworld") %>
+     </p>
+   </div>
+
+``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
+
+   <!DOCTYPE html>
+   <% $system.required() /* to add static resources required by $system helper */ %>
+   <html>
+     <head>
+       <meta charset="utf-8">
+       <title><%= page.title %> - sunrise</title>
+       <% if( page.feed ){ %><link rel="alternate" type="application/rss+xml" title="<%= page.title %>" href="<%= page.feed %>" /><% } %>
+       <% if( page.canonical ){ %><link rel="canonical" href="<%= page.canonical %>" /><% } %>
+       <link rel="stylesheet" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.12/themes/blitzer/jquery-ui.css" type="text/css" />
+       <link rel="stylesheet" href="/vendor/blueprint/blueprint/screen.css" type="text/css" media="screen, projection">
+       <link rel="stylesheet" href="/vendor/blueprint/blueprint/print.css" type="text/css" media="print">	
+       <!--[if lt IE 8]><link rel="stylesheet" href="/vendor/blueprint/blueprint/ie.css" type="text/css" media="screen, projection"><![endif]-->
+       <link rel="stylesheet" href="/css/sunrise.css" type="text/css" />
+       <% for(var i in page.stylesheets){ %>
+       <link rel="stylesheet" href="<%= page.stylesheets[i] %>" type="text/css" />
+       <% } %>
+       <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6/jquery.min.js"></script>
+     </head>
+     <body>
+       <header id="siteHeader" class="container">
+         <%- $system.logo() %>
+         <%- $system.accountNavigation('twitter') %>
+         <%- $system.siteNavigation() %>
+       </header>
+       <hr />
+       <div id="main" class="container">
+          <%- body %>
+       </div>
+       <hr />
+       <footer id="siteFooter" class="container">
+         <p class="copyright">
+           &copy; 2010 - 2011
+           <a href="https://github.com/yssk22/sunrise">Sunrise Project</a>
+         </p>
+       </footer>
+       <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.12/jquery-ui.min.js"></script>
+       <script type="text/javascript" src="http://ajax.cdnjs.com/ajax/libs/json2/20110223/json2.js"></script>
+       <% for(var i in page.javascripts){ %>
+       <script type="text/javascript" src="<%= page.javascripts[i] %>"></script>
+       <% } %>
+     </body>
+   </html>
+
+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 <http://www.blueprintcss.org/>`_ css framework. This is important to compile .less file.
+- `jQuery <http://jquery.com/>`_ and `jQuery UI <http://jqueryui.com/>`_ 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