# HG changeset patch # User Christophe de Vienne # Date 1420751466 -3600 # Node ID c67bcee932488ff02d8fc97305bee897cb09e60e # Parent 76ab3c71aff2fa8137c79895ca0d4112f6484dbf [doc] Restructure the documentation * Create a new index file * Move the sphinx configuration files do the documentation root * Move book/README to dev/documenting.rst * Move book/mode_plan.py to tools/ * Move book/en/images to images * Move book/en/* to book/ * Move changelogs to changes/* * Adapt the Makefile * Add a title to the javascript api index Related to #4832808 diff -r 76ab3c71aff2 -r c67bcee93248 .hgignore --- a/.hgignore Mon Jul 06 17:39:35 2015 +0200 +++ b/.hgignore Thu Jan 08 22:11:06 2015 +0100 @@ -18,4 +18,7 @@ ^doc/html/ ^doc/doctrees/ ^doc/book/en/devweb/js_api/ +^doc/_build +^doc/js_api/ +data/pgdb/ data.*/pgdb.* diff -r 76ab3c71aff2 -r c67bcee93248 doc/3.14.rst --- a/doc/3.14.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,164 +0,0 @@ -Whats new in CubicWeb 3.14 -========================== - -First notice CW 3.14 depends on yams 0.34 (which is incompatible with prior -cubicweb releases regarding instance re-creation). - -API changes ------------ - -* `Entity.fetch_rql` `restriction` argument has been deprecated and should be - replaced with a call to the new `Entity.fetch_rqlst` method, get the returned - value (a rql `Select` node) and use the RQL syntax tree API to include the - above-mentionned restrictions. - - Backward compat is kept with proper warning. - -* `Entity.fetch_order` and `Entity.fetch_unrelated_order` class methods have been - replaced by `Entity.cw_fetch_order` and `Entity.cw_fetch_unrelated_order` with - a different prototype: - - - instead of taking (attr, var) as two string argument, they now take (select, - attr, var) where select is the rql syntax tree beinx constructed and var the - variable *node*. - - - instead of returning some string to be inserted in the ORDERBY clause, it has - to modify the syntax tree - - Backward compat is kept with proper warning, BESIDE cases below: - - - custom order method return **something else the a variable name with or - without the sorting order** (e.g. cases where you sort on the value of a - registered procedure as it was done in the tracker for instance). In such - case, an error is logged telling that this sorting is ignored until API - upgrade. - - - client code use direct access to one of those methods on an entity (no code - known to do that). - -* `Entity._rest_attr_info` class method has been renamed to - `Entity.cw_rest_attr_info` - - No backward compat yet since this is a protected method an no code is known to - use it outside cubicweb itself. - -* `AnyEntity.linked_to` has been removed as part of a refactoring of this - functionality (link a entity to another one at creation step). It was replaced - by a `EntityFieldsForm.linked_to` property. - - In the same refactoring, `cubicweb.web.formfield.relvoc_linkedto`, - `cubicweb.web.formfield.relvoc_init` and - `cubicweb.web.formfield.relvoc_unrelated` were removed and replaced by - RelationField methods with the same names, that take a form as a parameter. - - **No backward compatibility yet**. It's still time to cry for it. - Cubes known to be affected: tracker, vcsfile, vcreview. - -* `CWPermission` entity type and its associated require_permission relation type - (abstract) and require_group relation definitions have been moved to a new - `localperms` cube. With this have gone some functions from the - `cubicweb.schemas` package as well as some views. This makes cubicweb itself - smaller while you get all the local permissions stuff into a single, - documented, place. - - Backward compat is kept for existing instances, **though you should have - installed the localperms cubes**. A proper error should be displayed when - trying to migrate to 3.14 an instance the use `CWPermission` without the new - cube installed. For new instances / test, you should add a dependancy on the - new cube in cubes using this feature, along with a dependancy on cubicweb >= - 3.14. - -* jQuery has been updated to 1.6.4 and jquery-tablesorter to 2.0.5. No backward - compat issue known. - -* Table views refactoring : new `RsetTableView` and `EntityTableView`, as well as - rewritten an enhanced version of `PyValTableView` on the same bases, with logic - moved to some column renderers and a layout. Those should be well documented - and deprecates former `TableView`, `EntityAttributesTableView` and `CellView`, - which are however kept for backward compat, with some warnings that may not be - very clear unfortunatly (you may see your own table view subclass name here, - which doesn't make the problem that clear). Notice that `_cw.view('table', - rset, *kwargs)` will be routed to the new `RsetTableView` or to the old - `TableView` depending on given extra arguments. See #1986413. - -* `display_name` don't call .lower() anymore. This may leads to changes in your - user interface. Different msgid for upper/lower cases version of entity type - names, as this is the only proper way to handle this with some languages. - -* `IEditControlAdapter` has been deprecated in favor of `EditController` - overloading, which was made easier by adding dedicated selectors called - `match_edited_type` and `match_form_id`. - -* Pre 3.6 API backward compat has been dropped, though *data* migration - compatibility has been kept. You may have to fix errors due to old API usage - for your instance before to be able to run migration, but then you should be - able to upgrade even a pre 3.6 database. - -* Deprecated `cubicweb.web.views.iprogress` in favor of new `iprogress` cube. - -* Deprecated `cubicweb.web.views.flot` in favor of new `jqplot` cube. - - -Unintrusive API changes ------------------------ - -* Refactored properties forms (eg user preferences and site wide properties) as - well as pagination components to ease overridding. - -* New `cubicweb.web.uihelper` module with high-level helpers for uicfg. - -* New `anonymized_request` decorator to temporary run stuff as an anonymous - user, whatever the currently logged in user. - -* New 'verbatimattr' attribute view. - -* New facet and form widget for Integer used to store binary mask. - -* New `js_href` function to generated proper javascript href. - -* `match_kwargs` and `match_form_params` selectors both accept a new - `once_is_enough` argument. - -* `printable_value` is now a method of request, and may be given dict of - formatters to use. - -* `[Rset]TableView` allows to set None in 'headers', meaning the label should be - fetched from the result set as done by default. - -* Field vocabulary computation on entity creation now takes `__linkto` - information into accounet. - -* Started a `cubicweb.pylintext` pylint plugin to help pylint analyzing cubes. - - -RQL ---- - -* Support for HAVING in 'SET' and 'DELETE' queries. - -* new `AT_TZ` function to get back a timestamp at a given time-zone. - -* new `WEEKDAY` date extraction function - - -User interface changes ----------------------- - -* Datafeed source now present an history of the latest import's log, including - global status and debug/info/warning/error messages issued during - imports. Import logs older than a configurable amount of time are automatically - deleted. - -* Breadcrumbs component is properly kept when creating an entity with '__linkto'. - -* users and groups management now really lead to that (i.e. includes *groups* - management). - -* New 'jsonp' controller with 'jsonexport' and 'ejsonexport' views. - - -Configuration ------------- - -* Added option 'resources-concat' to make javascript/css files concatenation - optional. diff -r 76ab3c71aff2 -r c67bcee93248 doc/3.15.rst --- a/doc/3.15.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,96 +0,0 @@ -What's new in CubicWeb 3.15? -============================ - -New functionnalities --------------------- - -* Add Zmq server, based on the cutting edge ZMQ (http://www.zeromq.org/) socket - library. This allows to access distant instance, in a similar way as Pyro. - -* Publish/subscribe mechanism using ZMQ for communication among cubicweb - instances. The new zmq-address-sub and zmq-address-pub configuration variables - define where this communication occurs. As of this release this mechanism is - used for entity cache invalidation. - -* Improved WSGI support. While there is still some caveats, most of the code - which was twisted only is now generic and allows related functionalities to work - with a WSGI front-end. - -* Full undo/transaction support : undo of modification has eventually been - implemented, and the configuration simplified (basically you activate it or not - on an instance basis). - -* Controlling HTTP status code used is not much more easier : - - - `WebRequest` now has a `status_out` attribut to control the response status ; - - - most web-side exceptions take an optional ``status`` argument. - -API changes ------------ - -* The base registry implementation has been moved to a new - `logilab.common.registry` module (see #1916014). This includes code from : - - * `cubicweb.vreg` (the whole things that was in there) - * `cw.appobject` (base selectors and all). - - In the process, some renaming was done: - - * the top level registry is now `RegistryStore` (was `VRegistry`), but that - should not impact cubicweb client code ; - - * former selectors functions are now known as "predicate", though you still use - predicates to build an object'selector ; - - * for consistency, the `objectify_selector` decoraror has hence be renamed to - `objectify_predicate` ; - - * on the CubicWeb side, the `selectors` module has been renamed to - `predicates`. - - Debugging refactoring dropped the more need for the `lltrace` decorator. There - should be full backward compat with proper deprecation warnings. Notice the - `yes` predicate and `objectify_predicate` decorator, as well as the - `traced_selection` function should now be imported from the - `logilab.common.registry` module. - -* All login forms are now submitted to /login. Redirection to requested - page is now handled by the login controller (it was previously handle by the - session manager). - -* `Publisher.publish` has been renamed to `Publisher.handle_request`. This - method now contains generic version of logic previously handled by - Twisted. `Controller.publish` is **not** affected. - -Unintrusive API changes ------------------------ - -* New 'ldapfeed' source type, designed to replace 'ldapuser' source with - data-feed (i.e. copy based) source ideas. - -* New 'zmqrql' source type, similar to 'pyrorql' but using ømq instead of Pyro. - -* A new registry called `services` has appeared, where you can register - server-side `cubicweb.server.Service` child classes. Their `call` method can be - invoked from a web-side AppObject instance using new `self._cw.call_service` - method or a server-side one using `self.session.call_service`. This is a new - way to call server-side methods, much cleaner than monkey patching the - Repository class, which becomes a deprecated way to perform similar tasks. - -* a new `ajax-func` registry now hosts all remote functions (i.e. functions - callable through the `asyncRemoteExec` JS api). A convenience `ajaxfunc` - decorator will let you expose your python function easily without all the - appobject standard boilerplate. Backward compatibility is preserved. - -* the 'json' controller is now deprecated in favor of the 'ajax' one. - -* `WebRequest.build_url` can now take a __secure__ argument. When True cubicweb - try to generate an https url. - - -User interface changes ----------------------- - -A new 'undohistory' view expose the undoable transactions and give access to undo -some of them. diff -r 76ab3c71aff2 -r c67bcee93248 doc/3.16.rst --- a/doc/3.16.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,97 +0,0 @@ -What's new in CubicWeb 3.16? -============================ - -New functionalities --------------------- - -* Add a new dataimport store (`SQLGenObjectStore`). This store enables a fast - import of data (entity creation, link creation) in CubicWeb, by directly - flushing information in SQL. This may only be used with PostgreSQL, as it - requires the 'COPY FROM' command. - - -API changes ------------ - -* Orm: `set_attributes` and `set_relations` are unified (and - deprecated) in favor of `cw_set` that works in all cases. - -* db-api/configuration: all the external repository connection information is - now in an URL (see `#2521848 `_), - allowing to drop specific options of pyro nameserver host, group, etc and fix - broken `ZMQ `_ source. Configuration related changes: - - * Dropped 'pyro-ns-host', 'pyro-instance-id', 'pyro-ns-group' from the client side - configuration, in favor of 'repository-uri'. **NO MIGRATION IS DONE**, - supposing there is no web-only configuration in the wild. - - * Stop discovering the connection method through `repo_method` class attribute - of the configuration, varying according to the configuration class. This is - a first step on the way to a simpler configuration handling. - - DB-API related changes: - - * Stop indicating the connection method using `ConnectionProperties`. - - * Drop `_cnxtype` attribute from `Connection` and `cnxtype` from - `Session`. The former is replaced by a `is_repo_in_memory` property - and the later is totaly useless. - - * Turn `repo_connect` into `_repo_connect` to mark it as a private function. - - * Deprecate `in_memory_cnx` which becomes useless, use `_repo_connect` instead - if necessary. - -* the "tcp://" uri scheme used for `ZMQ `_ - communications (in a way reminiscent of Pyro) is now named - "zmqpickle-tcp://", so as to make room for future zmq-based lightweight - communications (without python objects pickling). - -* Request.base_url gets a `secure=True` optional parameter that yields - an https url if possible, allowing hook-generated content to send - secure urls (e.g. when sending mail notifications) - -* Dataimport ucsvreader gets a new boolean `ignore_errors` - parameter. - - -Unintrusive API changes ------------------------ - -* Drop of `cubicweb.web.uicfg.AutoformSectionRelationTags.bw_tag_map`, - deprecated since 3.6. - - -User interface changes ----------------------- - -* The RQL search bar has now some auto-completion support. It means - relation types or entity types can be suggested while typing. It is - an awesome improvement over the current behaviour ! - -* The `action box` associated with `table` views (from `tableview.py`) - has been transformed into a nice-looking series of small tabs; it - means that the possible actions are immediately visible and need not - be discovered by clicking on an almost invisible icon on the upper - right. - -* The `uicfg` module has moved to web/views/ and ui configuration - objects are now selectable. This will reduce the amount of - subclassing and whole methods replacement usually needed to - customize the ui behaviour in many cases. - -* Remove changelog view, as neither cubicweb nor known - cubes/applications were properly feeding related files. - - -Other changes -------------- - -* 'pyrorql' sources will be automatically updated to use an URL to locate the source - rather than configuration option. 'zmqrql' sources were broken before this change, - so no upgrade is needed... - -* Debugging filters for Hooks and Operations have been added. - -* Some cubicweb-ctl commands used to show the output of `msgcat` and - `msgfmt`; they don't anymore. diff -r 76ab3c71aff2 -r c67bcee93248 doc/3.17.rst --- a/doc/3.17.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,60 +0,0 @@ -What's new in CubicWeb 3.17? -============================ - -New functionalities --------------------- - -* add a command to compare db schema and file system schema - (see `#464991 `_) - -* Add CubicWebRequestBase.content with the content of the HTTP request (see #2742453) - (see `#2742453 `_) - -* Add directive bookmark to ReST rendering - (see `#2545595 `_) - -* Allow user defined final type - (see `#124342 `_) - - -API changes ------------ - -* drop typed_eid() in favour of int() (see `#2742462 `_) - -* The SIOC views and adapters have been removed from CubicWeb and moved to the - `sioc` cube. - -* The web page embedding views and adapters have been removed from CubicWeb and - moved to the `embed` cube. - -* The email sending views and controllers have been removed from CubicWeb and - moved to the `massmailing` cube. - -* ``RenderAndSendNotificationView`` is deprecated in favor of - ``ActualNotificationOp`` the new operation use the more efficient *data* - idiom. - -* Looping task can now have a interval <= ``0``. Negative interval disable the - looping task entirely. - -* We now serve html instead of xhtml. - (see `#2065651 `_) - - -Deprecation ---------------------- - -* ``ldapuser`` have been deprecated. It'll be fully dropped in the next - version. If you are still using ldapuser switch to ``ldapfeed`` **NOW**! - -* ``hijack_user`` have been deprecated. It will be dropped soon. - -Deprecated Code Drops ----------------------- - -* The progress views and adapters have been removed from CubicWeb. These - classes were deprecated since 3.14.0. They are still available in the - `iprogress` cube. - -* API deprecated since 3.7 have been dropped. diff -r 76ab3c71aff2 -r c67bcee93248 doc/3.18.rst --- a/doc/3.18.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,101 +0,0 @@ -What's new in CubicWeb 3.18? -============================ - -The migration script does not handle sqlite nor mysql instances. - - -New functionalities --------------------- - -* add a security debugging tool - (see `#2920304 `_) - -* introduce an `add` permission on attributes, to be interpreted at - entity creation time only and allow the implementation of complex - `update` rules that don't block entity creation (before that the - `update` attribute permission was interpreted at entity creation and - update time) - -* the primary view display controller (uicfg) now has a - `set_fields_order` method similar to the one available for forms - -* new method `ResultSet.one(col=0)` to retrive a single entity and enforce the - result has only one row (see `#3352314 https://www.cubicweb.org/ticket/3352314`_) - -* new method `RequestSessionBase.find` to look for entities - (see `#3361290 https://www.cubicweb.org/ticket/3361290`_) - -* the embedded jQuery copy has been updated to version 1.10.2, and jQuery UI to - version 1.10.3. - -* initial support for wsgi for the debug mode, available through the new - ``wsgi`` cubicweb-ctl command, which can use either python's builtin - wsgi server or the werkzeug module if present. - -* a ``rql-table`` directive is now available in ReST fields - -* cubicweb-ctl upgrade can now generate the static data resource directory - directly, without a manual call to gen-static-datadir. - -API changes ------------ - -* not really an API change, but the entity permission checks are now - systematically deferred to an operation, instead of a) trying in a - hook and b) if it failed, retrying later in an operation - -* The default value storage for attributes is no longer String, but - Bytes. This opens the road to storing arbitrary python objects, e.g. - numpy arrays, and fixes a bug where default values whose truth value - was False were not properly migrated. - -* `symmetric` relations are no more handled by an rql rewrite but are - now handled with hooks (from the `activeintegrity` category); this - may have some consequences for applications that do low-level database - manipulations or at times disable (some) hooks. - -* `unique together` constraints (multi-columns unicity constraints) - get a `name` attribute that maps the CubicWeb contraint entities to - corresponding backend index. - -* BreadCrumbEntityVComponent's open_breadcrumbs method now includes - the first breadcrumbs separator - -* entities can be compared for equality and hashed - -* the ``on_fire_transition`` predicate accepts a sequence of possible - transition names - -* the GROUP_CONCAT rql aggregate function no longer repeats duplicate - values, on the sqlite and postgresql backends - -Deprecation ---------------------- - -* ``pyrorql`` sources have been deprecated. Multisource will be fully dropped - in the next version. If you are still using pyrorql, switch to ``datafeed`` - **NOW**! - -* the old multi-source system - -* `find_one_entity` and `find_entities` in favor of `find` - (see `#3361290 https://www.cubicweb.org/ticket/3361290`_) - -* the `TmpFileViewMixin` and `TmpPngView` classes (see `#3400448 - https://www.cubicweb.org/ticket/3400448`_) - -Deprecated Code Drops ----------------------- - -* ``ldapuser`` have been dropped; use ``ldapfeed`` now - (see `#2936496 `_) - -* action ``GotRhythm`` was removed, make sure you do not - import it in your cubes (even to unregister it) - (see `#3093362 `_) - -* all 3.8 backward compat is gone - -* all 3.9 backward compat (including the javascript side) is gone - -* the ``twisted`` (web-only) instance type has been removed diff -r 76ab3c71aff2 -r c67bcee93248 doc/3.19.rst --- a/doc/3.19.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,180 +0,0 @@ -What's new in CubicWeb 3.19? -============================ - -New functionalities --------------------- - -* implement Cross Origin Resource Sharing (CORS) - (see `#2491768 `_) - -* system_source.create_eid can get a range of IDs, to reduce overhead of batch - entity creation - -Behaviour Changes ------------------ - -* The anonymous property of Session and Connection are now computed from the - related user login. If it matches the ``anonymous-user`` in the config the - connection is anonymous. Beware that the ``anonymous-user`` config is web - specific. Therefore, no session may be anonymous in a repository only setup. - - -New Repository Access API -------------------------- - -Connection replaces Session -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A new explicit Connection object replaces Session as the main repository entry -point. Connection holds all the necessary methods to be used server-side -(``execute``, ``commit``, ``rollback``, ``call_service``, ``entity_from_eid``, -etc...). One obtains a new Connection object using ``session.new_cnx()``. -Connection objects need to have an explicit begin and end. Use them as a context -manager to never miss an end:: - - with session.new_cnx() as cnx: - cnx.execute('INSERT Elephant E, E name "Babar"') - cnx.commit() - cnx.execute('INSERT Elephant E, E name "Celeste"') - cnx.commit() - # Once you get out of the "with" clause, the connection is closed. - -Using the same Connection object in multiple threads will give you access to the -same Transaction. However, Connection objects are not thread safe (hence at your -own risks). - -``repository.internal_session`` is deprecated in favor of -``repository.internal_cnx``. Note that internal connections are now `safe` by default, -i.e. the integrity hooks are enabled. - -Backward compatibility is preserved on Session. - - -dbapi vs repoapi -~~~~~~~~~~~~~~~~ - -A new API has been introduced to replace the dbapi. It is called `repoapi`. - -There are three relevant functions for now: - -* ``repoapi.get_repository`` returns a Repository object either from an - URI when used as ``repoapi.get_repository(uri)`` or from a config - when used as ``repoapi.get_repository(config=config)``. - -* ``repoapi.connect(repo, login, **credentials)`` returns a ClientConnection - associated with the user identified by the credentials. The - ClientConnection is associated with its own Session that is closed - when the ClientConnection is closed. A ClientConnection is a - Connection-like object to be used client side. - -* ``repoapi.anonymous_cnx(repo)`` returns a ClientConnection associated - with the anonymous user if described in the config. - - -repoapi.ClientConnection replace dbapi.Connection and company -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -On the client/web side, the Request is now using a ``repoapi.ClientConnection`` -instead of a ``dbapi.connection``. The ``ClientConnection`` has multiple backward -compatible methods to make it look like a ``dbapi.Cursor`` and ``dbapi.Connection``. - -Session used on the Web side are now the same than the one used Server side. -Some backward compatibility methods have been installed on the server side Session -to ease the transition. - -The authentication stack has been altered to use the ``repoapi`` instead of -the ``dbapi``. Cubes adding new element to this stack are likely to break. - -Session data can be accessed using the cnx.data dictionary, while -transaction data is available through cnx.transaction_data. These -replace the [gs]et_shared_data methods with optional txid kwarg. - -New API in tests -~~~~~~~~~~~~~~~~ - -All current methods and attributes used to access the repo on ``CubicWebTC`` are -deprecated. You may now use a ``RepoAccess`` object. A ``RepoAccess`` object is -linked to a new ``Session`` for a specified user. It is able to create -``Connection``, ``ClientConnection`` and web side requests linked to this -session:: - - access = self.new_access('babar') # create a new RepoAccess for user babar - with access.repo_cnx() as cnx: - # some work with server side cnx - cnx.execute(...) - cnx.commit() - cnx.execute(...) - cnx.commit() - - with access.client_cnx() as cnx: - # some work with client side cnx - cnx.execute(...) - cnx.commit() - - with access.web_request(elephant='babar') as req: - # some work with client side cnx - elephant_name = req.form['elephant'] - req.execute(...) - req.cnx.commit() - -By default ``testcase.admin_access`` contains a ``RepoAccess`` object for the -default admin session. - - -API changes ------------ - -* ``RepositorySessionManager.postlogin`` is now called with two arguments, - request and session. And this now happens before the session is linked to the - request. - -* ``SessionManager`` and ``AuthenticationManager`` now take a repo object at - initialization time instead of a vreg. - -* The ``async`` argument of ``_cw.call_service`` has been dropped. All calls are - now synchronous. The zmq notification bus looks like a good replacement for - most async use cases. - -* ``repo.stats()`` is now deprecated. The same information is available through - a service (``_cw.call_service('repo_stats')``). - -* ``repo.gc_stats()`` is now deprecated. The same information is available through - a service (``_cw.call_service('repo_gc_stats')``). - -* ``repo.register_user()`` is now deprecated. The functionality is now - available through a service (``_cw.call_service('register_user')``). - -* ``request.set_session`` no longer takes an optional ``user`` argument. - -* CubicwebTC does not have repo and cnx as class attributes anymore. They are - standard instance attributes. ``set_cnx`` and ``_init_repo`` class methods - become instance methods. - -* ``set_cnxset`` and ``free_cnxset`` are deprecated. cnxset are now - automatically managed. - -* The implementation of cascading deletion when deleting `composite` - entities has changed. There comes a semantic change: merely deleting - a composite relation does not entail any more the deletion of the - component side of the relation. - -* ``_cw.user_callback`` and ``_cw.user_rql_callback`` are deprecated. Users - are encouraged to write an actual controller (e.g. using ``ajaxfunc``) - instead of storing a closure in the session data. - -* A new ``entity.cw_linkable_rql`` method provides the rql to fetch all entities - that are already or may be related to the current entity using the given - relation. - - -Deprecated Code Drops ----------------------- - -* session.hijack_user mechanism has been dropped. - -* EtypeRestrictionComponent has been removed, its functionality has been - replaced by facets a while ago. - -* the old multi-source support has been removed. Only copy-based sources - remain, such as datafeed or ldapfeed. - diff -r 76ab3c71aff2 -r c67bcee93248 doc/3.20.rst --- a/doc/3.20.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,78 +0,0 @@ -What's new in CubicWeb 3.20 -=========================== - -New features ------------- - -* virtual relations: a new ComputedRelation class can be used in - schema.py; its `rule` attribute is an RQL snippet that defines the new - relation. - -* computed attributes: an attribute can now be defined with a `formula` - argument (also an RQL snippet); it will be read-only, and updated - automatically. - - Both of these features are described in `CWEP-002`_, and the updated - "Data model" chapter of the CubicWeb book. - -* cubicweb-ctl plugins can use the ``cubicweb.utils.admincnx`` function - to get a Connection object from an instance name. - -* new 'tornado' wsgi backend - -* session cookies have the HttpOnly flag, so they're no longer exposed to - javascript - -* rich text fields can be formatted as markdown - -* the edit controller detects concurrent editions, and raises a ValidationError - if an entity was modified between form generation and submission - -* cubicweb can use a postgresql "schema" (namespace) for its tables - -* "cubicweb-ctl configure" can be used to set values of the admin user - credentials in the sources configuration file - -* in debug mode, setting the _cwtracehtml parameter on a request allows tracing - where each bit of output is produced - -.. _CWEP-002: http://hg.logilab.org/review/cwep/file/tip/CWEP-002.rst - - -API Changes ------------ - -* ``ucsvreader()`` and ``ucsvreader_pb()`` from the ``dataimport`` module have - 2 new keyword arguments ``delimiter`` and ``quotechar`` to replace the - ``separator`` and ``quote`` arguments respectively. This makes the API match - that of Python's ``csv.reader()``. The old arguments are still supported - though deprecated. - -* the migration environment's ``remove_cube`` function is now called ``drop_cube``. - -* cubicweb.old.css is now cubicweb.css. The previous "new" - cubicweb.css, along with its cubicweb.reset.css companion, have been - removed. - -* the jquery-treeview plugin was updated to its latest version - - -Deprecated Code Drops ----------------------- - -* most of 3.10 and 3.11 backward compat is gone; this includes: - - CtxComponent.box_action() and CtxComponent.build_link() - - cubicweb.devtools.htmlparser.XMLDemotingValidator - - various methods and properties on Entities, replaced by cw_edited and cw_attr_cache - - 'commit_event' method on hooks, replaced by 'postcommit_event' - - server.hook.set_operation(), replaced by Operation.get_instance(...).add_data() - - View.div_id(), View.div_class() and View.create_url() - - `*VComponent` classes - - in forms, Field.value() and Field.help() must take the form and the field itself as arguments - - form.render() must get `w` as a named argument, and renderer.render() must take `w` as first argument - - in breadcrumbs, the optional `recurs` argument must be a set, not False - - cubicweb.web.views.idownloadable.{download_box,IDownloadableLineView} - - primary views no longer have `render_entity_summary` and `summary` methods - - WFHistoryVComponent's `cell_call` method is replaced by `render_body` - - cubicweb.dataimport.ObjectStore.add(), replaced by create_entity - - ManageView.{folders,display_folders} diff -r 76ab3c71aff2 -r c67bcee93248 doc/Makefile --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Makefile Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,88 @@ +SRC=. + +# You can set these sphinx variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +#BUILDDIR = build +BUILDDIR = _build +CWDIR = .. +JSDIR = ${CWDIR}/web/data +JSTORST = tools/pyjsrest.py +BUILDJS = js_api + +# Internal variables for sphinx +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d ${BUILDDIR}/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + + + +.PHONY: help clean html web pickle htmlhelp latex changes linkcheck + +help: + @echo "Please use \`make ' where is one of" + @echo " all to make standalone HTML files, developer manual and API doc" + @echo " html to make standalone HTML files" + @echo "--- " + @echo " pickle to make pickle files (usable by e.g. sphinx-web)" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview over all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + +clean: + rm -f *.html + -rm -rf ${BUILDDIR}/html ${BUILDDIR}/doctrees + -rm -rf ${BUILDJS} + +all: html + +# run sphinx ### +html: js + mkdir -p ${BUILDDIR}/html ${BUILDDIR}/doctrees + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${BUILDDIR}/html + @echo + @echo "Build finished. The HTML pages are in ${BUILDDIR}/html." + +js: + mkdir -p ${BUILDJS} + $(JSTORST) -p ${JSDIR} -o ${BUILDJS} + +pickle: + mkdir -p ${BUILDDIR}/pickle ${BUILDDIR}/doctrees + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) ${BUILDDIR}/pickle + @echo + @echo "Build finished; now you can process the pickle files or run" + @echo " sphinx-web ${BUILDDIR}/pickle" + @echo "to start the sphinx-web server." + +web: pickle + +htmlhelp: + mkdir -p ${BUILDDIR}/htmlhelp ${BUILDDIR}/doctrees + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) ${BUILDDIR}/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in ${BUILDDIR}/htmlhelp." + +latex: + mkdir -p ${BUILDDIR}/latex ${BUILDDIR}/doctrees + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) ${BUILDDIR}/latex + @echo + @echo "Build finished; the LaTeX files are in ${BUILDDIR}/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + mkdir -p ${BUILDDIR}/changes ${BUILDDIR}/doctrees + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) ${BUILDDIR}/changes + @echo + @echo "The overview file is in ${BUILDDIR}/changes." + +linkcheck: + mkdir -p ${BUILDDIR}/linkcheck ${BUILDDIR}/doctrees + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) ${BUILDDIR}/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in ${BUILDDIR}/linkcheck/output.txt." diff -r 76ab3c71aff2 -r c67bcee93248 doc/_static/cubicweb.png Binary file doc/_static/cubicweb.png has changed diff -r 76ab3c71aff2 -r c67bcee93248 doc/_static/logilab.png Binary file doc/_static/logilab.png has changed diff -r 76ab3c71aff2 -r c67bcee93248 doc/_static/sphinx-default.css --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/_static/sphinx-default.css Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,861 @@ +/** + * Sphinx Doc Design + */ + +html, body { + background: white; +} + +body { + font-family: Verdana, sans-serif; + font-size: 100%; + background-color: white; + color: black; + margin: 0; + padding: 0; +} + +/* :::: LAYOUT :::: */ + +div.logilablogo { + padding: 10px 10px 10px 10px; + height:75; +} + + +div.document { + background-color: white; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: white; + padding: 0 20px 30px 20px; + border-left:solid; + border-left-color:#e2e2e2; + border-left-width:thin; +} + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.clearer { + clear: both; +} + +div.footer { + color: #ff4500; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #ff4500; + text-decoration: underline; +} + +div.related { + background-color: #ff7700; + color: white; + width: 100%; + height: 30px; + line-height: 30px; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +div.related a { + color: white; + font-weight:bold; +} + +/* ::: TOC :::: */ + +div.sphinxsidebar { + border-style:solid; + border-color: white; +/* background-color:#e2e2e2;*/ + padding-bottom:5px; +} + +div.sphinxsidebar h3 { + font-family: Verdana, sans-serif; + color: black; + font-size: 1.2em; + font-weight: normal; + margin: 0; + padding: 0; + font-weight:bold; + font-style:italic; +} + +div.sphinxsidebar h4 { + font-family: Verdana, sans-serif; + color: black; + font-size: 1.1em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; + font-weight:bold; + font-style:italic; +} + +div.sphinxsidebar p { + color: black; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + list-style: none; + color: black; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar a { + color: black; + text-decoration: none; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #e2e2e2; + font-family: sans-serif; + font-size: 1em; + padding-bottom: 5px; +} + +/* :::: MODULE CLOUD :::: */ +div.modulecloud { + margin: -5px 10px 5px 10px; + padding: 10px; + line-height: 160%; + border: 1px solid #cbe7e5; + background-color: #f2fbfd; +} + +div.modulecloud a { + padding: 0 5px 0 5px; +} + +/* :::: SEARCH :::: */ +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* :::: COMMON FORM STYLES :::: */ + +div.actions { + padding: 5px 10px 5px 10px; + border-top: 1px solid #cbe7e5; + border-bottom: 1px solid #cbe7e5; + background-color: #e0f6f4; +} + +form dl { + color: #333; +} + +form dt { + clear: both; + float: left; + min-width: 110px; + margin-right: 10px; + padding-top: 2px; +} + +input#homepage { + display: none; +} + +div.error { + margin: 5px 20px 0 0; + padding: 5px; + border: 1px solid #d00; + font-weight: bold; +} + +/* :::: INLINE COMMENTS :::: */ + +div.inlinecomments { + position: absolute; + right: 20px; +} + +div.inlinecomments a.bubble { + display: block; + float: right; + background-image: url(style/comment.png); + background-repeat: no-repeat; + width: 25px; + height: 25px; + text-align: center; + padding-top: 3px; + font-size: 0.9em; + line-height: 14px; + font-weight: bold; + color: black; +} + +div.inlinecomments a.bubble span { + display: none; +} + +div.inlinecomments a.emptybubble { + background-image: url(style/nocomment.png); +} + +div.inlinecomments a.bubble:hover { + background-image: url(style/hovercomment.png); + text-decoration: none; + color: #3ca0a4; +} + +div.inlinecomments div.comments { + float: right; + margin: 25px 5px 0 0; + max-width: 50em; + min-width: 30em; + border: 1px solid #2eabb0; + background-color: #f2fbfd; + z-index: 150; +} + +div#comments { + border: 1px solid #2eabb0; + margin-top: 20px; +} + +div#comments div.nocomments { + padding: 10px; + font-weight: bold; +} + +div.inlinecomments div.comments h3, +div#comments h3 { + margin: 0; + padding: 0; + background-color: #2eabb0; + color: white; + border: none; + padding: 3px; +} + +div.inlinecomments div.comments div.actions { + padding: 4px; + margin: 0; + border-top: none; +} + +div#comments div.comment { + margin: 10px; + border: 1px solid #2eabb0; +} + +div.inlinecomments div.comment h4, +div.commentwindow div.comment h4, +div#comments div.comment h4 { + margin: 10px 0 0 0; + background-color: #2eabb0; + color: white; + border: none; + padding: 1px 4px 1px 4px; +} + +div#comments div.comment h4 { + margin: 0; +} + +div#comments div.comment h4 a { + color: #d5f4f4; +} + +div.inlinecomments div.comment div.text, +div.commentwindow div.comment div.text, +div#comments div.comment div.text { + margin: -5px 0 -5px 0; + padding: 0 10px 0 10px; +} + +div.inlinecomments div.comment div.meta, +div.commentwindow div.comment div.meta, +div#comments div.comment div.meta { + text-align: right; + padding: 2px 10px 2px 0; + font-size: 95%; + color: #538893; + border-top: 1px solid #cbe7e5; + background-color: #e0f6f4; +} + +div.commentwindow { + position: absolute; + width: 500px; + border: 1px solid #cbe7e5; + background-color: #f2fbfd; + display: none; + z-index: 130; +} + +div.commentwindow h3 { + margin: 0; + background-color: #2eabb0; + color: white; + border: none; + padding: 5px; + font-size: 1.5em; + cursor: pointer; +} + +div.commentwindow div.actions { + margin: 10px -10px 0 -10px; + padding: 4px 10px 4px 10px; + color: #538893; +} + +div.commentwindow div.actions input { + border: 1px solid #2eabb0; + background-color: white; + color: #135355; + cursor: pointer; +} + +div.commentwindow div.form { + padding: 0 10px 0 10px; +} + +div.commentwindow div.form input, +div.commentwindow div.form textarea { + border: 1px solid #3c9ea2; + background-color: white; + color: black; +} + +div.commentwindow div.error { + margin: 10px 5px 10px 5px; + background-color: #fbe5dc; + display: none; +} + +div.commentwindow div.form textarea { + width: 99%; +} + +div.commentwindow div.preview { + margin: 10px 0 10px 0; + background-color: #70d0d4; + padding: 0 1px 1px 25px; +} + +div.commentwindow div.preview h4 { + margin: 0 0 -5px -20px; + padding: 4px 0 0 4px; + color: white; + font-size: 1.3em; +} + +div.commentwindow div.preview div.comment { + background-color: #f2fbfd; +} + +div.commentwindow div.preview div.comment h4 { + margin: 10px 0 0 0!important; + padding: 1px 4px 1px 4px!important; + font-size: 1.2em; +} + +/* :::: SUGGEST CHANGES :::: */ +div#suggest-changes-box input, div#suggest-changes-box textarea { + border: 1px solid #ccc; + background-color: white; + color: black; +} + +div#suggest-changes-box textarea { + width: 99%; + height: 400px; +} + + +/* :::: PREVIEW :::: */ +div.preview { + background-image: url(style/preview.png); + padding: 0 20px 20px 20px; + margin-bottom: 30px; +} + + +/* :::: INDEX PAGE :::: */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* :::: INDEX STYLES :::: */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +form.pfform { + margin: 10px 0 20px 0; +} + +/* :::: GLOBAL STYLES :::: */ + +.docwarning { + background-color: #ffe4e4; + padding: 10px; + margin: 0 -20px 0 -20px; + border-bottom: 1px solid #f66; +} + +p.subhead { + font-weight: bold; + margin-top: 20px; +} + +a { + color: orangered; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Verdana', sans-serif; + background-color: white; + font-weight: bold; + color: black; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 10pt; font-size: 150%; } +div.body h2 { font-size: 120%; } +div.body h3 { font-size: 100%; } +div.body h4 { font-size: 80%; } +div.body h5 { font-size: 600%; } +div.body h6 { font-size: 40%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +ul.fakelist { + list-style: none; + margin: 10px 0 10px 20px; + padding: 0; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +/* "Footnotes" heading */ +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* "Topics" */ + +div.topic { + background-color: #eee; + border: 1px solid #ccc; + padding: 0 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* Admonitions */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +div.admonition p { + display: inline; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +table.docutils { + border: 0; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 0; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +dl { + margin-bottom: 15px; + clear: both; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.refcount { + color: #060; +} + +dt:target, +.highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +th { + text-align: left; + padding-right: 5px; +} + +pre { + padding: 5px; + background-color: #efc; + color: #333; + border: 1px solid #ac9; + border-left: none; + border-right: none; + overflow: auto; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +.footnote:target { background-color: #ffa } + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +form.comment { + margin: 0; + padding: 10px 30px 10px 30px; + background-color: #eee; +} + +form.comment h3 { + background-color: #326591; + color: white; + margin: -10px -30px 10px -30px; + padding: 5px; + font-size: 1.4em; +} + +form.comment input, +form.comment textarea { + border: 1px solid #ccc; + padding: 2px; + font-family: sans-serif; + font-size: 100%; +} + +form.comment input[type="text"] { + width: 240px; +} + +form.comment textarea { + width: 100%; + height: 200px; + margin-bottom: 10px; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +/* :::: PRINT :::: */ +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0; + width : 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + div#comments div.new-comment-box, + #top-link { + display: none; + } +} diff -r 76ab3c71aff2 -r c67bcee93248 doc/_templates/layout.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/_templates/layout.html Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,196 @@ +{%- block doctype -%} + +{%- endblock %} +{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %} +{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %} +{%- macro relbar() %} +
+

