cubicweb: comparison doc/book/en/annexes/faq.rst

equal deleted inserted replaced

-:b5ed84c53b3f
+:4dad0ec0a44f
 .. -*- coding: utf-8 -*-
-Frequently Asked Questions
+Frequently Asked Questions (FAQ)
-==========================
+================================
 [XXX 'copy answer from forum' means reusing text from
 http://groups.google.com/group/google-appengine/browse_frm/thread/c9476925f5f66ec6
 and
 http://groups.google.com/group/google-appengine/browse_frm/thread/f48cf6099973aef5/c28cd6934dd72457
 You can see the roadmap there:
 http://www.cubicweb.org/project/cubicweb?tab=projectroadmap_tab.
 Why is the RQL query language looking similar to X ?
------------------------------------------------------
+----------------------------------------------------
 It may remind you of SQL but it is higher level than SQL, more like
 SPARQL. Except that SPARQL did not exist when we started the project.
 With version 3.4, CubicWeb has support for SPARQL.
 RQL.
 Which ajax library is CubicWeb using ?
 --------------------------------------
-CubicWeb uses jQuery and provides a few helpers on top of
+CubicWeb uses jQuery_ and provides a few helpers on top of that. Additionally,
-that. Additionally, some jQuery plugins are provided (some are
+some jQuery plugins are provided (some are provided in specific cubes).
-provided in specific cubes).
+.. _jQuery: http://jquery.com
 Development
 ```````````
-How to load data from a script ?
+How to change the instance logo ?
---------------------------------
+---------------------------------
-The following script aims at loading data within a script assuming pyro-nsd is
+There are two ways of changing the logo.
-running and your instance is configured with ``pyro-server=yes``, otherwise
-you would not be able to use dbapi.
+1. The easiest way to use a different logo is to replace the existing
+``logo.png`` in ``myapp/data`` by your prefered icon and refresh.
-.. sourcecode:: python
+By default all instance will look for a ``logo.png`` to be
+rendered in the logo section.
-from cubicweb import dbapi
+.. image:: ../images/lax-book_06-main-template-logo_en.png
-cnx = dbapi.connect(database='instance-id', user='admin', password='admin')
-cur = cnx.cursor()
+2. In your cube directory, you can specify which file to use for the logo.
-for name in ('Personal', 'Professional', 'Computers'):
+This is configurable in ``mycube/uiprops.py``: ::
-cur.execute('INSERT Blog B: B name %s', name)
-cnx.commit()
+LOGO = data('mylogo.gif')
+``mylogo.gif`` is in ``mycube/data`` directory.
-How to format an entity date attribute ?
-----------------------------------------
-If your schema has an attribute of type Date or Datetime, you might
-want to format it. First, you should define your preferred format using
-the site configuration panel ``http://appurl/view?vid=systempropertiesform``
-and then set ``ui.date`` and/or ``ui.datetime``.
-Then in the view code, use:
-.. sourcecode:: python
-self.format_date(entity.date_attribute)
-What is the CubicWeb datatype corresponding to GAE datastore's UserProperty ?
------------------------------------------------------------------------------
-If you take a look at your instance schema and
-click on "display detailed view of metadata" you will see that there
-is a Euser entity in there. That's the one that is modeling users. The
-thing that corresponds to a UserProperty is a relationship between
-your entity and the Euser entity. As in:
-.. sourcecode:: python
-class TodoItem(EntityType):
-text = String()
-todo_by = SubjectRelation('Euser')
-[XXX check that cw handle users better by mapping Google Accounts to local Euser
-entities automatically]
-How do I translate an msg id defined (and translated) in another cube ?
------------------------------------------------------------------------
-You should put these translations in the `i18n/static-messages.pot`
-file of your own cube.
-What is `Error while publishing rest text ...` ?
-------------------------------------------------
-While modifying the description of an entity, you get an error message in
-the instance `Error while publishing ...` for Rest text and plain text.
-The server returns a traceback like as follows ::
-2008-10-06 15:05:08 - (cubicweb.rest) ERROR: error while publishing ReST text
-Traceback (most recent call last):
-File "/home/user/src/blogdemo/cubicweb/common/rest.py", line 217, in rest_publish
-File "/usr/lib/python2.5/codecs.py", line 817, in open
-file = __builtin__.open(filename, mode, buffering)
-TypeError: __init__() takes at most 3 arguments (4 given)
-This can be fixed by applying the patch described in :
-http://code.google.com/p/googleappengine/issues/detail?id=48
-What are hooks used for ?
--------------------------
-Hooks are executed around (actually before or after) events.  The
-most common events are data creation, update and deletion.  They
-permit additional constraint checking (those not expressible at the
-schema level), pre and post computations depending on data
-movements.
-As such, they are a vital part of the framework.
-Other kinds of hooks, called Operations, are available
-for execution just before commit.
-When should you define an HTML template rather than define a graphical component ?
-----------------------------------------------------------------------------------
-An HTML template cannot contain code, hence it is only about static
-content.  A component is made of code and operations that apply on a
-well defined context (request, result set). It enables much more
-dynamic views.
-How to update a database after a schema modification ?
-------------------------------------------------------
-It depends on what has been modified in the schema.
-* update the permissions and properties of an entity or a relation:
-``sync_schema_props_perms('MyEntityOrRelation')``.
-* add an attribute: ``add_attribute('MyEntityType', 'myattr')``.
-* add a relation: ``add_relation_definition('SubjRelation', 'MyRelation', 'ObjRelation')``.
 How to create an anonymous user ?
 ---------------------------------
-This allows to bypass authentication for your site. In the
+This allows to browse the site without being authenticated. In the
 ``all-in-one.conf`` file of your instance, define the anonymous user
 as follows ::
 # login of the CubicWeb user account to use for anonymous user (if you want to
 # allow anonymous)
 # password of the CubicWeb user account matching login
 anonymous-password=anon
 You also must ensure that this `anon` user is a registered user of
 the DB backend. If not, you can create through the administation
-interface of your instance by adding a user with the role `guests`.
+interface of your instance by adding a user with in the group `guests`.
-This could be the admin account (for development
-purposes, of course).
 .. note::
 While creating a new instance, you can decide to allow access
 to anonymous user, which will automatically execute what is
 decribed above.
+How to load data from a script ?
-How to change the instance logo ?
+--------------------------------
-------------------------------------
+The following script aims at loading data within a script assuming pyro-nsd is
-There are two ways of changing the logo.
+running and your instance is configured with ``pyro-server=yes``, otherwise
+you would not be able to use dbapi.
-1. The easiest way to use a different logo is to replace the existing
-``logo.png`` in ``myapp/data`` by your prefered icon and refresh.
+.. sourcecode:: python
-By default all instance will look for a ``logo.png`` to be
-rendered in the logo section.
+from cubicweb import dbapi
-.. image:: ../images/lax-book_06-main-template-logo_en.png
+cnx = dbapi.connect(database='instance-id', user='admin', password='admin')
+cur = cnx.cursor()
-2. In your cube directory, you can specify which file to use for the logo.
+for name in (u'Personal', u'Professional', u'Computers'):
-This is configurable in ``mycube/data/external_resources``: ::
+cur.execute('INSERT Tag T: T name %(n)s', {'n': name})
+cnx.commit()
-LOGO = DATADIR/path/to/mylogo.gif
+Wether your instance as pyro activated or not, you can still acheive this by
-where DATADIR is ``mycube/data``.
+using cubicweb-ctl shell scripts.
+How to format an entity date attribute ?
+----------------------------------------
+If your schema has an attribute of type `Date` or `Datetime`, you usually want to
+format it when displaying it. First, you should define your preferred format
+using the site configuration panel
+``http://appurl/view?vid=systempropertiesform`` and then set ``ui.date`` and/or
+``ui.datetime``.  Then in the view code, use:
+.. sourcecode:: python
+entity.printable_value(date_attribute)
+which will always return a string whatever the attribute's type (so it's
+recommended also for other attribute types). By default it expects to generate
+HTML, so it deals with rich text formating, xml escaping...
+How do I translate an msg id defined (and translated) in another cube ?
+-----------------------------------------------------------------------
+You should put these translations in the `i18n/static-messages.pot`
+file of your own cube.
+How to update a database after a schema modification ?
+------------------------------------------------------
+It depends on what has been modified in the schema.
+* update the permissions and properties of an entity or a relation:
+``sync_schema_props_perms('MyEntityOrRelation')``.
+* add an attribute: ``add_attribute('MyEntityType', 'myattr')``.
+* add a relation: ``add_relation_definition('SubjRelation', 'MyRelation', 'ObjRelation')``.
+I get `NoSelectableObject` exceptions, how do I debug selectors ?
+-----------------------------------------------------------------
+You just need to put the appropriate context manager around view/component
+selection. One standard place for components is in cubicweb/vregistry.py:
+.. sourcecode:: python
+def possible_objects(self, *args, **kwargs):
+"""return an iterator on possible objects in this registry for the given
+context
+"""
+from cubicweb.selectors import traced_selection
+with traced_selection():
+for appobjects in self.itervalues():
+try:
+yield self._select_best(appobjects, *args, **kwargs)
+except NoSelectableObject:
+continue
+Don't forget the 'from __future__ import with_statement' at the module
+top-level if you're using python 2.5.
+This will yield additional WARNINGs, like this::
+2009-01-09 16:43:52 - (cubicweb.selectors) WARNING: selector one_line_rset returned 0 for <class 'cubicweb.web.views.basecomponents.WFHistoryVComponent'>
+For views, you can put this context in `cubicweb/web/views/basecontrollers.py` in
+the `ViewController`:
+.. sourcecode:: python
+def _select_view_and_rset(self, rset):
+...
+try:
+from cubicweb.selectors import traced_selection
+with traced_selection():
+view = self._cw.vreg['views'].select(vid, req, rset=rset)
+except ObjectNotFound:
+self.warning("the view %s could not be found", vid)
+req.set_message(req._("The view %s could not be found") % vid)
+vid = vid_from_rset(req, rset, self._cw.vreg.schema)
+view = self._cw.vreg['views'].select(vid, req, rset=rset)
+...
+I get "database is locked" when executing tests
+-----------------------------------------------
+If you have "database is locked" as error when you are executing security tests,
+it is usually because commit or rollback are missing before login() calls.
+You can also use a context manager, to avoid such errors, as described
+here: :ref:`securitytest`.
+What are hooks used for ?
+-------------------------
+Hooks are executed around (actually before or after) events.  The most common
+events are data creation, update and deletion.  They permit additional constraint
+checking (those not expressible at the schema level), pre and post computations
+depending on data movements.
+As such, they are a vital part of the framework.
+Other kinds of hooks, called Operations, are available
+for execution just before commit.
+For more information, read :ref:`hooks` section.
 Configuration
 `````````````
 How to configure a LDAP source ?
 --------------------------------
-Your instance's sources are defined in ``/etc/cubicweb.d/myapp/sources``.
+See :ref:`LDAP`.
-Configuring an LDAP source is about declaring that source in your
-instance configuration file such as: ::
-[ldapuser]
-adapter=ldapuser
-# ldap host
-host=myhost
-# base DN to lookup for usres
-user-base-dn=ou=People,dc=mydomain,dc=fr
-# user search scope
-user-scope=ONELEVEL
-# classes of user
-user-classes=top,posixAccount
-# attribute used as login on authentication
-user-login-attr=uid
-# name of a group in which ldap users will be by default
-user-default-group=users
-# map from ldap user attributes to cubicweb attributes
-user-attrs-map=gecos:email,uid:login
-Any change applied to configuration file requires to restart your
-instance.
-You can find additional information in the section :ref:`LDAP`.
 How to import LDAP users in |cubicweb| ?
 ----------------------------------------
 Here is a useful script which enables you to import LDAP users
 cnx.commit()
 cnx.close()
-I get NoSelectableObject exceptions, how do I debug selectors ?
----------------------------------------------------------------
-You just need to put the appropriate context manager around view/component
-selection (one standard place in in vreg.py):
-.. sourcecode:: python
-def possible_objects(self, registry, *args, **kwargs):
-"""return an iterator on possible objects in a registry for this result set
-actions returned are classes, not instances
-"""
-from cubicweb.selectors import traced_selection
-with traced_selection():
-for vobjects in self.registry(registry).values():
-try:
-yield self.select(vobjects, *args, **kwargs)
-except NoSelectableObject:
-continue
-Don't forget the 'from __future__ import with_statement' at the module
-top-level.
-This will yield additional WARNINGs, like this::
-2009-01-09 16:43:52 - (cubicweb.selectors) WARNING: selector one_line_rset returned 0 for <class 'cubicweb.web.views.basecomponents.WFHistoryVComponent'>
 Security
 ````````
 How to reset the password for user joe ?
 ----------------------------------------
 update cw_cwuser set cw_upassword=CONVERT(varbinary(255), 'qHO8282QN5Utg') where cw_login='joe';
 Be careful, the encryption algorithm is different on Windows and on
 Unix. You cannot therefore use a hash generated on Unix to fill in a
 Windows database, nor the other way round.
 You can prefer use a migration script similar to this shell invocation instead::
 $ cubicweb-ctl shell <instance>
 You are probably getting errors such as ::
 remove {'PR': 'Project', 'C': 'CWUser'} from solutions since your_user has no read access to cost
-This is because you have to put your user in the "users" group. The user has to be in both groups.
+This is because you have to put your user in the "users" group. The user has to
+be in both groups.
 How is security implemented ?
 ------------------------------
 The basis for security is a mapping from operations to groups or
 You can find additional information in the section :ref:`securitymodel`.
 Is it possible to bypass security from the UI (web front) part ?
 ----------------------------------------------------------------
-No.
+No. Only Hooks/Operations can do that.
-Only Hooks/Operations can do that.
 Can PostgreSQL and CubicWeb authentication work with kerberos ?
 ----------------------------------------------------------------
 If you have PostgreSQL set up to accept kerberos authentication, you can set

changeset 6592	4dad0ec0a44f
parent 6352	2259d834d757
child 7250	fe27390bf2f8