diff -r 49075f57cf2c -r aa09e20dd8c0 doc/book/en/annexes/faq.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/annexes/faq.rst Thu May 14 12:48:11 2009 +0200 @@ -0,0 +1,344 @@ +.. -*- coding: utf-8 -*- + +Frequently Asked Questions +========================== + +[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/d791ce17e2716147/eb078f8cfe8426e0 +and +http://groups.google.com/group/google-appengine/browse_frm/thread/f48cf6099973aef5/c28cd6934dd72457 +] + +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] + + `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. + +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. + + When doing development, you need a real language and template + languages are not real languages. + + Using Python enables developing applications for which code is + easier 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 GPL license to prevent me from doing X ? +----------------------------------------------------------- + + GPL means that *if* you redistribute your application, you need to + redistribute it *and* the changes you made *and* the code _linked_ + to it under the GPL licence. + + Publishing a web site has nothing to do with redistributing + source code. A fair amount of companies use modified GPL code + for internal use. And someone could publish a `CubicWeb` component + under a BSD licence for others to plug into a GPL 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 over the past seven years 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. + +<<<<<<< /home/syt/src/fcubicweb/cubicweb_3.2/doc/book/en/annexes/faq.rst +Why is the RQL query language looking similar to X ? +---------------------------------------------------- +======= +Why is the RQL query language looking similar to X ? +----------------------------------------------------- +>>>>>>> /tmp/faq.rst~other.MxOUAP + + 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 has a query language has been in our backlog for years. + + 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. + + 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] + +which ajax library +------------------ +[we use jquery and things on top of that] + + +How to implement security? +-------------------------- + + This is an example of how it works in our framework:: + + class Version(EntityType): + """a version is defining the content of a particular project's + release""" + # definition of attributes is voluntarily missing + permissions = {'read': ('managers', 'users', 'guests',), + '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'),)} + + 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. + :: + + class version_of(RelationType): + """link a version to its project. A version is necessarily linked + to one and only one project. """ + # some lines voluntarily missing + 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'),) } + + You can find additional information in the section :ref:`security`. + + [XXX what does the second example means in addition to the first one?] + + +`Error while publishing rest text ...` +-------------------------------------- + While modifying the description of an entity, you get an error message in + the application `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. + +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. + +How to update a database after a schema modification? +----------------------------------------------------- + + It depends on what has been modified in the schema. + + * Update of an attribute permissions and properties: + ``synchronize_eschema('MyEntity')``. + + * Update of a relation permissions and properties: + ``synchronize_rschema('MyRelation')``. + + * 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 + ``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 + + # 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). + +.. 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 change the application 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 application will look for a ``logo.png`` to be + rendered in the logo section. + + .. 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``: :: + + LOGO = DATADIR/path/to/mylogo.gif + + where DATADIR is ``mycubes/data``. + + +How to configure 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: :: + + [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 + application. + +I get NoSelectableObject exceptions: how do I debug selectors ? +--------------------------------------------------------------- + + You just need to put the appropriate context manager around view/component + selection: :: + + from cubicweb.common.selectors import traced_selection + with traced_selection(): + comp = self.vreg.select_object('contentnavigation', 'wfhistory', + self.req, rset, context='navcontentbottom') + + 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=systemepropertiesform`` + and then set ``ui.date`` and/or ``ui.datetime``. + Then in the view code, use:: + + 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. + + +How to load data from a script? +------------------------------- + + The following script aims at loading data within a script assuming pyro-nsd is + running and your application is configured with ``pyro-server=yes``, otherwise + you would not be able to use dbapi. :: + + from cubicweb import dbapi + + cnx = dbapi.connection(database='instance-id', user='admin', password='admin') + cur = cnx.cursor() + for name in ('Personal', 'Professional', 'Computers'): + cur.execute('INSERT Blog B: B name %s', name) + cnx.commit() + +What is the CubicWeb datatype corresponding to GAE datastore's UserProperty? +---------------------------------------------------------------------------- + + If you take a look at your application 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 :: + + 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] +