Navigation

+
    + {%- for rellink in rellinks %} +
  • + {{ rellink[3] }} + {%- if not loop.first %}{{ reldelim2 }}{% endif %}
    • + {%- endfor %} + {%- block rootrellink %} +
  • {{ shorttitle }}{{ reldelim1 }}
    • + {%- endblock %} + {%- for parent in parents %} +
  • {{ parent.title }}{{ reldelim1 }}
    • + {%- endfor %} + {%- block relbaritems %}{% endblock %} +
+
+{%- endmacro %} +{%- macro sidebar() %} + {%- if builder != 'htmlhelp' %} +
+
+ {%- block sidebarlogo %} + {%- if logo %} + + {%- endif %} + {%- endblock %} + {%- block sidebartoc %} + {%- if display_toc %} +

Table Of Contents

+ {{ toc }} + {%- endif %} + {%- endblock %} + {%- block sidebarrel %} + {%- if prev %} +

Previous topic

+

{{ prev.title }}

+ {%- endif %} + {%- if next %} +

Next topic

+

{{ next.title }}

+ {%- endif %} + {%- endblock %} + {%- if sourcename %} + + {%- endif %} + {%- if customsidebar %} + {{ rendertemplate(customsidebar) }} + {%- endif %} + {%- block sidebarsearch %} + {%- if pagename != "search" %} +

{{ builder == 'web' and 'Keyword' or 'Quick' }} search

+
+ + + +
+ {%- if builder == 'web' %} +

Enter a module, class or function name.

+ {%- endif %} + {%- endif %} + {%- endblock %} +
+
+ {%- endif %} +{%- endmacro -%} + + + + + {%- if builder != 'htmlhelp' %} + {%- set titlesuffix = " — " + docstitle %} + {%- endif %} + {{ title|striptags }}{{ titlesuffix }} + {%- if builder == 'web' %} + + {%- for link, type, title in page_links %} + + {%- endfor %} + {%- else %} + + + {%- endif %} + {%- if builder != 'htmlhelp' %} + + + + + + {%- if use_opensearch %} + + {%- endif %} + {%- if favicon %} + + {%- endif %} + {%- endif %} +{%- block rellinks %} + {%- if hasdoc('about') %} + + {%- endif %} + + + + {%- if hasdoc('copyright') %} + + {%- endif %} + + {%- if parents %} + + {%- endif %} + {%- if next %} + + {%- endif %} + {%- if prev %} + + {%- endif %} +{%- endblock %} +{%- block extrahead %}{% endblock %} + + + +{% block logilablogo %} + +{% endblock %} + +{%- block relbar1 %}{{ relbar() }}{% endblock %} + +{%- block sidebar1 %}{# possible location for sidebar #}{% endblock %} + +{%- block document %} +
+
+ {%- if builder != 'htmlhelp' %} +
+ {%- endif %} +
+ {% block body %}{% endblock %} +
+ {%- if builder != 'htmlhelp' %} +
+ {%- endif %} +
+{%- endblock %} + +{%- block sidebar2 %}{{ sidebar() }}{% endblock %} +
+
+ +{%- block relbar2 %}{{ relbar() }}{% endblock %} + +{%- block footer %} +
+ {%- if hasdoc('copyright') %} + © Copyright {{ copyright }}. + {%- else %} + © Copyright {{ copyright }}. + {%- endif %} + {%- if last_updated %} + Last updated on {{ last_updated }}. + {%- endif %} + {%- if show_sphinx %} + Created using Sphinx. + {%- endif %} +
+{%- endblock %} + + diff -r 76ab3c71aff2 -r c67bcee93248 doc/_themes/cubicweb/layout.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/_themes/cubicweb/layout.html Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,61 @@ +{% extends "basic/layout.html" %} + +{%- block extrahead %} + +{%- if theme_favicon %} + +{%- endif %} + +{%- if theme_canonical_url %} + +{%- endif %} +{% endblock %} + +{% block header %} + +{% if theme_in_progress|tobool %} + Documentation in progress +{% endif %} + +{% if theme_outdated|tobool %} + +{% endif %} + +
+ {%- if theme_logo %} + {% set img, ext = theme_logo.split('.', -1) %} +
+ + + +
+ {%- endif %} +
+{% endblock %} + +{%- macro relbar() %} +
+

{{ _('Navigation') }}

+
    + {%- for rellink in rellinks %} +
  • + {{ rellink[3] }} + {%- if not loop.first %}{{ reldelim2 }}{% endif %} +
    • + {%- endfor %} + {%- block rootrellink %} +
  • {{ docstitle|e }}{{ reldelim1 }}
    • + {%- endblock %} + {%- for parent in parents %} +
  • {{ parent.title }}{{ reldelim1 }}
    • + {%- endfor %} + {%- block relbaritems %} {% endblock %} +
+
+{%- endmacro %} + +{%- block sidebarlogo %}{%- endblock %} +{%- block sidebarsourcelink %}{%- endblock %} diff -r 76ab3c71aff2 -r c67bcee93248 doc/_themes/cubicweb/static/cubicweb.css_t --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/_themes/cubicweb/static/cubicweb.css_t Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,33 @@ +/* + * cubicweb.css_t + * ~~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- cubicweb theme. + * + * :copyright: Copyright 2014 by the Cubicweb team, see AUTHORS. + * :license: LGPL, see LICENSE for details. + * + */ + +@import url("pyramid.css"); + +div.header-small { + background-image: linear-gradient(white, #e2e2e2); + border-bottom: 1px solid #bbb; +} + +div.logo-small { + padding: 10px; +} + +img.logo { + width: 150px; +} + +div.related a { + color: #e6820e; +} + +a, a .pre { + color: #e6820e; +} diff -r 76ab3c71aff2 -r c67bcee93248 doc/_themes/cubicweb/static/cubicweb.ico --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/_themes/cubicweb/static/cubicweb.ico Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,1 @@ +../../../../../../web/data/favicon.ico \ No newline at end of file diff -r 76ab3c71aff2 -r c67bcee93248 doc/_themes/cubicweb/static/logo-cubicweb-small.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/_themes/cubicweb/static/logo-cubicweb-small.svg Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,1 @@ +logo-cubicweb.svg \ No newline at end of file diff -r 76ab3c71aff2 -r c67bcee93248 doc/_themes/cubicweb/static/logo-cubicweb.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/_themes/cubicweb/static/logo-cubicweb.svg Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,1 @@ +../../../../../../web/data/logo-cubicweb.svg \ No newline at end of file diff -r 76ab3c71aff2 -r c67bcee93248 doc/_themes/cubicweb/theme.conf --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/_themes/cubicweb/theme.conf Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,12 @@ +[theme] +inherit = pyramid +pygments_style = sphinx.pygments_styles.PyramidStyle +stylesheet = cubicweb.css + + +[options] +logo = logo-cubicweb.svg +favicon = cubicweb.ico +in_progress = false +outdated = false +canonical_url = diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/MERGE_ME-tut-create-app.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/MERGE_ME-tut-create-app.en.txt Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,386 @@ +.. -*- coding: utf-8 -*- + + +Tutoriel : créer votre première application web pour Google AppEngine +===================================================================== + +[TRANSLATE ME TO FRENCH] + +This tutorial will guide you step by step to build a blog application +and discover the unique features of `LAX`. It assumes that you followed +the :ref:`installation` guidelines and that both the `AppEngine SDK` and the +`LAX` framework are setup on your computer. + +Creating a new application +-------------------------- + +We choosed in this tutorial to develop a blog as an example of web application +and will go through each required steps/actions to have it running with `LAX`. +When you installed `LAX`, you saw a directory named ``skel``. Make a copy of +this directory and call it ``BlogDemo``. + +The location of this directory does not matter. But once decided, make sure your ``PYTHONPATH`` is properly set (:ref:`installation`). + + +Defining a schema +----------------- + +With `LAX`, the schema/datamodel is the core of the application. This is where +you will define the type of content you have to hanlde in your application. + +Let us start with something simple and improve on it iteratively. + +In schema.py, we define two entities: ``Blog`` and ``BlogEntry``. + +:: + + class Blog(EntityType): + title = String(maxsize=50, required=True) + description = String() + + class BlogEntry(EntityType): + title = String(maxsize=100, required=True) + publish_date = Date(default='TODAY') + text = String(fulltextindexed=True) + category = String(vocabulary=('important','business')) + entry_of = SubjectRelation('Blog', cardinality='?*') + +A Blog has a title and a description. The title is a string that is +required by the class EntityType and must be less than 50 characters. +The description is a string that is not constrained. + +A BlogEntry has a title, a publish_date and a text. The title is a +string that is required and must be less than 100 characters. The +publish_date is a Date with a default value of TODAY, meaning that +when a BlogEntry is created, its publish_date will be the current day +unless it is modified. The text is a string that will be indexed in +the full-text index and has no constraint. + +A BlogEntry also has a relationship ``entry_of`` that link it to a +Blog. The cardinality ``?*`` means that a BlogEntry can be part of +zero or one Blog (``?`` means `zero or one`) and that a Blog can +have any number of BlogEntry (``*`` means `any number including +zero`). For completeness, remember that ``+`` means `one or more`. + +Running the application +----------------------- + +Defining this simple schema is enough to get us started. Make sure you +followed the setup steps described in detail in the installation +chapter (especially visiting http://localhost:8080/_load as an +administrator), then launch the application with the command:: + + python dev_appserver.py BlogDemo + +and point your browser at http://localhost:8080/ (if it is easier for +you, use the on-line demo at http://lax.appspot.com/). + +.. image:: images/lax-book.00-login.en.png + :alt: login screen + +After you log in, you will see the home page of your application. It +lists the entity types: Blog and BlogEntry. If these links read +``blog_plural`` and ``blogentry_plural`` it is because +internationalization (i18n) is not working for you yet. Please ignore +this for now. + +.. image:: images/lax-book.01-start.en.png + :alt: home page + +Creating system entities +------------------------ +You can only create new users if you decided not to use google authentication. + + +[WRITE ME : create users manages permissions etc] + + + +Creating application entites +---------------------------- + +Create a Blog +~~~~~~~~~~~~~ + +Let us create a few of these entities. Click on the [+] at the right +of the link Blog. Call this new Blog ``Tech-blog`` and type in +``everything about technology`` as the description, then validate the +form by clicking on ``Validate``. + +.. image:: images/lax-book.02-create-blog.en.png + :alt: from to create blog + +Click on the logo at top left to get back to the home page, then +follow the Blog link that will list for you all the existing Blog. +You should be seeing a list with a single item ``Tech-blog`` you +just created. + +.. image:: images/lax-book.03-list-one-blog.en.png + :alt: displaying a list of a single blog + +Clicking on this item will get you to its detailed description except +that in this case, there is not much to display besides the name and +the phrase ``everything about technology``. + +.. image:: images/lax-book.04-detail-one-blog.en.png + :alt: displaying the detailed view of a blog + +Now get back to the home page by clicking on the top-left logo, then +create a new Blog called ``MyLife`` and get back to the home page +again to follow the Blog link for the second time. The list now +has two items. + +.. image:: images/lax-book.05-list-two-blog.en.png + :alt: displaying a list of two blogs + + +Create a BlogEntry +~~~~~~~~~~~~~~~~~~ + +Get back to the home page and click on [+] at the right of the link +BlogEntry. Call this new entry ``Hello World`` and type in some text +before clicking on ``Validate``. You added a new blog entry without +saying to what blog it belongs. There is a box on the left entitled +``actions``, click on the menu item ``modify``. You are back to the form +to edit the blog entry you just created, except that the form now has +another section with a combobox titled ``add relation``. Chose +``entry_of`` in this menu and a second combobox appears where you pick +``MyLife``. + +You could also have, at the time you started to fill the form for a +new entity BlogEntry, hit ``Apply`` instead of ``Validate`` and the +combobox titled ``add relation`` would have showed up. + +.. image:: images/lax-book.06-add-relation-entryof.en.png + :alt: editing a blog entry to add a relation to a blog + +Validate the changes by clicking ``Validate``. The entity BlogEntry +that is displayed now includes a link to the entity Blog named +``MyLife``. + +.. image:: images/lax-book.07-detail-one-blogentry.en.png + :alt: displaying the detailed view of a blogentry + +Remember that all of this was handled by the framework and that the +only input that was provided so far is the schema. To get a graphical +view of the schema, run the ``laxctl genschema BlogDemo`` command as +explained in the installation section and point your browser to the +URL http://localhost:8080/schema + +.. image:: images/lax-book.08-schema.en.png + :alt: graphical view of the schema (aka data-model) + +Site configuration +------------------ + +.. image:: images/lax-book.03-site-config-panel.en.png + +This panel allows you to configure the appearance of your application site. +Six menus are available and we will go through each of them to explain how +to use them. + +Navigation +~~~~~~~~~~ +This menu provides you a way to adjust some navigation options depending on +your needs, such as the number of entities to display by page of results. +Follows the detailled list of available options: + +* navigation.combobox-limit: maximum number of entities to display in related + combo box (sample format: 23) +* navigation.page-size: maximum number of objects displayed by page of results + (sample format: 23) +* navigation.related-limit: maximum number of related entities to display in + the primary view (sample format: 23) +* navigation.short-line-size: maximum number of characters in short description + (sample format: 23) + +UI +~~ +This menu provides you a way to customize the user interface settings such as +date format or encoding in the produced html. +Follows the detailled list of available options: + +* ui.date-format : how to format date in the ui ("man strftime" for format description) +* ui.datetime-format : how to format date and time in the ui ("man strftime" for format + description) +* ui.default-text-format : default text format for rich text fields. +* ui.encoding : user interface encoding +* ui.fckeditor : should html fields being edited using fckeditor (a HTML WYSIWYG editor). + You should also select text/html as default text format to actually get fckeditor. +* ui.float-format : how to format float numbers in the ui +* ui.language : language of the user interface +* ui.main-template : id of main template used to render pages +* ui.site-title : site title, which is displayed right next to the logo in the header +* ui.time-format : how to format time in the ui ("man strftime" for format description) + + +Actions +~~~~~~~ +This menu provides a way to configure the context in which you expect the actions +to be displayed to the user and if you want the action to be visible or not. +You must have notice that when you view a list of entities, an action box is +available on the left column which display some actions as well as a drop-down +menu for more actions. + +The context available are: + +* mainactions : actions listed in the left box +* moreactions : actions listed in the `more` menu of the left box +* addrelated : add actions listed in the left box +* useractions : actions listed in the first section of drop-down menu + accessible from the right corner user login link +* siteactions : actions listed in the second section of drop-down menu + accessible from the right corner user login link +* hidden : select this to hide the specific action + +Boxes +~~~~~ +The application has already a pre-defined set of boxes you can use right away. +This configuration section allows you to place those boxes where you want in the +application interface to customize it. + +The available boxes are: + +* actions box : box listing the applicable actions on the displayed data + +* boxes_blog_archives_box : box listing the blog archives + +* possible views box : box listing the possible views for the displayed data + +* rss box : RSS icon to get displayed data as a RSS thread + +* search box : search box + +* startup views box : box listing the configuration options available for + the application site, such as `Preferences` and `Site Configuration` + +Components +~~~~~~~~~~ +[WRITE ME] + +Contextual components +~~~~~~~~~~~~~~~~~~~~~ +[WRITE ME] + +Set-up a workflow +----------------- + +Before starting, make sure you refresh your mind by reading [link to +definition_workflow chapter]. + +We want to create a workflow to control the quality of the BlogEntry +submitted on your application. When a BlogEntry is created by a user +its state should be `submitted`. To be visible to all, it needs to +be in the state `published`. To move from `submitted` to `published` +we need a transition that we can name `approve_blogentry`. + +We do not want every user to be allowed to change the state of a +BlogEntry. We need to define a group of user, `moderators`, and +this group will have appropriate permissions to approve BlogEntry +to be published and visible to all. + +There are two ways to create a workflow, form the user interface, +and also by defining it in ``migration/postcreate.py``. This script +is executed each time a new ``./bin/laxctl db-init`` is done. +If you create the states and transitions through the user interface +this means that next time you will need to initialize the database +you will have to re-create all the entities. +We strongly recommand you create the workflow in ``migration\postcreate.py`` +and we will now show you how. +The user interface would only be a reference for you to view the states +and transitions but is not the appropriate interface to define your +application workflow. + +Update the schema +~~~~~~~~~~~~~~~~~ +To enable a BlogEntry to have a State, we have to define a relation +``in_state`` in the schema of BlogEntry. Please do as follows, add +the line ``in_state (...)``:: + + class BlogEntry(EntityType): + title = String(maxsize=100, required=True) + publish_date = Date(default='TODAY') + text_format = String(meta=True, internationalizable=True, maxsize=50, + default='text/rest', constraints=[format_constraint]) + text = String(fulltextindexed=True) + category = String(vocabulary=('important','business')) + entry_of = SubjectRelation('Blog', cardinality='?*') + in_state = SubjectRelation('State', cardinality='1*') + +As you updated the schema, you will have re-execute ``./bin/laxctl db-init`` +to initialize the database and migrate your existing entities. +[WRITE ABOUT MIGRATION] + +Create states, transitions and group permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +At the time the ``postcreate.py`` script is executed, several methods +can be used. They are all defined in the ``class ServerMigrationHelper``. +We will only discuss the method we use to create a wrokflow here. + +To define our workflow for BlogDemo, please add the following lines +to ``migration/postcreate.py``:: + + _ = unicode + + moderators = add_entity('CWGroup', name=u"moderators") + + submitted = add_state(_('submitted'), 'BlogEntry', initial=True) + published = add_state(_('published'), 'BlogEntry') + + add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),) + + checkpoint() + +``add_entity`` is used here to define the new group of users that we +need to define the transitions, `moderators`. +If this group required by the transition is not defined before the +transition is created, it will not create the relation `transition +require the group moderator`. + +``add_state`` expects as the first argument the name of the state you are +willing to create, then the entity type on which the state can be applied, +and an optionnal argument to set if the state is the initial state +of the entity type or not. + +``add_transition`` expects as the first argument the name of the +transition, then the entity type on which we can apply the transition, +then the list of possible initial states from which the transition +can be applied, the target state of the transition, and the permissions +(e.g. list of the groups of users who can apply the transition). + +.. image:: images/lax-book.03-transitions-view.en.png + +You can now notice that in the actions box of a BlogEntry, the state +is now listed as well as the possible transitions from this state +defined by the workflow. This transition, as defined in the workflow, +will only being displayed for the users belonging to the group +moderators of managers. + +Change view permission +~~~~~~~~~~~~~~~~~~~~~~ + + + +Conclusion +---------- + +Exercise +~~~~~~~~ + +Create new blog entries in ``Tech-blog``. + +What we learned +~~~~~~~~~~~~~~~ + +Creating a simple schema was enough to set up a new application that +can store blogs and blog entries. + +What is next ? +~~~~~~~~~~~~~~ + +Although the application is fully functionnal, its look is very +basic. In the following section we will learn to create views to +customize how data is displayed. + + diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/MERGE_ME-tut-create-gae-app.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/MERGE_ME-tut-create-gae-app.en.txt Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,218 @@ +.. -*- coding: utf-8 -*- + +.. _tutorielGAE: + +Tutoriel : créer votre première application web pour Google AppEngine +===================================================================== + +Ce tutoriel va vous guider pas à pas a construire une apllication web +de gestion de Blog afin de vous faire découvrir les fonctionnalités de +*CubicWeb*. + +Nous supposons que vous avec déjà suivi le guide :ref:`installationGAE`. + + +Créez une nouvelle application +------------------------------ + +Nous choisissons dans ce tutoriel de développer un blog comme un exemple +d'application web et nous allons expliciter toutes les étapes nécessaires +à sa réalisation. + +:: + + cubicweb-ctl newgapp blogdemo + +`newgapp` est la commande permettant de créer une instance *CubicWeb* pour +le datastore. + +Assurez-vous que votre variable d'environnement ``PYTHONPATH`` est correctement +initialisée (:ref:`installationGAE`) + +Définissez un schéma +-------------------- + +Le modèle de données ou schéma est au coeur d'une application *CubicWeb*. +C'est là où vous allez devoir définir le type de contenu que votre application +devra gérer. + +Commençons par un schéma simple que nous améliorerons progressivemment. + +Une fois votre instance ``blogdemo`` crée, vous trouverez un fichier ``schema.py`` +contenant la définition des entités suivantes : ``Blog`` and ``BlogEntry``. + +:: + + class Blog(EntityType): + title = String(maxsize=50, required=True) + description = String() + + class BlogEntry(EntityType): + title = String(maxsize=100, required=True) + publish_date = Date(default='TODAY') + text = String(fulltextindexed=True) + category = String(vocabulary=('important','business')) + entry_of = SubjectRelation('Blog', cardinality='?*') + + +Un ``Blog`` a un titre et une description. Le titre est une chaîne +de caractères requise par la classe parente EntityType and ne doit +pas excéder 50 caractères. La description est une chaîne de +caractères sans contraintes. + +Une ``BlogEntry`` a un titre, une date de publication et du texte +étant son contenu. Le titre est une chaîne de caractères qui ne +doit pas excéder 100 caractères. La date de publication est de type Date et a +pour valeur par défaut TODAY, ce qui signifie que lorsqu'une +``BlogEntry`` sera créée, sa date de publication sera la date +courante a moins de modifier ce champ. Le texte est une chaîne de +caractères qui sera indexée en plein texte et sans contraintes. + +Une ``BlogEntry`` a aussi une relation nommée ``entry_of`` qui la +relie à un ``Blog``. La cardinalité ``?*`` signifie que BlogEntry +peut faire partie de zero a un Blog (``?`` signifie `zero ou un`) et +qu'un Blog peut avoir une infinité de BlogEntry (``*`` signifie +`n'importe quel nombre incluant zero`). +Par soucis de complétude, nous rappellerons que ``+`` signifie +`un ou plus`. + +Lancez l'application +-------------------- + +Définir ce simple schéma est suffisant pour commencer. Assurez-vous +que vous avez suivi les étapes décrites dans la section installation +(en particulier visitez http://localhost:8080/_load en tant qu'administrateur +afin d'initialiser le datastore), puis lancez votre application avec la commande :: + + python dev_appserver.py BlogDemo + +puis dirigez vous vers http://localhost:8080/ (ou si c'est plus facile +vous pouvez utiliser la démo en ligne http://lax.appspot.com/). +[FIXME] -- changer la demo en ligne en quelque chose qui marche (!) + +.. image:: images/lax-book.00-login.en.png + :alt: login screen + +Après vous être authentifié, vous arrivez sur la page d'accueil de votre +application. Cette page liste les types d'entités accessibles dans votre +application, en l'occurrence : Blog et Articles. Si vous lisez ``blog_plural`` +et ``blogentry_plural`` cela signifie que l'internationalisation (i18n) +n'a pas encore fonctionné. Ignorez cela pour le moment. + +.. image:: images/lax-book.01-start.en.png + :alt: home page + +Créez des entités système +------------------------- + +Vous ne pourrez créer de nouveaux utilisateurs que dans le cas où vous +avez choisi de ne pas utiliser l'authentification Google. + + +[WRITE ME : create users manages permissions etc] + + + +Créez des entités applicatives +------------------------------ + +Créez un Blog +~~~~~~~~~~~~~ + +Créons à présent quelques entités. Cliquez sur `[+]` sur la +droite du lien Blog. Appelez cette nouvelle entité Blog ``Tech-Blog`` +et tapez pour la description ``everything about technology``, +puis validez le formulaire d'édition en cliquant sur le bouton +``Validate``. + + +.. image:: images/lax-book.02-create-blog.en.png + :alt: from to create blog + +En cliquant sur le logo situé dans le coin gauche de la fenêtre, +vous allez être redirigé vers la page d'accueil. Ensuite, si vous allez +sur le lien Blog, vous devriez voir la liste des entités Blog, en particulier +celui que vous venez juste de créer ``Tech-Blog``. + +.. image:: images/lax-book.03-list-one-blog.en.png + :alt: displaying a list of a single blog + +Si vous cliquez sur ``Tech-Blog`` vous devriez obtenir une description +détaillée, ce qui dans notre cas, n'est rien de plus que le titre +et la phrase ``everything about technology`` + + +.. image:: images/lax-book.04-detail-one-blog.en.png + :alt: displaying the detailed view of a blog + +Maintenant retournons sur la page d'accueil et créons un nouveau +Blog ``MyLife`` et retournons sur la page d'accueil, puis suivons +le lien Blog et nous constatons qu'à présent deux blogs sont listés. + +.. image:: images/lax-book.05-list-two-blog.en.png + :alt: displaying a list of two blogs + +Créons un article +~~~~~~~~~~~~~~~~~ + +Revenons sur la page d'accueil et cliquons sur `[+]` à droite du lien +`articles`. Appellons cette nouvelle entité ``Hello World`` et introduisons +un peut de texte avant de ``Valider``. Vous venez d'ajouter un article +sans avoir précisé à quel Blog il appartenait. Dans la colonne de gauche +se trouve une boite intitulé ``actions``, cliquez sur le menu ``modifier``. +Vous êtes de retour sur le formulaire d'édition de l'article que vous +venez de créer, à ceci près que ce formulaire a maintenant une nouvelle +section intitulée ``ajouter relation``. Choisissez ``entry_of`` dans ce menu, +cela va faire apparaitre une deuxième menu déroulant dans lequel vous +allez pouvoir séléctionner le Blog ``MyLife``. + +Vous auriez pu aussi, au moment où vous avez crée votre article, sélectionner +``appliquer`` au lieu de ``valider`` et le menu ``ajouter relation`` serait apparu. + +.. image:: images/lax-book.06-add-relation-entryof.en.png + :alt: editing a blog entry to add a relation to a blog + +Validez vos modifications en cliquant sur ``Valider``. L'entité article +qui est listée contient maintenant un lien vers le Blog auquel il +appartient, ``MyLife``. + +.. image:: images/lax-book.07-detail-one-blogentry.en.png + :alt: displaying the detailed view of a blogentry + +Rappelez-vous que pour le moment, tout a été géré par la plate-forme +*CubicWeb* et que la seule chose qui a été fournie est le schéma de +données. D'ailleurs pour obtenir une vue graphique du schéma, exécutez +la commande ``laxctl genschema blogdemo`` et vous pourrez visualiser +votre schéma a l'URL suivante : http://localhost:8080/schema + +.. image:: images/lax-book.08-schema.en.png + :alt: graphical view of the schema (aka data-model) + + +Change view permission +~~~~~~~~~~~~~~~~~~~~~~ + + + +Conclusion +---------- + +Exercise +~~~~~~~~ + +Create new blog entries in ``Tech-blog``. + +What we learned +~~~~~~~~~~~~~~~ + +Creating a simple schema was enough to set up a new application that +can store blogs and blog entries. + +What is next ? +~~~~~~~~~~~~~~ + +Although the application is fully functionnal, its look is very +basic. In the following section we will learn to create views to +customize how data is displayed. + + diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/README --- a/doc/book/README Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,85 +0,0 @@ -==== -Book -==== - ----- -Part ----- - -Chapter -======= - -.. _Level1AnchorForLaterReference: - -Level 1 section ---------------- - -Level 2 section -~~~~~~~~~~~~~~~ - -Level 3 section -``````````````` - - - -*CubicWeb* - - -inline directives: - :file:`directory/file` - :envvar:`AN_ENV_VARIABLE` - :command:`command --option arguments` - - :ref:, :mod: - - -.. sourcecode:: python - - class SomePythonCode: - ... - -.. XXX a comment, wont be rendered - - -a [foot note]_ - -.. [foot note] the foot note content - - -Boxes -===== - -- warning box: - .. warning:: - - Warning content -- note box: - .. note:: - - Note content - - - -Cross references -================ - -To arbitrary section --------------------- - -:ref:`identifier` ou :ref:`label ` - -Label required of referencing node which as no title, else the node's title will be used. - - -To API objects --------------- -See the autodoc sphinx extension documentation. Quick overview: - -* ref to a class: :class:`cubicweb.devtools.testlib.AutomaticWebTest` - -* if you can to see only the class name in the generated documentation, add a ~: - :class:`~cubicweb.devtools.testlib.AutomaticWebTest` - -* you can also use :mod: (module), :exc: (exception), :func: (function), :meth: (method)... - -* syntax explained above to specify label explicitly may also be used diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/additionnal_services/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/additionnal_services/index.rst Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,14 @@ +Additional services +=================== + +In this chapter, we introduce services crossing the *web - +repository - administration* organisation of the first parts of the +CubicWeb book. Those services can be either proper services (like the +undo functionality) or mere *topical cross-sections* across CubicWeb. + +.. toctree:: + :maxdepth: 2 + + undo + + diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/additionnal_services/undo.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/additionnal_services/undo.rst Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,337 @@ +Undoing changes in CubicWeb +--------------------------- + +Many desktop applications offer the possibility for the user to +undo its last changes : this *undo feature* has now been +integrated into the CubicWeb framework. This document will +introduce you to the *undo feature* both from the end-user and the +application developer point of view. + +But because a semantic web application and a common desktop +application are not the same thing at all, especially as far as +undoing is concerned, we will first introduce *what* is the *undo +feature* for now. + +What's *undoing* in a CubicWeb application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +What is an *undo feature* is quite intuitive in the context of a +desktop application. But it is a bit subtler in the context of a +Semantic Web application. This section introduces some of the main +differences between a classical desktop and a Semantic Web +applications to keep in mind in order to state precisely *what we +want*. + +The notion transactions +``````````````````````` + +A CubicWeb application acts upon an *Entity-Relationship* model, +described by a schema. This allows to ensure some data integrity +properties. It also implies that changes are made by all-or-none +groups called *transactions*, such that the data integrity is +preserved whether the transaction is completely applied *or* none +of it is applied. + +A transaction can thus include more actions than just those +directly required by the main purpose of the user. For example, +when a user *just* writes a new blog entry, the underlying +*transaction* holds several *actions* as illustrated below : + +* By admin on 2012/02/17 15:18 - Created Blog entry : Torototo + + #. Created Blog entry : Torototo + #. Added relation : Torototo owned by admin + #. Added relation : Torototo blog entry of Undo Blog + #. Added relation : Torototo in state draft (draft) + #. Added relation : Torototo created by admin + +Because of the very nature (all-or-none) of the transactions, the +"undoable stuff" are the transactions and not the actions ! + +Public and private actions within a transaction +``````````````````````````````````````````````` + +Actually, within the *transaction* "Created Blog entry : +Torototo", two of those *actions* are said to be *public* and +the others are said to be *private*. *Public* here means that the +public actions (1 and 3) were directly requested by the end user ; +whereas *private* means that the other actions (2, 4, 5) were +triggered "under the hood" to fulfill various requirements for the +user operation (ensuring integrity, security, ... ). + +And because quite a lot of actions can be triggered by a "simple" +end-user request, most of which the end-user is not (and does not +need or wish to be) aware, only the so-called public actions will +appear [1]_ in the description of the an undoable transaction. + +* By admin on 2012/02/17 15:18 - Created Blog entry : Torototo + + #. Created Blog entry : Torototo + #. Added relation : Torototo blog entry of Undo Blog + +But note that both public and private actions will be undone +together when the transaction is undone. + +(In)dependent transactions : the simple case +```````````````````````````````````````````` + +A CubicWeb application can be used *simultaneously* by different users +(whereas a single user works on an given office document at a +given time), so that there is not always a single history +time-line in the CubicWeb case. Moreover CubicWeb provides +security through the mechanism of *permissions* granted to each +user. This can lead to some transactions *not* being undoable in +some contexts. + +In the simple case two (unprivileged) users Alice and Bob make +relatively independent changes : then both Alice and Bob can undo +their changes. But in some case there is a clean dependency +between Alice's and Bob's actions or between actions of one of +them. For example let's suppose that : + +- Alice has created a blog, +- then has published a first post inside, +- then Bob has published a second post in the same blog, +- and finally Alice has updated its post contents. + +Then it is clear that Alice can undo her contents changes and Bob +can undo his post creation independently. But Alice can not undo +her post creation while she has not first undone her changes. +It is also clear that Bob should *not* have the +permissions to undo any of Alice's transactions. + + +More complex dependencies between transactions +`````````````````````````````````````````````` + +But more surprising things can quickly happen. Going back to the +previous example, Alice *can* undo the creation of the blog after +Bob has published its post in it ! But this is possible only +because the schema does not *require* for a post to be in a +blog. Would the *blog entry of* relation have been mandatory, then +Alice could not have undone the blog creation because it would +have broken integrity constraint for Bob's post. + +When a user attempts to undo a transaction the system will check +whether a later transaction has explicit dependency on the +would-be-undone transaction. In this case the system will not even +attempt the undo operation and inform the user. + +If no such dependency is detected the system will attempt the undo +operation but it can fail, typically because of integrity +constraint violations. In such a case the undo operation is +completely [3]_ rollbacked. + + +The *undo feature* for CubicWeb end-users +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The exposition of the undo feature to the end-user through a Web +interface is still quite basic and will be improved toward a +greater usability. But it is already fully functional. For now +there are two ways to access the *undo feature* as long as the it +has been activated in the instance configuration file with the +option *undo-support=yes*. + +Immediately after having done the change to be canceled through +the **undo** link in the message. This allows to undo an +hastily action immediately. For example, just after having +validated the creation of the blog entry *A second blog entry* we +get the following message, allowing to undo the creation. + +.. image:: /images/undo_mesage_w600.png + :width: 600px + :alt: Screenshot of the undo link in the message + :align: center + +At any time we can access the **undo-history view** accessible from the +start-up page. + +.. image:: /images/undo_startup-link_w600.png + :width: 600px + :alt: Screenshot of the startup menu with access to the history view + :align: center + +This view will provide inspection of the transaction and their (public) +actions. Each transaction provides its own **undo** link. Only the +transactions the user has permissions to see and undo will be shown. + +.. image:: /images/undo_history-view_w600.png + :width: 600px + :alt: Screenshot of the undo history main view + :align: center + +If the user attempts to undo a transaction which can't be undone or +whose undoing fails, then a message will explain the situation and +no partial undoing will be left behind. + +This is all for the end-user side of the undo mechanism : this is +quite simple indeed ! Now, in the following section, we are going +to introduce the developer side of the undo mechanism. + +The *undo feature* for CubicWeb application developers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A word of warning : this section is intended for developers, +already having some knowledge of what's under CubicWeb's hood. If +it is not *yet* the case, please refer to CubicWeb documentation +http://docs.cubicweb.org/ . + +Overview +```````` + +The core of the undo mechanisms is at work in the *native source*, +beyond the RQL. This does mean that *transactions* and *actions* +are *no entities*. Instead they are represented at the SQL level +and exposed through the *DB-API* supported by the repository +*Connection* objects. + +Once the *undo feature* has been activated in the instance +configuration file with the option *undo-support=yes*, each +mutating operation (cf. [2]_) will be recorded in some special SQL +table along with its associated transaction. Transaction are +identified by a *txuuid* through which the functions of the +*DB-API* handle them. + +On the web side the last commited transaction *txuuid* is +remembered in the request's data to allow for imediate undoing +whereas the *undo-history view* relies upon the *DB-API* to list +the accessible transactions. The actual undoing is performed by +the *UndoController* accessible at URL of the form +`www.my.host/my/instance/undo?txuuid=...` + +The repository side +``````````````````` + +Please refer to the file `cubicweb/server/sources/native.py` and +`cubicweb/transaction.py` for the details. + +The undoing information is mainly stored in three SQL tables: + +`transactions` + Stores the txuuid, the user eid and the date-and-time of + the transaction. This table is referenced by the two others. + +`tx_entity_actions` + Stores the undo information for actions on entities. + +`tx_relation_actions` + Stores the undo information for the actions on relations. + +When the undo support is activated, entries are added to those +tables for each mutating operation on the data repository, and are +deleted on each transaction undoing. + +Those table are accessible through the following methods of the +repository `Connection` object : + +`undoable_transactions` + Returns a list of `Transaction` objects accessible to the user + and according to the specified filter(s) if any. + +`tx_info` + Returns a `Transaction` object from a `txuuid` + +`undo_transaction` + Returns the list of `Action` object for the given `txuuid`. + + NB: By default it only return *public* actions. + +The web side +```````````` + +The exposure of the *undo feature* to the end-user through the Web +interface relies on the *DB-API* introduced above. This implies +that the *transactions* and *actions* are not *entities* linked by +*relations* on which the usual views can be applied directly. + +That's why the file `cubicweb/web/views/undohistory.py` defines +some dedicated views to access the undo information : + +`UndoHistoryView` + This is a *StartupView*, the one accessible from the home + page of the instance which list all transactions. + +`UndoableTransactionView` + This view handles the display of a single `Transaction` object. + +`UndoableActionBaseView` + This (abstract) base class provides private methods to build + the display of actions whatever their nature. + +`Undoable[Add|Remove|Create|Delete|Update]ActionView` + Those views all inherit from `UndoableActionBaseView` and + each handles a specific kind of action. + +`UndoableActionPredicate` + This predicate is used as a *selector* to pick the appropriate + view for actions. + +Apart from this main *undo-history view* a `txuuid` is stored in +the request's data `last_undoable_transaction` in order to allow +immediate undoing of a hastily validated operation. This is +handled in `cubicweb/web/application.py` in the `main_publish` and +`add_undo_link_to_msg` methods for the storing and displaying +respectively. + +Once the undo information is accessible, typically through a +`txuuid` in an *undo* URL, the actual undo operation can be +performed by the `UndoController` defined in +`cubicweb/web/views/basecontrollers.py`. This controller basically +extracts the `txuuid` and performs a call to `undo_transaction` and +in case of an undo-specific error, lets the top level publisher +handle it as a validation error. + + +Conclusion +~~~~~~~~~~ + +The undo mechanism relies upon a low level recording of the +mutating operation on the repository. Those records are accessible +through some method added to the *DB-API* and exposed to the +end-user either through a whole history view of through an +immediate undoing link in the message box. + +The undo feature is functional but the interface and configuration +options are still quite reduced. One major improvement would be to +be able to filter with a finer grain which transactions or actions +one wants to see in the *undo-history view*. Another critical +improvement would be to enable the undo feature on a part only of +the entity-relationship schema to avoid storing too much useless +data and reduce the underlying overhead. + +But both functionality are related to the strong design choice not +to represent transactions and actions as entities and +relations. This has huge benefits in terms of safety and conceptual +simplicity but prevents from using lots of convenient CubicWeb +features such as *facets* to access undo information. + +Before developing further the undo feature or eventually revising +this design choice, it appears that some return of experience is +strongly needed. So don't hesitate to try the undo feature in your +application and send us some feedback. + + +Notes +~~~~~ + +.. [1] The end-user Web interface could be improved to enable + user to choose whether he wishes to see private actions. + +.. [2] There is only five kind of elementary actions (beyond + merely accessing data for reading): + + * **C** : creating an entity + * **D** : deleting an entity + * **U** : updating an entity attributes + * **A** : adding a relation + * **R** : removing a relation + +.. [3] Meaning none of the actions in the transaction is + undone. Depending upon the application, it might make sense + to enable *partial* undo. That is to say undo in which some + actions could not be undo without preventing to undo the + others actions in the transaction (as long as it does not + break schema integrity). This is not forbidden by the + back-end but is deliberately not supported by the front-end + (for now at least). diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/admin/additional-tips.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/admin/additional-tips.rst Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,64 @@ + +.. _Additional Tips: + +Backups (mostly with postgresql) +-------------------------------- + +It is always a good idea to backup. If your system does not do that, +you should set it up. Note that whenever you do an upgrade, +`cubicweb-ctl` offers you to backup your database. There are a number +of ways for doing backups. + +Using postgresql (and only that) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before you +go ahead, make sure the following permissions are correct :: + + # chgrp postgres /var/lib/cubicweb/backup + # chmod g+ws /var/lib/cubicweb/backup + # chgrp postgres /etc/cubicweb.d/**/sources + # chmod g+r /etc/cubicweb.d/**/sources + +Simply use the pg_dump in a cron installed for `postgres` user on the database server:: + + # m h dom mon dow command + 0 2 * * * pg_dump -Fc --username=cubicweb --no-owner > /var/backups/-$(date '+%Y-%m-%d_%H:%M:%S').dump + +Using :command:`cubicweb-ctl db-dump` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CubicWeb way is to use the :command:`db-dump` command. For that, +you have to put your passwords in a user-only-readable file at the +home directory of root user. The file is `.pgpass` (`chmod 0600`), in +this case for a socket run connection to PostgreSQL :: + + /var/run/postgresql:5432::: + +The postgres documentation for the `.pgpass` format can be found `here`_ + +Then add the following command to the crontab of the user (`crontab -e`):: + + # m h dom mon dow command + 0 2 * * * cubicweb-ctl db-dump + + +Backup ninja +~~~~~~~~~~~~ + +You can use a combination `backup-ninja`_ (which has a postgres script in the +example directory), `backuppc`)_ (for versionning). + +Please note that in the *CubicWeb way* it adds a second location for your +password which is error-prone. + +.. _`here` : http://www.postgresql.org/docs/current/static/libpq-pgpass.html +.. _`backup-ninja` : https://labs.riseup.net/code/projects/show/backupninja/ +.. _`backuppc` : http://backuppc.sourceforge.net/ + +.. warning:: + + Remember that these indications will fail you whenever you use + another database backend than postgres. Also it does properly handle + externally managed data such as files (using the Bytes File System + Storage). diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/admin/config.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/admin/config.rst Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,229 @@ +.. -*- coding: utf-8 -*- + +.. _ConfigEnv: + +Set-up of a *CubicWeb* environment +================================== + +You can `configure the database`_ system of your choice: + + - `PostgreSQL configuration`_ + - `MySql configuration`_ + - `SQLServer configuration`_ + - `SQLite configuration`_ + +For advanced features, have a look to: + + - `Cubicweb resources configuration`_ + +.. _`configure the database`: DatabaseInstallation_ +.. _`PostgreSQL configuration`: PostgresqlConfiguration_ +.. _`MySql configuration`: MySqlConfiguration_ +.. _`SQLServer configuration`: SQLServerConfiguration_ +.. _`SQLite configuration`: SQLiteConfiguration_ +.. _`Cubicweb resources configuration`: RessourcesConfiguration_ + + + +.. _RessourcesConfiguration: + +Cubicweb resources configuration +-------------------------------- + +.. autodocstring:: cubicweb.cwconfig + + +.. _DatabaseInstallation: + +Databases configuration +----------------------- + +Each instance can be configured with its own database connection information, +that will be stored in the instance's :file:`sources` file. The database to use +will be chosen when creating the instance. CubicWeb is known to run with +Postgresql (recommended), SQLServer and SQLite, and may run with MySQL. + +Other possible sources of data include CubicWeb, Subversion, LDAP and Mercurial, +but at least one relational database is required for CubicWeb to work. You do +not need to install a backend that you do not intend to use for one of your +instances. SQLite is not fit for production use, but it works well for testing +and ships with Python, which saves installation time when you want to get +started quickly. + +.. _PostgresqlConfiguration: + +PostgreSQL +~~~~~~~~~~ + +Many Linux distributions ship with the appropriate PostgreSQL packages. +Basically, you need to install the following packages: + +* `postgresql` and `postgresql-client`, which will pull the respective + versioned packages (e.g. `postgresql-9.1` and `postgresql-client-9.1`) and, + optionally, +* a `postgresql-plpython-X.Y` package with a version corresponding to that of + the aforementioned packages (e.g. `postgresql-plpython-9.1`). + +If you run postgres version prior to 8.3, you'll also need the +`postgresql-contrib-8.X` package for full-text search extension. + +If you run postgres on another host than the |cubicweb| repository, you should +install the `postgresql-client` package on the |cubicweb| host, and others on the +database host. + +For extra details concerning installation, please refer to the `PostgreSQL +project online documentation`_. + +.. _`PostgreSQL project online documentation`: http://www.postgresql.org/docs + + +Database cluster +++++++++++++++++ + +If you already have an existing cluster and PostgreSQL server running, you do +not need to execute the initilization step of your PostgreSQL database unless +you want a specific cluster for |cubicweb| databases or if your existing +cluster doesn't use the UTF8 encoding (see note below). + +To initialize a PostgreSQL cluster, use the command ``initdb``:: + + $ initdb -E UTF8 -D /path/to/pgsql + +Notice the encoding specification. This is necessary since |cubicweb| usually +want UTF8 encoded database. If you use a cluster with the wrong encoding, you'll +get error like:: + + new encoding (UTF8) is incompatible with the encoding of the template database (SQL_ASCII) + HINT: Use the same encoding as in the template database, or use template0 as template. + +Once initialized, start the database server PostgreSQL with the command:: + + $ postgres -D /path/to/psql + +If you cannot execute this command due to permission issues, please make sure +that your username has write access on the database. :: + + $ chown username /path/to/pgsql + +Database authentication ++++++++++++++++++++++++ + +The database authentication is configured in `pg_hba.conf`. It can be either set +to `ident sameuser` or `md5`. If set to `md5`, make sure to use an existing +user of your database. If set to `ident sameuser`, make sure that your client's +operating system user name has a matching user in the database. If not, please +do as follow to create a user:: + + $ su + $ su - postgres + $ createuser -s -P username + +The option `-P` (for password prompt), will encrypt the password with the +method set in the configuration file :file:`pg_hba.conf`. If you do not use this +option `-P`, then the default value will be null and you will need to set it +with:: + + $ su postgres -c "echo ALTER USER username WITH PASSWORD 'userpasswd' | psql" + +The above login/password will be requested when you will create an instance with +`cubicweb-ctl create` to initialize the database of your instance. + +Notice that the `cubicweb-ctl db-create` does database initialization that +may requires a postgres superuser. That's why a login/password is explicitly asked +at this step, so you can use there a superuser without using this user when running +the instance. Things that require special privileges at this step: + +* database creation, require the 'create database' permission +* install the plpython extension language (require superuser) +* install the tsearch extension for postgres version prior to 8.3 (require superuser) + +To avoid using a super user each time you create an install, a nice trick is to +install plpython (and tsearch when needed) on the special `template1` database, +so they will be installed automatically when cubicweb databases are created +without even with needs for special access rights. To do so, run :: + + # Installation of plpythonu language by default :: + $ createlang -U pgadmin plpythonu template1 + $ psql -U pgadmin template1 + template1=# update pg_language set lanpltrusted=TRUE where lanname='plpythonu'; + +Where `pgadmin` is a postgres superuser. The last command is necessary since by +default plpython is an 'untrusted' language and as such can't be used by non +superuser. This update fix that problem by making it trusted. + +To install the tsearch plain-text index extension on postgres prior to 8.3, run:: + + cat /usr/share/postgresql/8.X/contrib/tsearch2.sql | psql -U username template1 + + +.. _MySqlConfiguration: + +MySql +~~~~~ +.. warning:: + CubicWeb's MySQL support is not commonly used, so things may or may not work properly. + +You must add the following lines in ``/etc/mysql/my.cnf`` file:: + + transaction-isolation=READ-COMMITTED + default-storage-engine=INNODB + default-character-set=utf8 + max_allowed_packet = 128M + +.. Note:: + It is unclear whether mysql supports indexed string of arbitrary length or + not. + + +.. _SQLServerConfiguration: + +SQLServer +~~~~~~~~~ + +As of this writing, support for SQLServer 2005 is functional but incomplete. You +should be able to connect, create a database and go quite far, but some of the +SQL generated from RQL queries is still currently not accepted by the +backend. Porting to SQLServer 2008 is also an item on the backlog. + +The `source` configuration file may look like this (specific parts only are +shown):: + + [system] + db-driver=sqlserver2005 + db-user=someuser + # database password not needed + #db-password=toto123 + #db-create/init may ask for a pwd: just say anything + db-extra-arguments=Trusted_Connection + db-encoding=utf8 + + +You need to change the default settings on the database by running:: + + ALTER DATABASE SET READ_COMMITTED_SNAPSHOT ON; + +The ALTER DATABASE command above requires some permissions that your +user may not have. In that case you will have to ask your local DBA to +run the query for you. + +You can check that the setting is correct by running the following +query which must return '1':: + + SELECT is_read_committed_snapshot_on + FROM sys.databases WHERE name=''; + + + +.. _SQLiteConfiguration: + +SQLite +~~~~~~ + +SQLite has the great advantage of requiring almost no configuration. Simply +use 'sqlite' as db-driver, and set path to the dabase as db-name. Don't specify +anything for db-user and db-password, they will be ignore anyway. + +.. Note:: + SQLite is great for testing and to play with cubicweb but is not suited for + production environments. + diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/admin/create-instance.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/admin/create-instance.rst Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,100 @@ +.. -*- coding: utf-8 -*- + +Creation of your first instance +=============================== + +Instance creation +----------------- + +Now that we created a cube, we can create an instance and access it via a web +browser. We will use a `all-in-one` configuration to simplify things :: + + cubicweb-ctl create -c all-in-one mycube myinstance + +.. note:: + Please note that we created a new cube for a demo purposes but + you could have used an existing cube available in our standard library + such as blog or person for example. + +A series of questions will be prompted to you, the default answer is usually +sufficient. You can anyway modify the configuration later on by editing +configuration files. When a login/password are requested to access the database +please use the credentials you created at the time you configured the database +(:ref:`PostgresqlConfiguration`). + +It is important to distinguish here the user used to access the database and the +user used to login to the cubicweb instance. When an instance starts, it uses +the login/password for the database to get the schema and handle low level +transaction. But, when :command:`cubicweb-ctl create` asks for a manager +login/psswd of *CubicWeb*, it refers to the user you will use during the +development to administrate your web instance. It will be possible, later on, +to use this user to create other users for your final web instance. + + +Instance administration +----------------------- + +start / stop +~~~~~~~~~~~~ + +When this command is completed, the definition of your instance is +located in :file:`~/etc/cubicweb.d/myinstance/*`. To launch it, you +just type :: + + cubicweb-ctl start -D myinstance + +The option `-D` specifies the *debug mode* : the instance is not +running in server mode and does not disconnect from the terminal, +which simplifies debugging in case the instance is not properly +launched. You can see how it looks by visiting the URL +`http://localhost:8080` (the port number depends of your +configuration). To login, please use the cubicweb administrator +login/password you defined when you created the instance. + +To shutdown the instance, Crtl-C in the terminal window is enough. +If you did not use the option `-D`, then type :: + + cubicweb-ctl stop myinstance + +This is it! All is settled down to start developping your data model... + +.. note:: + + The output of `cubicweb-ctl start -D myinstance` can be + overwhelming. It is possible to reduce the log level with the + `--loglevel` parameter as in `cubicweb-ctl start -D myinstance -l + info` to filter out all logs under `info` gravity. + +upgrade +~~~~~~~ + +A manual upgrade step is necessary whenever a new version of CubicWeb or +a cube is installed, in order to synchronise the instance's +configuration and schema with the new code. The command is:: + + cubicweb-ctl upgrade myinstance + +A series of questions will be asked. It always starts with a proposal +to make a backup of your sources (where it applies). Unless you know +exactly what you are doing (i.e. typically fiddling in debug mode, but +definitely NOT migrating a production instance), you should answer YES +to that. + +The remaining questions concern the migration steps of |cubicweb|, +then of the cubes that form the whole application, in reverse +dependency order. + +In principle, if the migration scripts have been properly written and +tested, you should answer YES to all questions. + +Somtimes, typically while debugging a migration script, something goes +wrong and the migration fails. Unfortunately the databse may be in an +incoherent state. You have two options here: + +* fix the bug, restore the database and restart the migration process + from scratch (quite recommended in a production environement) + +* try to replay the migration up to the last successful commit, that + is answering NO to all questions up to the step that failed, and + finish by answering YES to the remaining questions. + diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/admin/cubicweb-ctl.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/admin/cubicweb-ctl.rst Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,111 @@ +.. -*- coding: utf-8 -*- + +.. _cubicweb-ctl: + +``cubicweb-ctl`` tool +===================== + +`cubicweb-ctl` is the swiss knife to manage *CubicWeb* instances. +The general syntax is :: + + cubicweb-ctl [options command] + +To view available commands :: + + cubicweb-ctl + cubicweb-ctl --help + +Please note that the commands available depends on the *CubicWeb* packages +and cubes that have been installed. + +To view the help menu on specific command :: + + cubicweb-ctl --help + +Listing available cubes and instance +------------------------------------- + +* ``list``, provides a list of the available configuration, cubes + and instances. + + +Creation of a new cube +----------------------- + +Create your new cube cube :: + + cubicweb-ctl newcube + +This will create a new cube in +``/path/to/grshell-cubicweb/cubes/`` for a Mercurial +installation, or in ``/usr/share/cubicweb/cubes`` for a debian +packages installation. + +Create an instance +------------------- + +You must ensure `~/etc/cubicweb.d/` exists prior to this. On windows, the +'~' part will probably expand to 'Documents and Settings/user'. + +To create an instance from an existing cube, execute the following +command :: + + cubicweb-ctl create + +This command will create the configuration files of an instance in +``~/etc/cubicweb.d/``. + +The tool ``cubicweb-ctl`` executes the command ``db-create`` and +``db-init`` when you run ``create`` so that you can complete an +instance creation in a single command. But of course it is possible +to issue these separate commands separately, at a later stage. + +Command to create/initialize an instance database +------------------------------------------------- + +* ``db-create``, creates the system database of an instance (tables and + extensions only) +* ``db-init``, initializes the system database of an instance + (schema, groups, users, workflows...) + +Commands to control instances +----------------------------- + +* ``start``, starts one or more or all instances + +of special interest:: + + start -D + +will start in debug mode (under windows, starting without -D will not +work; you need instead to setup your instance as a service). + +* ``stop``, stops one or more or all instances +* ``restart``, restarts one or more or all instances +* ``status``, returns the status of the instance(s) + +Commands to maintain instances +------------------------------ + +* ``upgrade``, launches the existing instances migration when a new version + of *CubicWeb* or the cubes installed is available +* ``shell``, opens a (Python based) migration shell for manual maintenance of the instance +* ``db-dump``, creates a dump of the system database +* ``db-restore``, restores a dump of the system database +* ``db-check``, checks data integrity of an instance. If the automatic correction + is activated, it is recommanded to create a dump before this operation. +* ``schema-sync``, synchronizes the persistent schema of an instance with + the instance schema. It is recommanded to create a dump before this operation. + +Commands to maintain i18n catalogs +---------------------------------- +* ``i18ncubicweb``, regenerates messages catalogs of the *CubicWeb* library +* ``i18ncube``, regenerates the messages catalogs of a cube +* ``i18ninstance``, recompiles the messages catalogs of an instance. + This is automatically done while upgrading. + +See also chapter :ref:`internationalization`. + +Other commands +-------------- +* ``delete``, deletes an instance (configuration files and database) diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/admin/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/admin/index.rst Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,28 @@ +.. -*- coding: utf-8 -*- + +.. _Part3: + +-------------- +Administration +-------------- + +This part is for installation and administration of the *CubicWeb* framework and +instances based on that framework. + +.. toctree:: + :maxdepth: 1 + :numbered: + + setup + setup-windows + config + cubicweb-ctl + create-instance + instance-config + site-config + multisources + ldap + migration + additional-tips + rql-logs + diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/admin/instance-config.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/admin/instance-config.rst Thu Jan 08 22:11:06 2015 +0100 @@ -0,0 +1,200 @@ +.. -*- coding: utf-8 -*- + + +Configure an instance +===================== + +While creating an instance, a configuration file is generated in:: + + $ (CW_INSTANCES_DIR) / / .conf + +For example:: + + /etc/cubicweb.d/myblog/all-in-one.conf + +It is a simple text file in the INI format +(http://en.wikipedia.org/wiki/INI_file). In the following description, +each option name is prefixed with its own section and followed by its +default value if necessary, e.g. "`
.