# HG changeset patch # User Nicolas Chauvat # Date 1248819163 -7200 # Node ID f32af375339d04da7db6aa439e33e1f69e6dd9f0 # Parent df456fa1b053dd9202930de805861be2c40c3ed5 [doc] fix FAQ layout diff -r df456fa1b053 -r f32af375339d doc/book/en/annexes/faq.rst --- a/doc/book/en/annexes/faq.rst Tue Jul 28 23:55:56 2009 +0200 +++ b/doc/book/en/annexes/faq.rst Wed Jul 29 00:12:43 2009 +0200 @@ -14,79 +14,79 @@ Why does not CubicWeb have a template language ? ------------------------------------------------ - There are enough template languages out there. You can use your - preferred template language if you want. [explain how to use a - template language] +There are enough template languages out there. You can use your +preferred template language if you want. [explain how to use a +template language] - *CubicWeb* does not define its own templating language as this was - not our goal. Based on our experience, we realized that - we could gain productivity by letting designers use design tools - and developpers develop without the use of the templating language - as an intermediary that could not be anyway efficient for both parties. - Python is the templating language that we use in *CubicWeb*, but again, - it does not prevent you from using a templating language. +*CubicWeb* does not define its own templating language as this was +not our goal. Based on our experience, we realized that +we could gain productivity by letting designers use design tools +and developpers develop without the use of the templating language +as an intermediary that could not be anyway efficient for both parties. +Python is the templating language that we use in *CubicWeb*, but again, +it does not prevent you from using a templating language. - The reason template languages are not used in this book is that - experience has proved us that using pure python was less cumbersome. +The reason template languages are not used in this book is that +experience has proved us that using pure python was less cumbersome. Why do you think using pure python is better than using a template language ? ----------------------------------------------------------------------------- - Python is an Object Oriented Programming language and as such it - already provides a consistent and strong architecture and syntax - a templating language would not reach. +Python is an Object Oriented Programming language and as such it +already provides a consistent and strong architecture and syntax +a templating language would not reach. - When doing development, you need a real language and template - languages are not real languages. +When doing development, you need a real language and template +languages are not real languages. - Using Python instead of a template langage for describing the user interface - makes it to maintain with real functions/classes/contexts without the need of - learning a new dialect. By using Python, we use standard OOP techniques and - this is a key factor in a robust application. +Using Python instead of a template langage for describing the user interface +makes it to maintain with real functions/classes/contexts without the need of +learning a new dialect. By using Python, we use standard OOP techniques and +this is a key factor in a robust application. Why do you use the LGPL license to prevent me from doing X ? ------------------------------------------------------------ - LGPL means that *if* you redistribute your application, you need to - redistribute the changes you made to CubicWeb under the LGPL licence. +LGPL means that *if* you redistribute your application, you need to +redistribute the changes you made to CubicWeb under the LGPL licence. - Publishing a web site has nothing to do with redistributing - source code. A fair amount of companies use modified LGPL code - for internal use. And someone could publish a *CubicWeb* component - under a BSD licence for others to plug into a LGPL framework without - any problem. The only thing we are trying to prevent here is someone - taking the framework and packaging it as closed source to his own - clients. +Publishing a web site has nothing to do with redistributing +source code. A fair amount of companies use modified LGPL code +for internal use. And someone could publish a *CubicWeb* component +under a BSD licence for others to plug into a LGPL framework without +any problem. The only thing we are trying to prevent here is someone +taking the framework and packaging it as closed source to his own +clients. CubicWeb looks pretty recent. Is it stable ? -------------------------------------------- - It is constantly evolving, piece by piece. The framework has evolved since - 2001 and data has been migrated from one schema to the other ever since. There - is a well-defined way to handle data and schema migration. +It is constantly evolving, piece by piece. The framework has evolved since +2001 and data has been migrated from one schema to the other ever since. There +is a well-defined way to handle data and schema migration. 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. - Having SPARQL as a query language has been in our backlog for years. +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. - That RQL language is what is going to make a difference with django- - like frameworks for several reasons. +That RQL language is what is going to make a difference with django- +like frameworks for several reasons. - 1. accessing data is *much* easier with it. One can write complex - queries with RQL that would be tedious to define and hard to maintain - using an object/filter suite of method calls. +1. accessing data is *much* easier with it. One can write complex + queries with RQL that would be tedious to define and hard to maintain + using an object/filter suite of method calls. - 2. it offers an abstraction layer allowing your applications to run - on multiple back-ends. That means not only various SQL backends - (postgresql, sqlite, mysql), but also multiple databases at the - same time, and also non-SQL data stores like LDAP directories and - subversion/mercurial repositories (see the `vcsfile` - component). Google App Engine is yet another supported target for - RQL. +2. it offers an abstraction layer allowing your applications to run + on multiple back-ends. That means not only various SQL backends + (postgresql, sqlite, mysql), but also multiple databases at the + same time, and also non-SQL data stores like LDAP directories and + subversion/mercurial repositories (see the `vcsfile` + component). Google App Engine is yet another supported target for + RQL. [copy answer from forum, explain why similar to sparql and why better than django and SQL] @@ -100,7 +100,9 @@ How is security implemented ? ------------------------------ - This is an example of how it works in our framework:: +This is an example of how it works in our framework: + +.. sourcecode:: python class Version(EntityType): """a version is defining the content of a particular project's @@ -110,16 +112,17 @@ 'update': ('managers', 'logilab', 'owners',), 'delete': ('managers', ), 'add': ('managers', 'logilab', - ERQLExpression('X version_of PROJ, U in_group G, ' - 'PROJ require_permission P, ' - 'P name "add_version", P require_group G'),)} + ERQLExpression('X version_of PROJ, U in_group G, ' + 'PROJ require_permission P, ' + 'P name "add_version", P require_group G'),)} - The above means that permission to read a Version is granted to any - user that is part of one of the groups 'managers', 'users', 'guests'. - The 'add' permission is granted to users in group 'managers' or - 'logilab' and to users in group G, if G is linked by a permission - entity named "add_version" to the version's project. - :: +The above means that permission to read a Version is granted to any +user that is part of one of the groups 'managers', 'users', 'guests'. +The 'add' permission is granted to users in group 'managers' or +'logilab' and to users in group G, if G is linked by a permission +entity named "add_version" to the version's project. + +.. sourcecode:: python class version_of(RelationType): """link a version to its project. A version is necessarily linked @@ -128,20 +131,20 @@ permissions = {'read': ('managers', 'users', 'guests',), 'delete': ('managers', ), 'add': ('managers', 'logilab', - RRQLExpression('O require_permission P, P name "add_version", - 'U in_group G, P require_group G'),) } + RRQLExpression('O require_permission P, P name "add_version", ' + 'U in_group G, P require_group G'),) } - You can find additional information in the section :ref:`security`. +You can find additional information in the section :ref:`security`. - [XXX what does the second example means in addition to the first one?] +[XXX what does the second example means in addition to the first one?] 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 :: +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): @@ -150,70 +153,69 @@ 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 +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. +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. +As such, they are a vital part of the framework. - Other kinds of hooks, called Operations, are available - for execution just before commit. +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. +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. What is the difference between `AppRsetObject` and `AppObject` ? ---------------------------------------------------------------- - `AppRsetObject` instances are selected on a request and a result - set. `AppObject` instances are directly selected by id. +`AppRsetObject` instances are selected on a request and a result +set. `AppObject` instances are directly selected by id. How to update a database after a schema modification ? ------------------------------------------------------ - It depends on what has been modified in the schema. +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')``. +* Update the permissions and properties of an entity or a relation: + ``sync_schema_props_perms('MyEntityOrRelation')``. - * Add an attribute: ``add_attribute('MyEntityType', 'myattr')``. +* Add an attribute: ``add_attribute('MyEntityType', 'myattr')``. - * Add a relation: ``add_relation_definition('SubjRelation', 'MyRelation', 'ObjRelation')``. +* 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 - ``all-in-one.conf`` file of your instance, define the anonymous user - as follows :: +This allows to bypass authentication for your site. 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) - anonymous-user=anon + # login of the CubicWeb user account to use for anonymous user (if you want to + # allow anonymous) + anonymous-user=anon - # password of the CubicWeb user account matching login - anonymous-password=anon + # 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`. - This could be the admin account (for development - purposes, of course). +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`. +This could be the admin account (for development +purposes, of course). .. note:: While creating a new instance, you can decide to allow access @@ -224,55 +226,57 @@ How to change the instance logo ? ------------------------------------ - There are two ways of changing the logo. +There are two ways of changing the logo. - 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. - By default all instance will look for a ``logo.png`` to be - rendered in the logo section. +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. + By default all instance will look for a ``logo.png`` to be + rendered in the logo section. - .. image:: ../images/lax-book.06-main-template-logo.en.png + .. image:: ../images/lax-book.06-main-template-logo.en.png - 2. In your cube directory, you can specify which file to use for the logo. - This is configurable in ``mycube/data/external_resources``: :: +2. In your cube directory, you can specify which file to use for the logo. + This is configurable in ``mycube/data/external_resources``: :: - LOGO = DATADIR/path/to/mylogo.gif + LOGO = DATADIR/path/to/mylogo.gif - where DATADIR is ``mycube/data``. + where DATADIR is ``mycube/data``. How to configure a LDAP source ? -------------------------------- - Your instance's sources are defined in ``/etc/cubicweb.d/myapp/sources``. - Configuring an LDAP source is about declaring that source in your - instance configuration file such as: :: +Your instance's sources are defined in ``/etc/cubicweb.d/myapp/sources``. +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 + [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. +Any change applied to configuration file requires to restart your +instance. 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) : :: +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 @@ -287,40 +291,43 @@ except NoSelectableObject: continue - Don't forget the 'from __future__ improt with_statement' at the - module top-level. +Don't forget the 'from __future__ import with_statement' at the module +top-level. - This will yield additional WARNINGs, like this: - :: +This will yield additional WARNINGs, like this:: 2009-01-09 16:43:52 - (cubicweb.selectors) WARNING: selector one_line_rset returned 0 for 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:: +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) Can PostgreSQL and CubicWeb authentication work with kerberos ? ---------------------------------------------------------------- - If you have PostgreSQL set up to accept kerberos authentication, you can set - the db-host, db-name and db-user parameters in the `sources` configuration - file while leaving the password blank. It should be enough for your - instance to connect to postgresql with a kerberos ticket. +If you have PostgreSQL set up to accept kerberos authentication, you can set +the db-host, db-name and db-user parameters in the `sources` configuration +file while leaving the password blank. It should be enough for your +instance to connect to postgresql with a kerberos ticket. How to load data from a script ? -------------------------------- - The following script aims at loading data within a script assuming pyro-nsd is - running and your instance is configured with ``pyro-server=yes``, otherwise - you would not be able to use dbapi. :: +The following script aims at loading data within a script assuming pyro-nsd is +running and your instance is configured with ``pyro-server=yes``, otherwise +you would not be able to use dbapi. + +.. sourcecode:: python from cubicweb import dbapi @@ -333,24 +340,30 @@ 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 :: +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] +[XXX check that cw handle users better by mapping Google Accounts to local Euser +entities automatically] How to reset the password for user joe ? ---------------------------------------- - You need to generate a new encrypted password:: +If you want to reset the admin password for ``myinstance``, do:: + + $ cubicweb-ctl reset-admin-pwd myinstance + +You need to generate a new encrypted password:: $ python >>> from cubicweb.server.utils import crypt_password @@ -358,7 +371,7 @@ 'qHO8282QN5Utg' >>> - and paste it in the database:: +and paste it in the database:: $ psql mydb mydb=> update cw_cwuser set cw_upassword='qHO8282QN5Utg' where cw_login='joe'; @@ -369,6 +382,6 @@ You are probably getting errors such as :: - remove {'PR': 'Project', 'C': 'CWUser'} from solutions since your_user has no read access to cost + 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.