Commit c26367e9 authored by Sylvain Thénault's avatar Sylvain Thénault
Browse files

[book] fixes some references and other doc construction pbs

* predefine order of js files in index generation, skip some files
* fix some references to the base tutorial (recently changed)
* other ReST fixes

--HG--
branch : stable
parent 54944faf9b61
......@@ -2,7 +2,7 @@
.. _SetUpEnv:
Installation and set-up of a *CubicWeb* environment
Installation and set-up of a |cubicweb| environment
===================================================
Installation of `Cubicweb` and its dependencies
......@@ -68,8 +68,8 @@ cubes.
`cubicweb with postgresql datatabase`_ and `cubicweb-mysql-support` contains
necessary dependency for using `cubicweb with mysql database`_ .
There is also a wide variety of :ref:`cubes <Cubes>` listed on the `CubicWeb.org Forge`_
available as debian packages and tarball.
There is also a wide variety of :ref:`cubes <AvailableCubes>` listed on the
`CubicWeb.org Forge`_ available as debian packages and tarball.
The repositories are signed with `Logilab's gnupg key`_. To avoid warning on
"apt-get update":
......
......@@ -16,5 +16,4 @@ The following chapters are reference material.
rql/index
mercurial
depends
javascript-api
docstrings-conventions
.. _RQLChapter
.. _RQLChapter:
Relation Query Language (RQL)
=============================
......
.. _AvailableCubes:
Available cubes
---------------
......
......@@ -8,14 +8,13 @@ Defining a Workflow
General
-------
A workflow describes how certain entities have to evolve between
different states. Hence we have a set of states, and a "transition
graph", i.e. a set of possible transitions from one state to another
state.
We will define a simple workflow for a blog, with only the following
two states: `submitted` and `published`. So first, we create a simple
|cubicweb| instance in five minutes (see :ref:`BlogFiveMinutes`).
A workflow describes how certain entities have to evolve between different
states. Hence we have a set of states, and a "transition graph", i.e. a set of
possible transitions from one state to another state.
We will define a simple workflow for a blog, with only the following two states:
`submitted` and `published`. You may want to take a look at :ref:`_TutosBase` if
you want to quickly setup an instance running a blog.
Setting up a workflow
---------------------
......
......@@ -117,7 +117,7 @@ javascript (`$('#sendmail')` being the jQuery call to get the element with DOM i
set to 'sendmail', which is our form DOM id as specified by its `domid`
attribute), another to cancel the form which will go back to the previous page
using another javascript call. Also we specify an image to use as button icon as a
resource identifier (see :ref:`external_resources`) given as last argument to
resource identifier (see :ref:`uiprops`) given as last argument to
:class:`cubicweb.web.formwidgets.ImgButton`.
To see this form, we still have to wrap it in a view. This is pretty simple:
......@@ -131,12 +131,13 @@ To see this form, we still have to wrap it in a view. This is pretty simple:
def call(self):
form = self._cw.vreg['forms'].select('massmailing', self._cw,
rset=self.cw_rset)
self.w(form.render())
form.render(w=self.w)
As you see, we simply define a view with proper selector so it only apply to a
result set containing :class:`IEmailable` entities, and so that only users in the
managers or users group can use it. Then in the `call()` method for this view we
simply select the above form and write what its `.render()` method returns.
simply select the above form and call its `.render()` method with our output
stream as argument.
When this form is submitted, a controller with id 'sendmail' will be called (as
specified using `action`). This controller will be responsible to actually send
......
.. -*- coding: utf-8 -*-
.. |cubicweb| replace:: *CubicWeb*
.. _templates:
Templates
......
......@@ -226,8 +226,6 @@ Example of customization and creation
We'll show you now an example of a ``primary`` view and how to customize it.
We continue along the basic tutorial :ref:`tuto_blog`.
If you want to change the way a ``BlogEntry`` is displayed, just
override the method ``cell_call()`` of the view ``primary`` in
``BlogDemo/views.py``.
......@@ -247,7 +245,7 @@ override the method ``cell_call()`` of the view ``primary`` in
The above source code defines a new primary view for
``BlogEntry``. The `id` class attribute is not repeated there since it
``BlogEntry``. The `__reid__` class attribute is not repeated there since it
is inherited through the `primary.PrimaryView` class.
The selector for this view chains the selector of the inherited class
......
......@@ -13,19 +13,28 @@ principles.
Its main features are:
* an engine driven by the explicit :ref:`data model <DefineDataModel>` of the application,
* an engine driven by the explicit :ref:`data model
<TutosBaseCustomizingTheApplicationDataModel>` of the application,
* a query language named :ref:`RQL <RQL>` similar to W3C's SPARQL,
* a :ref:`selection+view <DefineViews>` mechanism for semi-automatic XHTML/XML/JSON/text generation,
* a library of reusable :ref:`components <cubes>` (data model and views) that fulfill common needs,
* a :ref:`selection+view <TutosBaseCustomizingTheApplicationCustomViews>`
mechanism for semi-automatic XHTML/XML/JSON/text generation,
* a library of reusable :ref:`components <Cube>` (data model and views) that
fulfill common needs,
* the power and flexibility of the Python_ programming language,
* the reliability of SQL databases, LDAP directories, Subversion and Mercurial for storage backends.
* the reliability of SQL databases, LDAP directories, Subversion and Mercurial
for storage backends.
Built since 2000 from an R&D effort still continued, supporting 100,000s of
daily visits at some production sites, |cubicweb| is a proven end to end solution
for semantic web application development that promotes quality, reusability and
efficiency.
The unbeliever will read the :ref:`Tutorial`.
The unbeliever will read the :ref:`Tutorials`.
The hacker will join development at the forge_.
......
......@@ -33,7 +33,7 @@ help:
clean:
rm -f *.html
-rm -rf ${BUILDDIR}/*
-rm -rf ${BUILDDIR}/html ${BUILDDIR}/doctrees
-rm -rf ${BUILDJS}
all: html
......
Building my photos web site with CubicWeb part IV: let's make it more user friendly
===================================================================================
Let's make it more user friendly
================================
Step 0: updating code to CubicWeb 3.9 / cubicweb-file 1.9
......@@ -200,12 +200,12 @@ Also, we added a title that tries to make it more evident that the visitor is
authenticated, or not. Hopefuly people will get it now!
.. figure:: ../../images/tutos-photowebsite_index_before.png
.. figure:: ../../images/tutos-photowebsite_index-before.png
:alt: default index page screenshot
The default index page
.. figure:: ../../images/tutos-photowebsite_index_after.png
.. figure:: ../../images/tutos-photowebsite_index-after.png
:alt: new index page screenshot
Our simpler, less intimidating, index page (still translated in french)
......
Building my photos web site with |cubiweb| part V: let's make it even more user friendly
Building my photos web site with |cubicweb| part V: let's make it even more user friendly
=========================================================================================
We'll now see how to benefit from features introduced in 3.9 and 3.10 releases of CubiWeb
We'll now see how to benefit from features introduced in 3.9 and 3.10 releases of CubicWeb
Step 1: Tired of the default look?
Step 1: tired of the default look?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OK... Now our site has its most desired features. But... I would like to make it look
......@@ -12,8 +12,8 @@ first!
The first thing we can to is to change the logo. There are various way to achieve
this. The easiest way is to put a :file:`logo.png` file into the cube's :file:`data`
directory. As data files are looked at according to cubes order (CubiWeb
resources coming last), that file will be selected instead of CubiWeb's one.
directory. As data files are looked at according to cubes order (CubicWeb
resources coming last), that file will be selected instead of CubicWeb's one.
.. Note::
As the location for static resources are cached, you'll have to restart
......@@ -27,14 +27,14 @@ the cube's :file:`uiprops.py` file:
LOGO = data('logo.jpg')
The uiprops machinery has been introduced in `CubiWeb 3.9`_. It is used to define
The uiprops machinery has been introduced in `CubicWeb 3.9`_. It is used to define
some static file resources, such as the logo, default Javascript / CSS files, as
well as CSS properties (we'll see that later).
.. Note::
This file is imported specifically by |cubicweb|, with a predefined name space,
containing for instance the `data` function, telling the file is somewhere
in a cube or CubiWeb's data directory.
in a cube or CubicWeb's data directory.
One side effect of this is that it can't be imported as a regular python
module.
......@@ -44,7 +44,7 @@ and then automatically reloaded.
Now, as it's a photos web-site, I would like to have a photo of mine as background...
After some trials I won't detail here, I've found a working recipe explained `here`_.
All I've to do is to override some stuff of the default CubiWeb user interface to
All I've to do is to override some stuff of the default CubicWeb user interface to
apply it as explained.
The first thing to to get the ``<img/>`` tag as first element after the
......@@ -144,11 +144,11 @@ introduced above:
STYLESHEETS = sheet['STYLESHEETS'] + [data('cubes.sytweb.css')]
.. Note:
.. Note::
`sheet` is another predefined variable containing values defined by
already process `:file:`uiprops.py`` file, notably the CubiWeb's one.
already process `:file:`uiprops.py`` file, notably the CubicWeb's one.
Here we simply want our CSS in addition to CubiWeb's base CSS files, so we
Here we simply want our CSS in addition to CubicWeb's base CSS files, so we
redefine the `STYLESHEETS` variable to existing CSS (accessed through the `sheet`
variable) with our one added. I could also have done:
......@@ -163,7 +163,7 @@ resized to fit the screen.
.. image:: ../../images/tutos-photowebsite_background-image.png
The final touch: let's customize CubiWeb's CSS to get less orange... By simply adding
The final touch: let's customize CubicWeb's CSS to get less orange... By simply adding
.. sourcecode:: python
......@@ -174,7 +174,7 @@ the orange one:
.. image:: ../../images/tutos-photowebsite_grey-box.png
This is because CubiWeb's CSS include some variables which are
This is because CubicWeb's CSS include some variables which are
expanded by values defined in uiprops file. In our case we controlled the
properties of the CSS `background` property of boxes with CSS class
`contextualBoxTitleBg` and `incontextBoxTitleBg`.
......@@ -290,7 +290,7 @@ Let's see how it looks like on a file primary view:
Great, it's now as easy for me to link my pictures to people than to tag them.
Also, visitors get a consistent display of these two pieces of information.
.. Note:
.. Note::
The ui component system has been refactored in `CubicWeb 3.10`_, which also
introduced the :class:`AjaxEditRelationCtxComponent` class.
......@@ -301,7 +301,7 @@ Step 3: configuring facets
The last feature we'll add today is facet configuration. If you access to the
'/file' url, you'll see a set of 'facets' appearing in the left column. Facets
provide an intuitive way to build a query incrementally, by proposing to the user
various way to restrict the result set. For instance CubiWeb proposes a facet to
various way to restrict the result set. For instance CubicWeb proposes a facet to
restrict based on who created an entity; the tag cube proposes a facet to
restrict based on tags; the zoe cube a facet to restrict based on geographical
location, and so on. In that gist, I want to propose a facet to restrict based on
......@@ -310,7 +310,7 @@ the people displayed on the picture. To do so, there are various classes in the
attributes as we've done for the box. In our case, we'll define a subclass of
:class:`RelationFacet`.
.. Note:
.. Note::
Since that's ui stuff, we'll continue to add code below to our
:file:`views.py` file. Though we begin to have a lot of various code their, so
......@@ -348,7 +348,7 @@ Now if I search for some pictures on my site, I get the following facets availab
.. image:: ../../images/tutos-photowebsite_facets.png
.. Note:
.. Note::
By default a facet must be applyable to every entity in the result set and
provide at leat two elements of vocabulary to be displayed (for instance you
......@@ -370,6 +370,6 @@ friends...
.. _`CubicWeb 3.10`: https://www.cubicweb.org/blogentry/1330518
.. _`CubicWeb 3.10`: http://www.cubicweb.org/blogentry/1330518
.. _`CubicWeb 3.9`: http://www.cubicweb.org/blogentry/1179899
.. _`here`: http://webdesign.about.com/od/css3/f/blfaqbgsize.htm
......@@ -41,7 +41,7 @@ and then create your new cube using: ::
cubicweb-ctl newcube --directory=~/src/cubes myblog
.. Note:
.. Note::
We previously used `myblog` as the name of our *instance*. We're now creating
a *cube* with the same name. Both are different things. We'll now try to
......@@ -63,6 +63,7 @@ file:
where the ``None`` means we do not depends on a particular version of the cube.
.. _TutosBaseCustomizingTheApplicationDataModel:
Extending the data model
~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -179,6 +180,8 @@ framework.
You'll then be able to redefine each of them according to your needs
and preferences. We'll now see how to do such thing.
.. _TutosBaseCustomizingTheApplicationCustomViews:
Defining your views
~~~~~~~~~~~~~~~~~~~
......
......@@ -150,7 +150,7 @@ Examples:
If you want to change cubicweb test server parameters, you can check class
variables from :class:`CubicWebServerConfig` or inherit it with overriding the
:var:`configcls` attribute in :class:`CubicWebServerTC` ::
:attr:`configcls` attribute in :class:`CubicWebServerTC` ::
.. sourcecode:: python
......
......@@ -4,6 +4,7 @@ Parser for Javascript comments.
"""
from __future__ import with_statement
import os.path as osp
import sys, os, getopt, re
def clean_comment(match):
......@@ -71,34 +72,48 @@ def parse_js_files(args=sys.argv):
if rst_dir is None and len(args) != 1:
rst_dir = 'apidocs'
js_dir = opts.get('--jspath') or opts.get('-p')
if not os.path.exists(os.path.join(rst_dir)):
os.makedirs(os.path.join(rst_dir))
if not osp.exists(osp.join(rst_dir)):
os.makedirs(osp.join(rst_dir))
f_index = open(os.path.join(rst_dir, 'index.rst'), 'wb')
f_index.write('''
.. toctree::
:maxdepth: 1
'''
)
index = set()
for js_path, js_dirs, js_files in os.walk(js_dir):
rst_path = re.sub('%s%s*' % (js_dir, os.path.sep), '', js_path)
rst_path = re.sub('%s%s*' % (js_dir, osp.sep), '', js_path)
for js_file in js_files:
if not js_file.endswith('.js'):
continue
if not os.path.exists(os.path.join(rst_dir, rst_path)):
os.makedirs(os.path.join(rst_dir, rst_path))
if js_file in FILES_TO_IGNORE:
continue
if not osp.exists(osp.join(rst_dir, rst_path)):
os.makedirs(osp.join(rst_dir, rst_path))
rst_content = extract_rest(js_path, js_file)
filename = os.path.join(rst_path, js_file[:-3])
filename = osp.join(rst_path, js_file[:-3])
# add to index
f_index.write(' %s\n' % filename)
index.add(filename)
# save rst file
with open(os.path.join(rst_dir, filename) + '.rst', 'wb') as f_rst:
with open(osp.join(rst_dir, filename) + '.rst', 'wb') as f_rst:
f_rst.write(rst_content)
f_index.close()
stream = open(osp.join(rst_dir, 'index.rst'), 'w')
stream.write('''
.. toctree::
:maxdepth: 1
''')
# first write expected files in order
for fileid in INDEX_IN_ORDER:
try:
index.remove(fileid)
except:
raise Exception(
'Bad file id %s referenced in INDEX_IN_ORDER in %s, '
'fix this please' % (fileid, __file__))
stream.write(' %s\n' % fileid)
# append remaining, by alphabetical order
for fileid in sorted(index):
stream.write(' %s\n' % fileid)
stream.close()
def extract_rest(js_dir, js_file):
js_filepath = os.path.join(js_dir, js_file)
js_filepath = osp.join(js_dir, js_file)
filecontent = open(js_filepath, 'U').read()
comments = get_doc_comments(filecontent)
rst = rest_title(js_file, 0)
......@@ -106,5 +121,50 @@ def extract_rest(js_dir, js_file):
rst += '\n\n'.join(comments)
return rst
INDEX_IN_ORDER = [
'cubicweb',
'cubicweb.python',
'cubicweb.htmlhelpers',
'cubicweb.ajax',
'cubicweb.lazy',
'cubicweb.tabs',
'cubicweb.ajax.box',
'cubicweb.facets',
'cubicweb.widgets',
'cubicweb.image',
'cubicweb.flot',
'cubicweb.calendar',
'cubicweb.preferences',
'cubicweb.edition',
'cubicweb.reledit',
'cubicweb.iprogress',
'cubicweb.rhythm',
'cubicweb.gmap',
'cubicweb.timeline-ext',
]
FILES_TO_IGNORE = set([
'jquery.js',
'jquery.treeview.js',
'jquery.json.js',
'jquery.tablesorter.js',
'jquery.timePicker.js',
'jquery.flot.js',
'jquery.corner.js',
'jquery.ui.js',
'ui.core.js',
'ui.tabs.js',
'ui.slider.js',
'excanvas.js',
'gmap.utility.labeledmarker.js',
'cubicweb.fckcwconfig.js',
'cubicweb.fckcwconfig-full.js',
'cubicweb.goa.js',
'cubicweb.compat.js',
'cubicweb.timeline-bundle.js',
])
if __name__ == '__main__':
parse_js_files()
......@@ -212,7 +212,7 @@ The existing categories are:
* ``integrity``, data integrity checking hooks
* ``activeintegrity``, data integrity consistency hooks, that you should *never*
* ``activeintegrity``, data integrity consistency hooks, that you should **never**
want to disable
* ``syncsession``, hooks synchronizing existing sessions
......
......@@ -16,12 +16,14 @@ TODAY = new Date();
* .. class:: Calendar
*
* Calendar (graphical) widget
*
* public methods are :
*
* __init__ :
* @param containerId: the DOM node's ID where the calendar will be displayed
* @param inputId: which input needs to be updated when a date is selected
* @param year, @param month: year and month to be displayed
* @param cssclass: CSS class of the calendar widget (default is commandCal)
* :attr:`containerId`: the DOM node's ID where the calendar will be displayed
* :attr:`inputId`: which input needs to be updated when a date is selected
* :attr:`year`, :attr:`month`: year and month to be displayed
* :attr:`cssclass`: CSS class of the calendar widget (default is 'commandCal')
*
* show() / hide():
* show or hide the calendar widget
......
......@@ -32,14 +32,15 @@ forEach = cw.utils.deprecatedFunction(
/**
* .. function:: cw.utils.deprecatedFunction(msg, function)
*
* jQUery flattens arrays returned by the mapping function:
* >>> y = ['a:b:c', 'd:e']
* >>> jQuery.map(y, function(y) { return y.split(':');})
* ["a", "b", "c", "d", "e"]
* // where one would expect:
* [ ["a", "b", "c"], ["d", "e"] ]
* XXX why not the same argument order as $.map and forEach ?
* jQUery flattens arrays returned by the mapping function: ::
*
* >>> y = ['a:b:c', 'd:e']
* >>> jQuery.map(y, function(y) { return y.split(':');})
* ["a", "b", "c", "d", "e"]
* // where one would expect:
* [ ["a", "b", "c"], ["d", "e"] ]
*/
// XXX why not the same argument order as $.map and forEach ?
map = cw.utils.deprecatedFunction(
'[3.9] map() is deprecated, use $.map instead',
function(func, array) {
......
/**
* toggle visibility of an element by its id
* & set current visibility status in a cookie
* XXX whenever used outside of preferences, don't forget to
* move me in a more appropriate place
* toggle visibility of an element by its id & set current visibility status in a cookie
*
*/
var prefsValues = {};
......
......@@ -248,9 +248,11 @@ function makeConstructor(userctor) {
* this is a js class factory. objects returned by this function behave
* more or less like a python class. The `class` function prototype is
* inspired by the python `type` builtin
* Important notes :
* -> methods are _STATICALLY_ attached when the class it created
* -> multiple inheritance was never tested, which means it doesn't work ;-)
*
* .. Note::
*
* * methods are _STATICALLY_ attached when the class it created
* * multiple inheritance was never tested, which means it doesn't work ;-)
*/
function defclass(name, bases, classdict) {
var baseclasses = bases || [];
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment