From 515b8a07629d7f93ce4806cbf1e2600d3eec51e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Fri, 7 Nov 2014 15:57:07 +0100 Subject: [PATCH 01/28] add doc for menus and flashbag --- source/development/flashbags.rst | 35 +++++++++ source/development/index.rst | 2 + source/development/menus.rst | 123 +++++++++++++++++++++++++++++++ 3 files changed, 160 insertions(+) create mode 100644 source/development/flashbags.rst create mode 100644 source/development/menus.rst diff --git a/source/development/flashbags.rst b/source/development/flashbags.rst new file mode 100644 index 000000000..d6334a7a3 --- /dev/null +++ b/source/development/flashbags.rst @@ -0,0 +1,35 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +.. _flashbags : + +Flashbags: message to users +**************************** + +The four following levels are defined : + ++-----------+----------------------------------------------------------------------------------------------+ +|Key |Intent | ++===========+==============================================================================================+ +|alert |A message not linked with the user action, but which should require an action or a | +| |correction. | ++-----------+----------------------------------------------------------------------------------------------+ +|success |The user action succeeds. | ++-----------+----------------------------------------------------------------------------------------------+ +|notice |A simple message to give information to the user. The message may be linked or not linked with| +| |the user action. | ++-----------+----------------------------------------------------------------------------------------------+ +|warning |A message linked with an action, the user should correct. | ++-----------+----------------------------------------------------------------------------------------------+ +|error |The user's action failed: he must correct something to process the action. | ++-----------+----------------------------------------------------------------------------------------------+ + +.. seealso:: + + `Flash Messages on Symfony documentation `_ + Learn how to use flash messages in controller. diff --git a/source/development/index.rst b/source/development/index.rst index c06ca6db5..6eef8cdd5 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -16,6 +16,8 @@ As Chill rely on the `symfony `_ framework, reading the fram Install Chill for development Instructions to create a new bundle + Menus + Message to users Testing manual/index.rst Official bundle's documentation diff --git a/source/development/menus.rst b/source/development/menus.rst new file mode 100644 index 000000000..5e6cda3ea --- /dev/null +++ b/source/development/menus.rst @@ -0,0 +1,123 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +.. _menus : + +Menus +***** + +Chill has created his own menu system + +.. seealso:: + + `Routes dans Chill [specification] `_ + The issue wich discussed the implementation of routes. + +Concepts +======== + +.. warning:: + + to be written + + + +Add a menu in a template +======================== + +In your twig template, use the `chill_menu` function : + +.. code-block:: html+jinja + + {{ chill_menu('person', { + 'layout': 'ChillPersonBundle::menu.html.twig', + 'args' : {'id': person.id }, + 'activeRouteKey': 'chill_person_view' + }) }} + +The available arguments are: + +* `layout` : a custom layout. Default to `ChillMainBundle:Menu:defaultMenu.html.twig` +* `args` : those arguments will be passed through the url generator. +* `activeRouteKey` must be the route key name. + +.. note:: + + The argument `activeRouteKey` may be a twig variable, defined elsewhere in your template, even in child templates. + + + +Create an entry in an existing menu +=================================== + +If a route belongs to a menu, you simply add this to his definition in routing.yml : + +.. code-block:: yaml + + chill_person_history_list: + pattern: /person/{person_id}/history + defaults: { _controller: ChillPersonBundle:History:list } + options: + #declare menus + menus: + # the route should be in 'person' menu : + person: + #and have those arguments : + order: 100 + label: menu.person.history + +* `order` (mandatory) : the order in the menu. It is preferrable to increment by far more than 1. +* `label` (mandatory) : a translatable string. +* `helper` (optional) : a text to help people to understand what does the menu do. Not used in default implementation. +* `condition` (optional) : an `Expression Language `_ which will make the menu appears or not. Typically, it may be used to say "show this menu only if the person concerned is more than 18". **Not implemented yet**. +* `access` (optional) : an Expression Language to evalute the possibility, for the user, to show this menu according to Access Control Model. **Not implemented yet.** + +You may add additional keys, but should not use the keys described above. + +You may add the same route to multiple menus : + +.. code-block:: yaml + + chill_person_history_list: + pattern: /person/{person_id}/history + defaults: { _controller: ChillPersonBundle:History:list } + options: + menus: + menu1: + order: 100 + label: menu.person.history + menu2: + order: 100 + label: another.label + + + +Customize menu rendering +======================== + +You may customize menu rendering by using the `layout` option. + +.. warning :: + + TODO : this part should be written. + + + + + + +.. _caveats : + +Caveats +======= + +Currently, you may pass arguments globally to each menu, and they will be all passed to route url. This means that : + +* the argument name in the route entry must match the argument key in menu declaration in twig template +* if an argument is missing to generate an url, the url generator will throw an error +* if the argument name is not declared in route entry, it will be added to the url, (example: `/my/route?additional=foo`) From 75cc85746e7c5e38a0f7aa6a6b1927e40e869dee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Fri, 7 Nov 2014 15:57:21 +0100 Subject: [PATCH 02/28] typo --- source/development/make-test-working.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/development/make-test-working.rst b/source/development/make-test-working.rst index 7b1919c4b..3f9778173 100644 --- a/source/development/make-test-working.rst +++ b/source/development/make-test-working.rst @@ -228,4 +228,4 @@ You should add there all routing information needed for your bundle. chill_main_bundle: resource: "@CLChillMainBundle/Resources/config/routing.yml" -That's it. Tests should not pass. +That's it. Tests should pass. From a271072f239ce813b46a5e53249d1ca77b8cf27b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Fri, 7 Nov 2014 16:02:18 +0100 Subject: [PATCH 03/28] precise the exception in case of missing parameter in url --- source/development/menus.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/development/menus.rst b/source/development/menus.rst index 5e6cda3ea..977591f1d 100644 --- a/source/development/menus.rst +++ b/source/development/menus.rst @@ -119,5 +119,5 @@ Caveats Currently, you may pass arguments globally to each menu, and they will be all passed to route url. This means that : * the argument name in the route entry must match the argument key in menu declaration in twig template -* if an argument is missing to generate an url, the url generator will throw an error +* if an argument is missing to generate an url, the url generator will throw a `Symfony\Component\Routing\Exception\MissingMandatoryParametersException` * if the argument name is not declared in route entry, it will be added to the url, (example: `/my/route?additional=foo`) From f70d3ef0b2d658ac5e1942b350edad33bc9bc1ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Sun, 9 Nov 2014 18:53:50 +0100 Subject: [PATCH 04/28] add dev tips for watching a field --- source/development/bundles/custom-fields.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/source/development/bundles/custom-fields.rst b/source/development/bundles/custom-fields.rst index 835921154..c30861e71 100644 --- a/source/development/bundles/custom-fields.rst +++ b/source/development/bundles/custom-fields.rst @@ -110,6 +110,20 @@ Add those file under `chill_custom_fields` section : * The class, which is a full FQDN class path +Development tips +----------------- + +If you want to test the rendering of a custom fields group, you may use this method : + +1. Run the built-in server **from the custom-fields directory** : + +.. code-block:: bash + + ./run-server.sh + +2. assuming that your custom fields id is `1`, go to your navigator and enter url : `http://localhost:8000/customfieldsgroup/test/render/2` + + .. glossary:: From f9ef4ab5154cdd8f61188890c07570f25986f3ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Sun, 9 Nov 2014 22:02:19 +0100 Subject: [PATCH 05/28] fix url --- source/development/bundles/custom-fields.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/development/bundles/custom-fields.rst b/source/development/bundles/custom-fields.rst index c30861e71..ae422b395 100644 --- a/source/development/bundles/custom-fields.rst +++ b/source/development/bundles/custom-fields.rst @@ -121,7 +121,7 @@ If you want to test the rendering of a custom fields group, you may use this met ./run-server.sh -2. assuming that your custom fields id is `1`, go to your navigator and enter url : `http://localhost:8000/customfieldsgroup/test/render/2` +2. assuming that your custom fields id is `1`, go to your navigator and enter url : `http://localhost:8000/customfieldsgroup/test/render/1` From 6d7567de01bc5b9cdaa67db79652d4d902bd5762 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Mon, 10 Nov 2014 00:47:20 +0100 Subject: [PATCH 06/28] enable todo extension --- source/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/conf.py b/source/conf.py index fb37071c5..2bee69683 100644 --- a/source/conf.py +++ b/source/conf.py @@ -334,6 +334,12 @@ epub_exclude_files = ['search.html'] # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +#-- Options for todo + +todo_include_todos = True + +#-- include template if not on RTD + if not on_rtd: # only import and set the theme if we're building docs locally import sphinx_rtd_theme html_theme = 'sphinx_rtd_theme' From 168e12045c70a6cc6ca58b471a23c0ef1629c738 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Mon, 10 Nov 2014 00:47:46 +0100 Subject: [PATCH 07/28] doc on custom fields rendering and form --- source/development/bundles/custom-fields.rst | 70 +++++++++++++++++++- 1 file changed, 68 insertions(+), 2 deletions(-) diff --git a/source/development/bundles/custom-fields.rst b/source/development/bundles/custom-fields.rst index ae422b395..885652a97 100644 --- a/source/development/bundles/custom-fields.rst +++ b/source/development/bundles/custom-fields.rst @@ -93,7 +93,7 @@ Declare your customizable class in configuration Two methods are available : * In your app/config.yml file. This is the easiest method, but discouraged because it will reduce the ease for installation. -* In your Configuration class +* In your Extension class : harder for devs, easier for installers. In app/config.yml file """""""""""""""""""""" @@ -103,12 +103,78 @@ Add those file under `chill_custom_fields` section : .. code-block:: yaml chill_custom_fields: - customizables_class: + customizables_entities: - { class: Chill\CustomFieldsBundle\Entity\BlopEntity, name: blop_entity } * The `name` allow you to define a string which is translatable. This string will appears when chill's admin will add/retrieve new customFieldsGroup. * The class, which is a full FQDN class path +Automatically, in DepedencyInjection/Extension class +"""""""""""""""""""""""""""""""""""""""""""""""""""" + +.. todo:: + + Explain how to declare customizable entitites in DepedencyInjection/Extension. + +Rendering custom fields in a template +-------------------------------------- + +.. todo:: + + Develop + + +Custom Fields's form +--------------------- + +You should simply use the 'custom_field' type in a template, with the group you would like to render in the `group` option + +Example : + +.. warning:: + + The above code isn't tested. + +.. todo:: + + Test the above code. + +.. code-block:: php + + use Symfony\Component\Form\AbstractType; + use Symfony\Component\Form\FormBuilderInterface; + use Symfony\Component\OptionsResolver\OptionsResolverInterface; + use Chill\CustomFieldsBundle\Form\Type\CustomFieldType; + use Chill\CustomFieldsBundle\Entity\CustomFieldsGroup; + + class BlopEntityType extends AbstractType + { + + public $group; + + public function __construct(CustomFieldsGroup $group) + { + $this->group = $group; + } + + + /** + * @param FormBuilderInterface $builder + * @param array $options + */ + public function buildForm(FormBuilderInterface $builder, array $options) + { + $builder + ->add('field1') + ->add('field2') + //->add('adress', new AdressType()) + ->add('customField', 'custom_field', array('group' => $group)) + ; + } + } + + + Development tips ----------------- From d3230043297c50bbc48e55fcfec69596ccbcbebf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Mon, 10 Nov 2014 00:48:05 +0100 Subject: [PATCH 08/28] add a todo list on front page --- source/index.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/index.rst b/source/index.rst index d6276ee2e..3d3a8858f 100644 --- a/source/index.rst +++ b/source/index.rst @@ -37,6 +37,11 @@ Contribute * Chill-standard : https://github.com/Champs-Libres/chill-standard * Chill-main : https://github.com/Champs-Libres/ChillMain +TODO in documentation +===================== + +.. todolist:: + Licence ======== From 5c0a9090face81449db941e7e6e34f1993bf0a6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Mon, 10 Nov 2014 13:07:32 +0100 Subject: [PATCH 09/28] add instructions to assume unchanged symfony files --- source/development/installation.rst | 31 +++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/source/development/installation.rst b/source/development/installation.rst index 87af17d5b..85855d187 100644 --- a/source/development/installation.rst +++ b/source/development/installation.rst @@ -46,6 +46,37 @@ This will install a project. All downloaded modules will be stored in the `/vend origin git://github.com/Chill-project/Standard.git (fetch) origin git@github.com:Chill-project/Standard.git (push) +Deleted and added files after installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Composer will deleted unrequired files, and add some of them. This perfectly normal and will appears in your git index. But you should NOT delete those files. + + +This should appears : + +.. code-block:: bash + + $git status + #(...) + + Modifications qui ne seront pas validées : + (utilisez "git add/rm ..." pour mettre à jour ce qui sera validé) + (utilisez "git checkout -- ..." pour annuler les modifications dans la copie de travail) + + modifié: app/SymfonyRequirements.php + supprimé: app/SymfonyStandard/Composer.php + supprimé: app/SymfonyStandard/RootPackageInstallSubscriber.php + modifié: app/check.php + +You can ignore the locally using the `git update-index --assume-unchanged` command. + +.. code-block:: bash + + $ git update-index --assume-unchanged app/check.php + $ git update-index --assume-unchanged app/SymfonyRequirements.php + $ git update-index --assume-unchanged app/SymfonyStandard/Composer.php + $ git update-index --assume-unchanged app/SymfonyStandard/RootPackageInstallSuscriber.php + Working with your own fork ^^^^^^^^^^^^^^^^^^^^^^^^^^ From f6aaefd1e56ac3ef3ccd79388b1193f5950c6cf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Mon, 10 Nov 2014 13:28:20 +0100 Subject: [PATCH 10/28] add docs for custom fields twig functions --- source/development/bundles/custom-fields.rst | 44 +++++++++++++++++++- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/source/development/bundles/custom-fields.rst b/source/development/bundles/custom-fields.rst index 885652a97..2cff00294 100644 --- a/source/development/bundles/custom-fields.rst +++ b/source/development/bundles/custom-fields.rst @@ -119,9 +119,49 @@ Automatically, in DepedencyInjection/Extension class Rendering custom fields in a template -------------------------------------- -.. todo:: +Two function are available : - Develop +* `chill_custom_field_widget` to render the widget. This function is defined on a customFieldType basis. +* `chill_custom_field_label` to render the label. You can customize the label rendering by choosing the layout you would like to use. + +**chill_custom_field_label** + +The signature is : + +* `CustomField|object|string` **$customFieldOrClass** either a customField OR a customizable_entity OR the FQDN of the entity +* `string` **$slug** only necessary if the first argument is NOT a CustomField instance +* `array` **params** the parameters for rendering. Currently, 'label_layout' allow to choose a different label. Default is 'ChillCustomFieldsBundle:CustomField:render_label.html.twig' + +Examples + +.. code-block:: jinja + + {{ chill_custom_field_label(customField) }} + + {{ chill_custom_field_label(entity, 'slug') }} + + {{ chill_custom_field_label('Path\To\Entity', 'slug') }} + + +**chill_custom_field_widget** + +* array **$fields** the array raw, as stored in the db +* CustomField|object|string $customFieldOrClass either a customField OR a customizable_entity OR the FQDN of the entity +* string **$slug** only necessary if the first argument is NOT a CustomField instance + +Examples: + +.. code-block:: jinja + + {{ chill_custom_field_widget(entity.customFields, customField) }} + + {{ chill_custom_field_widget(entity.customFields, entity, 'slug') }} + + {{ chill_custom_field_widget(fields, 'Path\To\Entity', 'slug') }} + +.. warning:: + + This feature is not fully tested. See `the corresponding issue `_ Custom Fields's form From 63d994bc49fe087af469db98bed3257c69f12509 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 4 Dec 2014 15:59:57 +0100 Subject: [PATCH 11/28] documentation about migrations close #216 --- source/development/index.rst | 1 + source/development/migrations.rst | 95 +++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+) create mode 100644 source/development/migrations.rst diff --git a/source/development/index.rst b/source/development/index.rst index 6eef8cdd5..2fb60d60d 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -18,6 +18,7 @@ As Chill rely on the `symfony `_ framework, reading the fram Instructions to create a new bundle Menus Message to users + Database migrations Testing manual/index.rst Official bundle's documentation diff --git a/source/development/migrations.rst b/source/development/migrations.rst new file mode 100644 index 000000000..7c3bbf73c --- /dev/null +++ b/source/development/migrations.rst @@ -0,0 +1,95 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +Database Migrations +******************** + +Every bundle potentially brings his own database operations : to persist entities, developers have to create database schema, creating indexes,... + +Those schema might be changed (the less is the better) from time to time. + +Consequence: each bundle should bring his own migration files, which will bring the database consistent with the operation you will run in your code. They will be gathered into the app installation, ready to be executed by the chill's installer. + +Currently, we use `doctrine migration`_ to manage those migration files. A `composer`_ script located in the **chill standard** component will copy the migrations from your bundle to the doctrne migration's excepted directory after each install and/or update operation. + +.. seealso:: + + The `doctrine migration`_ documentation + Learn concepts about migrations files and scripts and the doctrine ORM + + The `doctrine migration bundle`_ documentation + Learn about doctrine migration integration with Symfony framework + +Shipping migration files +======================== + +Migrations files should be shipped under the Resource/migrations directory. You could customize the migration directory by adding extra information in your composer.json: + +.. code-block:: json + + "extra": { + "migration-source": "path/to/my/dir" + } + +The class namespace should be `Application\Migrations`, as expected by doctrine migration. Only the files which will be executed by doctrine migration will be moved: they must have the pattern `VersionYYYYMMDDHHMMSS.php` where YYYY is the year, MM the month, DD the day, HH the hour, MM the month and SS the second of creation. + +They will be moved automatically by composer when you install or update a bundle. + +Executing migration files +========================== + +The installers will have to execute migrations files manually, running + +.. code-block:: bash + + php app/console doctrine:migrations:status #will give the current status of the database + php app/console doctrine:migrations:migrate #process the update + + +Updating migration files +========================= + +.. warning:: + + After an installation, migration files will be executed and registered as executed in the database (the version timestamp is recorded into the :title:`migrations_versions` table). If you update your migration file code, the file will still be considered as "executed" by doctrine migration, which will never recommand users to execute the migration again. + + Consequently, updating migration file should only be considered during development phase, and not published on public git branches. If you want to edit your database schema, you should create a new migration file, with a new timestamp, which will proceed to your schema adaptations. + +Every time a migration file is discovered, the composer'script will check if the migration exists in the local migration directory. If yes, the script will compare two file for changes (using a md5 hash). If migrations are discovered, the script will ask the installer to know if he must replace the file or ignore it. + +.. note:: + + You can manually run composer script by launching `composer run-script post-update-cmd` from your root chill installation's directory. + + +.. _doctrine migration: http://www.doctrine-project.org/projects/migrations.html +.. _doctrine migration bundle : http://symfony.com/doc/master/bundles/DoctrineMigrationsBundle/index.html +.. _composer : https://getcomposer.org + +Tips for development +==================== + +Generation +---------- + +You can generate migration file from the command line, using those commands: + +* `php app/console doctrine:migrations:diff` to generate a migration file by comparing your current database to your mapping information +* `php app/console doctrine:migrations:generate` to generate a blank migration file. + +Those files will be located into `app/DoctrineMigrations` directory. You will have to copy those file to your the directory `Resource/migrations` into your bundle directory. + +Comments and documentation +-------------------------- + +As files are copied from your bundle to the `app/DoctrineMigrations` directory, the link between your bundle and the copied file will be unclear. Please add all relevant documentation which will allow future developers to make a link between your file and your bundle. + +Inside the script +----------------- + +The script which move the migrations files to app directory `might be found here `_. From 208bc43e1fd1d1b17305ef2f3394fcf9d8c0ea1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 4 Dec 2014 16:13:11 +0100 Subject: [PATCH 12/28] add step "app/check.php" close #235 --- source/installation/installation.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/source/installation/installation.rst b/source/installation/installation.rst index 493afeaaa..5b7284e07 100644 --- a/source/installation/installation.rst +++ b/source/installation/installation.rst @@ -113,8 +113,16 @@ If composer ask you the following question : :: You may answer `Y` (Yes), or simply press the `return` button. +Check your requirements +^^^^^^^^^^^^^^^^^^^^^^^ -TODO insert 'check.php' +You should check your installation by running + +.. code-block:: bash + + php app/check.php + +Which will give you information about how your installation fullfill the requirements to running Chill, and give you advices to optimize your installation. Launch your server From ec446826a38e7c00dc7e265f11e63050c9a80c79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 4 Dec 2014 16:16:36 +0100 Subject: [PATCH 13/28] typo --- source/installation/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/installation/installation.rst b/source/installation/installation.rst index 5b7284e07..232dc5d3e 100644 --- a/source/installation/installation.rst +++ b/source/installation/installation.rst @@ -36,7 +36,7 @@ You won't need any web server for demonstration or development. Client requirements ^^^^^^^^^^^^^^^^^^^ -Chill is accessible through a web browser. Currently, we focus our support on `Firefox`_, because firefox is open source, cross-platform, and very well active. The software should work with other browser (Chromium, Opera, ...) but some functionalities should break. +Chill is accessible through a web browser. Currently, we focus our support on `Firefox`_, because firefox is open source, cross-platform, and very well active. The software should work with other browser (Chromium, Opera, ...) but some functionalities might break. Preparation ----------- @@ -63,7 +63,7 @@ Install composer on your system : curl -sS https://getcomposer.org/installer | php -move composer.phar to your system +Move composer.phar to your system """"""""""""""""""""""""""""""""" .. note:: From cc6326bc158f2f0578b5da530fe22ba15088e471 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 4 Dec 2014 16:33:54 +0100 Subject: [PATCH 14/28] add reference on how to create the database after installation --- source/index.rst | 1 + source/installation/install_new_bundles.rst | 16 ++++++++ source/installation/installation.rst | 44 +++++++++++++++++++-- 3 files changed, 58 insertions(+), 3 deletions(-) create mode 100644 source/installation/install_new_bundles.rst diff --git a/source/index.rst b/source/index.rst index 3d3a8858f..32b8f4d4a 100644 --- a/source/index.rst +++ b/source/index.rst @@ -24,6 +24,7 @@ Contents of this documentation: :maxdepth: 2 installation/installation.rst + installation/install_new_bundles.rst development/index.rst diff --git a/source/installation/install_new_bundles.rst b/source/installation/install_new_bundles.rst new file mode 100644 index 000000000..85b31d323 --- /dev/null +++ b/source/installation/install_new_bundles.rst @@ -0,0 +1,16 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +.. _install-new-bundles: + +Install new bundles to your installation +######################################## + +.. todo:: + + the section "install new bundles" must be written. Help appreciated :-) diff --git a/source/installation/installation.rst b/source/installation/installation.rst index 232dc5d3e..e1407f4ce 100644 --- a/source/installation/installation.rst +++ b/source/installation/installation.rst @@ -107,11 +107,21 @@ Composer will download `the standard architecture`_ and ask you a few question a You may accept the default parameters of `debug_toolbar`, `debug_redirects` and `use_assetic_controller` for a demonstration installation. For production, set them all to `false`. -If composer ask you the following question : :: +.. note:: - Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? + If composer ask you the following question : :: -You may answer `Y` (Yes), or simply press the `return` button. + Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? + + You may answer `Y` (Yes), or simply press the `return` button. + +.. note:: + + At the end of your installation, composer will warn you to execute database migration script, with this message : :: + + Some migration files have been imported. You should run `php app/console doctrine:migrations:status` and/or `php app/console doctrine:migrations:migrate` to apply them to your DB. + + We will proceed to this step some steps further. See :ref:`create-database-schema`. Check your requirements ^^^^^^^^^^^^^^^^^^^^^^^ @@ -125,6 +135,34 @@ You should check your installation by running Which will give you information about how your installation fullfill the requirements to running Chill, and give you advices to optimize your installation. +.. _create-database-schema: + +Create your database schema +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This step will create your table and minimum information into your database. Simply run + +.. code-block:: bash + + php app/console doctrine:migrations:migrate + +SQL queries will be printed into your console. + + +Populate your database with basic information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once your database schema is ready, you should populate your database with some basic information. Those are provided through scripts and might depends from the bundle you choose to install (see :ref:`install-new-bundles`) + +The main bundle require two scripts to be executed : + +.. code-block:: bash + + php app/console chill:main:countries:populate + php app/console chill:main:languages:populate + +Those will populate database, respectively, with countries (using ISO declaration) and languages (using, also, ISO informations). + Launch your server ^^^^^^^^^^^^^^^^^^ From 7e5945d6a1d84bf8050c3c095cc64b26881bdb98 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 4 Dec 2014 16:41:46 +0100 Subject: [PATCH 15/28] improve documentation hierarchy We create a level into the "installation" directory, and create an index file into this directory. This will also be more consistent with the "developer" part. --- source/index.rst | 3 +-- source/installation/index.rst | 32 ++++++++++++++++++++++++++++ source/installation/installation.rst | 7 +++++- 3 files changed, 39 insertions(+), 3 deletions(-) create mode 100644 source/installation/index.rst diff --git a/source/index.rst b/source/index.rst index 32b8f4d4a..a7db0cb28 100644 --- a/source/index.rst +++ b/source/index.rst @@ -23,8 +23,7 @@ Contents of this documentation: .. toctree:: :maxdepth: 2 - installation/installation.rst - installation/install_new_bundles.rst + installation/index.rst development/index.rst diff --git a/source/installation/index.rst b/source/installation/index.rst new file mode 100644 index 000000000..099628e02 --- /dev/null +++ b/source/installation/index.rst @@ -0,0 +1,32 @@ +.. chill-doc documentation master file, created by + sphinx-quickstart on Sun Sep 28 22:04:08 2014. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +Instructions about installation +################################ + +You will learn here : + +.. toctree:: + :maxdepth: 2 + + How to install the software + Add new bundles to your installation + + +.. todo:: + + We should write a section on "how to update your installation". + +.. todo:: + + We should write a section on "what are the concepts of chill" and explain what is a bundle, why we should install it, how to find them, ... diff --git a/source/installation/installation.rst b/source/installation/installation.rst index e1407f4ce..4aa05a50c 100644 --- a/source/installation/installation.rst +++ b/source/installation/installation.rst @@ -92,6 +92,12 @@ Create your Chill project using composer: php composer.phar create-project chill-project/standard \ path/to/your/directory --stability=dev +You should, now, move your cursor to the new directory + +.. code-block:: bash + + cd path/to/your/directory + .. note:: Until now, the stability of the project is set to "dev". Do not forget this argument, or composer will fail to download and create the project. @@ -170,7 +176,6 @@ If everything was fine, you are able to launch your built-in server : .. code-block:: bash - cd path/to/your/directory php app/console server:run Your server should now be available at `http://localhost:8000`. Type this address on your browser and you should see the homepage. From 8129f156de0d6e230e57bf246aac2025d11e09a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 4 Dec 2014 16:50:53 +0100 Subject: [PATCH 16/28] remove a warning, as I tested the instructions locally --- source/development/installation.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/source/development/installation.rst b/source/development/installation.rst index 85855d187..069d98df9 100644 --- a/source/development/installation.rst +++ b/source/development/installation.rst @@ -80,10 +80,6 @@ You can ignore the locally using the `git update-index --assume-unchanged` comma Working with your own fork ^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. warning:: - - This section has not been tested yet. Feedback wanted. - Ideally, you will work on a fork of the main github repository. To ensure that composer will download the code from **your** repository, you will have to adapt the `composer.json` file accordingly, using your own repository. Add the following lines to your composer.json file if you want to force composer to download from your own repository. This will force to use your own repository for the ChillMain bundle, insert in `composer.json` the following lines : From f2e4146a439e58fb497d4f3de4ab882869357db8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 4 Dec 2014 16:53:19 +0100 Subject: [PATCH 17/28] split text on multiple lines for readability --- source/installation/installation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/installation/installation.rst b/source/installation/installation.rst index 4aa05a50c..1cfc4b43f 100644 --- a/source/installation/installation.rst +++ b/source/installation/installation.rst @@ -125,7 +125,9 @@ You may accept the default parameters of `debug_toolbar`, `debug_redirects` and At the end of your installation, composer will warn you to execute database migration script, with this message : :: - Some migration files have been imported. You should run `php app/console doctrine:migrations:status` and/or `php app/console doctrine:migrations:migrate` to apply them to your DB. + Some migration files have been imported. You should run + `php app/console doctrine:migrations:status` and/or + `php app/console doctrine:migrations:migrate` to apply them to your DB. We will proceed to this step some steps further. See :ref:`create-database-schema`. From ceef7e746efe5c728e0b3f838493949eebbdcd72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 4 Dec 2014 16:57:32 +0100 Subject: [PATCH 18/28] warning about data losing and migration files updating --- source/development/migrations.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/source/development/migrations.rst b/source/development/migrations.rst index 7c3bbf73c..5a3252160 100644 --- a/source/development/migrations.rst +++ b/source/development/migrations.rst @@ -56,7 +56,7 @@ Updating migration files .. warning:: - After an installation, migration files will be executed and registered as executed in the database (the version timestamp is recorded into the :title:`migrations_versions` table). If you update your migration file code, the file will still be considered as "executed" by doctrine migration, which will never recommand users to execute the migration again. + After an installation, migration files will be executed and registered as executed in the database (the version timestamp is recorded into the :title:`migrations_versions` table). If you update your migration file code, the file will still be considered as "executed" by doctrine migration, which will not offers the possibility to run the migration again. Consequently, updating migration file should only be considered during development phase, and not published on public git branches. If you want to edit your database schema, you should create a new migration file, with a new timestamp, which will proceed to your schema adaptations. @@ -74,6 +74,11 @@ Every time a migration file is discovered, the composer'script will check if the Tips for development ==================== +Migration and data +------------------ + +Each time you create a migration script, you should ensure that it will not lead to data losing. Eventually, feel free to use intermediate steps. + Generation ---------- From 30338451463aac8e1884b411b6628ca8f90c1285 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Sun, 4 Jan 2015 22:29:27 +0100 Subject: [PATCH 19/28] Add unaccent requirement --- source/installation/installation.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/source/installation/installation.rst b/source/installation/installation.rst index 1cfc4b43f..8aafc2131 100644 --- a/source/installation/installation.rst +++ b/source/installation/installation.rst @@ -25,7 +25,7 @@ Requirements Server requirements ^^^^^^^^^^^^^^^^^^^^ -* a postgresql database. The minimum version is postgresql 9.3, but we are working on developing on the 9.4 branch, which will provide features which will ease developper work +* a postgresql database, with the `*unaccent* extension`_ enabled. The minimum version is postgresql 9.3, but we are working on developing on the 9.4 branch, which will provide features which will ease developper work * php 5.5 * If you run Chill in production mode, you should also install a web server (apache, ngnix, ...). We may use php built-in server for testing and development. @@ -33,6 +33,10 @@ Within this documentation, we are going to describe installation on Unix systems You won't need any web server for demonstration or development. +.. note:: + + Installing unaccent extension on ther server is possible with the package `postgresql-contrib-9.x` (replace 9.x with your server version). The extension may be enabled with running `CREATE EXTENSION unaccent;` in the database, with a superuser account. + Client requirements ^^^^^^^^^^^^^^^^^^^ @@ -188,3 +192,4 @@ Your server should now be available at `http://localhost:8000`. Type this addres .. _composer: https://getcomposer.org .. _Firefox: https://www.mozilla.org .. _symfony framework: http://symfony.com +.. _*unaccent* extension: http://www.postgresql.org/docs/current/static/unaccent.html From 21485649dbb6453c2dc9cbe0dd321d825b89ca92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Mon, 5 Jan 2015 16:21:14 +0100 Subject: [PATCH 20/28] Documente search terms on person bundl --- source/development/bundles/index.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/development/bundles/index.rst b/source/development/bundles/index.rst index c077c1633..31959ecc6 100644 --- a/source/development/bundles/index.rst +++ b/source/development/bundles/index.rst @@ -12,5 +12,6 @@ Official bundles documentation .. toctree:: :maxdepth: 2 - Main Bundle - Custom Fields + Main bundle + Custom Fields bundle + Person bundle From cd9b95c7ca5229b21dcae7eb514f6823c6c75290 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Mon, 5 Jan 2015 16:29:23 +0100 Subject: [PATCH 21/28] add missing report.rst file --- source/development/bundles/person.rst | 47 +++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 source/development/bundles/person.rst diff --git a/source/development/bundles/person.rst b/source/development/bundles/person.rst new file mode 100644 index 000000000..e4208d01d --- /dev/null +++ b/source/development/bundles/person.rst @@ -0,0 +1,47 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +Person bundle +########### + +This bundle provides the ability to record people in the software. This bundle is required by other bundle + +Entities provided +***************** + +.. todo:: + + describe entities provided by person bundle + + +Search terms +************* + +The class `Chill\PersonBundle\Search\PersonSearch` provide the search module. + +Domain +======= + +The search upon "person" is provided by default. The `@person` domain search may be omitted. + +* `@person` is the domain search for people. + + +Arguments +========= + +* `firstname` : provide the search on firstname. Example : `firstname:Depardieu`. May match part of the firstname (`firsname:dep` will match **Dep**ardieu) +* `lastname` : provide the search on lastname. May match part of the lastname. +* `birthdate` : provide the search on the birthdate. Example : `birthdate:1996-01-19` +* `gender`: performs search on man/woman. The accepted values are `man` or `woman`. +* `nationality` : performs search on nationality. Value must be a country code `as described in ISO 3166 `_. Example : `nationality:FR`. + +Default +======= + +The default search is performed on firstname and/or lastname. Both are concatened before search. If values are separated by spaces, the clause `AND` is used : the search `dep ge` will match '**Gé**rard **Dep**ardieu` or 'Jean **Dep**a**ge**lles', but not 'Charline **Dep**ardieu' (missing 'Ge' in word). From 6ea5a9227d302212df144b9fe25edac62c7d4326 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 15 Jan 2015 09:27:38 +0100 Subject: [PATCH 22/28] move bundle directory at root This should ease the browsing fo documentation (less menu and submenus) --- source/{development => }/bundles/custom-fields.rst | 0 source/{development => }/bundles/index.rst | 9 ++++++++- source/{development => }/bundles/main.rst | 0 source/{development => }/bundles/person.rst | 0 source/development/index.rst | 1 - source/index.rst | 1 + 6 files changed, 9 insertions(+), 2 deletions(-) rename source/{development => }/bundles/custom-fields.rst (100%) rename source/{development => }/bundles/index.rst (63%) rename source/{development => }/bundles/main.rst (100%) rename source/{development => }/bundles/person.rst (100%) diff --git a/source/development/bundles/custom-fields.rst b/source/bundles/custom-fields.rst similarity index 100% rename from source/development/bundles/custom-fields.rst rename to source/bundles/custom-fields.rst diff --git a/source/development/bundles/index.rst b/source/bundles/index.rst similarity index 63% rename from source/development/bundles/index.rst rename to source/bundles/index.rst index 31959ecc6..9b7921acc 100644 --- a/source/development/bundles/index.rst +++ b/source/bundles/index.rst @@ -6,12 +6,19 @@ A copy of the license is included in the section entitled "GNU Free Documentation License". -Official bundles documentation +Bundles documentation ############################### +You will find here documentation about bundles working with Chill. + .. toctree:: :maxdepth: 2 Main bundle Custom Fields bundle Person bundle + +Your bundle here ? +------------------- + +The contributors still do not have a policy about those bundle integration, but we would like to be very open on this subject. Please write to us `or open an issue `_. diff --git a/source/development/bundles/main.rst b/source/bundles/main.rst similarity index 100% rename from source/development/bundles/main.rst rename to source/bundles/main.rst diff --git a/source/development/bundles/person.rst b/source/bundles/person.rst similarity index 100% rename from source/development/bundles/person.rst rename to source/bundles/person.rst diff --git a/source/development/index.rst b/source/development/index.rst index 2fb60d60d..356ff124d 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -21,7 +21,6 @@ As Chill rely on the `symfony `_ framework, reading the fram Database migrations Testing manual/index.rst - Official bundle's documentation Help, I am lost ! diff --git a/source/index.rst b/source/index.rst index a7db0cb28..20825f23d 100644 --- a/source/index.rst +++ b/source/index.rst @@ -25,6 +25,7 @@ Contents of this documentation: installation/index.rst development/index.rst + Bundles Contribute From 9762df463f5a685ed87fcb603459312e4f703f81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 15 Jan 2015 15:34:46 +0100 Subject: [PATCH 23/28] Documentation about search refs #223 and refs #377 --- source/development/index.rst | 1 + source/development/searching.rst | 250 +++++++++++++++++++++++++++++++ 2 files changed, 251 insertions(+) create mode 100644 source/development/searching.rst diff --git a/source/development/index.rst b/source/development/index.rst index 356ff124d..eb5f2f7bf 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -19,6 +19,7 @@ As Chill rely on the `symfony `_ framework, reading the fram Menus Message to users Database migrations + Searching Testing manual/index.rst diff --git a/source/development/searching.rst b/source/development/searching.rst new file mode 100644 index 000000000..c033c0e17 --- /dev/null +++ b/source/development/searching.rst @@ -0,0 +1,250 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + + +Searching +********* + +Chill should provide information needed by users when they need it. Searching within bundle, entities,... is an important feature to achieve this goal. + +The Main Bundle provide interfaces to ease the developer work. It will also attempt that search will work in the same way accross bundles. + +.. contents:: Table of content + :local: + +.. seealso:: + + `Our blog post about searching (in French) `_ + This blog post give some information for end-users about searching. + + `The issue about search behaviour `_ + Where the search behaviour is defined. + +Searching in a glance for developers +==================================== + +Chill suggests to use an easy-to-learn language search. + +.. note:: + + We are planning to provide a form to create automatically search pattern according to this language. Watch the `issue regarding this feature `_. + +The language is an association of search terms. Search terms may contains : + +- **a domain**: this is "the domain you want to search" : it may some entities like people, reports, ... Example : `@person` to search accross people, `@report` to browse reports, ... The search pattern may have **a maximum of one** domain by search, providing more should throw an error, and trigger a warning for users. +- **arguments and their values** : This is "what you search". Arguments narrow the search to specific fields : username, date of birth, nationality, ... The syntax is `argument:value`. I.e.: ` birthdate:2014-12-15`, `firstname:Depardieu`, ... **Arguments are optional**. If the value of an argument contains spaces or characters like punctuation, quotes ("), the value should be provided between parenthesis : `firstname:(Van de snoeck)`, `firstname:(M'bola)`, ... +- **default value** : this the "rest" of the search, not linked with any arguments or domain. Example : `@person dep` (`dep` is the "default value"), or simply `dep` if any domain is provided (which is perfectly acceptable). If a string is not idenfied as argument or domain, it will be present in the "default" term. + +If a search pattern (provided by the user) does not contains any domain, the search must be run across default domain/search modules. + +A domain may be supported by different search modules. For instance, if you provide the domain `@person`, the end-user may receive results of exact firstname/lastname, but also result with spelling suggestion, ... **But** if results do not fit into the first page (if you have 75 results and the screen show only 50 results), the next page should contains only the results from the required module. + +For instance : a user search across people by firstname/lastname, the exact spelling contains 10 results, the "spelling suggestion" results contains 75 names, but show only the first 50. If the user want to see the last 25, the next screen should not contains the results by firstname/lastname. + +Allowed characters as arguments +=============================== + +In order to execute regular expression, the allowed chararcters in arguments are a-z characters, numbers, and the sign '-'. Spaces and special characters like accents are note allowed (the accents are removed during parsing). + +Special characters and uppercase +================================ + +The search should not care about lowercase/uppercase and accentued characters. Currently, they are removed automatically by the `chill.main.search_provider`. + +Implementing search module for dev +=================================== + +To implement a search module, you should : + +- create a class which implements the `Chill\MainBundle\Search\SearchInterface` class. An abstract class `Chill\MainBundle\Search\AbstractSearch` will provide useful assertions for parsing date string to `DateTime` objects, ... +- register the class as a service, and tag the service with `chill.search` and an appropriate alias + +The search logic is provided under the `/search` route. + +.. seealso:: + + `The implementation of a search module in Person bundle `_ + An example of implementationhttps://github.com/Chill-project/Main/blob/master/DependencyInjection/SearchableServicesCompilerPass.php + +.. note:: + + **Internals explained** : the services tagged with `chill.search` are gathered into the `chill.main.search_provider` service during compilation (`see the compiler pass `_). + + The `chill.main.search_provider` service allow to : + + - retrieve all results (as html string) for all search module concerned by the search (according to the domain provided or modules marked as default) + - retrieve result for one search module + +The SearchInterface class +------------------------- + +.. code-block:: php + + namespace Chill\PersonBundle\Search; + + use Chill\MainBundle\Search\AbstractSearch; + use Doctrine\ORM\EntityManagerInterface; + use Chill\PersonBundle\Entity\Person; + use Symfony\Component\DependencyInjection\ContainerInterface; + use Symfony\Component\DependencyInjection\ContainerAware; + use Symfony\Component\DependencyInjection\ContainerAwareTrait; + use Chill\MainBundle\Search\ParsingException; + + class PersonSearch extends AbstractSearch + { + + // indicate which domain you support + // you may respond TRUE to multiple domain, according to your logic + public function supports($domain) + { + return 'person' === $domain; + } + + // if your domain must be called when no domain is provided, should return true + public function isActiveByDefault() + { + return true; + } + + // if multiple module respond to the same domain, indicate an order for your search. + public function getOrder() + { + return 100; + } + + + // This is where your search logic should be executed. + // This method must return an HTML string (a string with HTML tags) + // see below about the structure of the $term array + public function renderResult(array $terms, $start = 0, $limit = 50, array $options = array()) + { + return $this->container->get('templating')->render('ChillPersonBundle:Person:list.html.twig', + array( + // you should implements the `search` function somewhere :-) + 'persons' => $this->search($terms, $start, $limit, $options), + // recomposePattern is available in AbstractSearch class + 'pattern' => $this->recomposePattern($terms, array('nationality', + 'firstname', 'lastname', 'birthdate', 'gender'), $terms['_domain']), + // you should implement the `count` function somewhere :-) + 'total' => $this->count($terms) + )); + } + } + + +Structure of array `$term` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The array term is parsed automatically by the `main.chill.search_provider` service. + +.. note:: + If you need to parse a search pattern, you may use the function `parse($pattern)` provided by the service. + +The array `$term` have the following structure after parsing : + +.. code-block:: php + + array( + '_domain' => 'person', //the domain, without the '@' + 'argument1' => 'value', //the argument1, with his value + 'argument2' => 'my value with spaces', //the argument2 + '_default' => 'abcde ef' // the default term + ); + +The original search would have been : `@person argument1:value argument2:(my value with spaces) abcde ef` + +.. warning:: + The search values are always unaccented. + +Register the service +-------------------- + +You should add your service in the configuration, and add a `chill.search` tag and an alias. + +Example : + +.. code-block:: yaml + + services: + chill.person.search_person: + class: Chill\PersonBundle\Search\PersonSearch + #your logic here + tags: + - { name: chill.search, alias: 'person_regular' } + +The alias will be used to get the results narrowed to this search module, in case of pagination (see above). + +Parsing date +============ + +The class `Chill\MainBundle\Search\AbstractSearch` provides a method to parse date : + +.. code-block:: php + + //from subclasses + $date = $this->parseDate($string); + +`$date` will be an instance of `DateTime `_. + +.. seealso:: + + `The possibility to add periods instead of date `_ + Which may be a future improvement for search with date. + +Exceptions +========== + +The logic of the search is handled by the controller for the `/search` path. + +You should throw those Exception from your instance of `SearchInterface` if needed : + +Chill\MainBundle\Search\ParsingException + If the terms does not fit your search logic (for instance, conflicting terms) + +Expected behaviour +================== + +Operators between multiple terms +-------------------------------- + +Multiple terms should be considered are "AND" instructions : + +@person nationality:RU firstname:dep + the people having the Russian nationality AND having DEP in their name + +@person birthdate:2015-12-12 charles + the people having 'charles' in their name or firstname AND born on December 12 2015 + +Spaces in default +----------------- + +Spaces in default terms should be considered as "AND" instruction + +@person charle dep + people having "dep" AND "charles" in their firstname or lastname. Match "Charles Depardieu" but not "Gérard Depardieu" ('charle' is not present) + +Rendering +--------- + +The rendering should contains : + +- the total number of results ; +- the search pattern in the search language. The aim of this is to let users learn the search language easily. +- a title + +Frequently Asked Questions (FAQ) +================================ + +Why renderResults returns an HTML string and not structured array ? + It seems that the form of results may vary (according to access-right logic, ...) and is not easily structurable + + + + + + From f2ea3edf293b8f504675773c6230effef0ce7979 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 15 Jan 2015 15:45:30 +0100 Subject: [PATCH 24/28] add a table of content for person bundle page and fixe some errors in rst syntax --- source/bundles/person.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/source/bundles/person.rst b/source/bundles/person.rst index e4208d01d..091b00758 100644 --- a/source/bundles/person.rst +++ b/source/bundles/person.rst @@ -7,9 +7,12 @@ Free Documentation License". Person bundle -########### +############# -This bundle provides the ability to record people in the software. This bundle is required by other bundle +This bundle provides the ability to record people in the software. This bundle is required by other bundle. + +.. contents:: Table of content + :local: Entities provided ***************** @@ -35,7 +38,7 @@ The search upon "person" is provided by default. The `@person` domain search may Arguments ========= -* `firstname` : provide the search on firstname. Example : `firstname:Depardieu`. May match part of the firstname (`firsname:dep` will match **Dep**ardieu) +* `firstname` : provide the search on firstname. Example : `firstname:Depardieu`. May match part of the firstname (`firsname:dep` will match Depardieu) * `lastname` : provide the search on lastname. May match part of the lastname. * `birthdate` : provide the search on the birthdate. Example : `birthdate:1996-01-19` * `gender`: performs search on man/woman. The accepted values are `man` or `woman`. @@ -44,4 +47,4 @@ Arguments Default ======= -The default search is performed on firstname and/or lastname. Both are concatened before search. If values are separated by spaces, the clause `AND` is used : the search `dep ge` will match '**Gé**rard **Dep**ardieu` or 'Jean **Dep**a**ge**lles', but not 'Charline **Dep**ardieu' (missing 'Ge' in word). +The default search is performed on firstname and/or lastname. Both are concatened before search. If values are separated by spaces, the clause `AND` is used : the search `dep ge` will match 'Gérard Depardieu` or 'Jean Depagelles', but not 'Charline Depardieu' (missing 'Ge' in word). From d1140ba6d3ddcdf110e2110e83f035ac9a4a8f3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 15 Jan 2015 15:53:08 +0100 Subject: [PATCH 25/28] documentation about search in reports --- source/bundles/index.rst | 1 + source/bundles/report.rst | 44 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 source/bundles/report.rst diff --git a/source/bundles/index.rst b/source/bundles/index.rst index 9b7921acc..2d05286c7 100644 --- a/source/bundles/index.rst +++ b/source/bundles/index.rst @@ -17,6 +17,7 @@ You will find here documentation about bundles working with Chill. Main bundle Custom Fields bundle Person bundle + Report bundle Your bundle here ? ------------------- diff --git a/source/bundles/report.rst b/source/bundles/report.rst new file mode 100644 index 000000000..524606353 --- /dev/null +++ b/source/bundles/report.rst @@ -0,0 +1,44 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +Report bundle +############# + +This bundle provides the ability to record report about people. We use custom fields to let user add fields to reports. + +.. contents:: Table of content + :local: + +.. todo:: + + The documentation about report is not writtend + +Concepts +======== + + +Search +====== + +Domain +------ + +* `@report` is the domain search for reports. + + +Arguments +--------- + +* `date` : The date of the report + +Default +------- + +The report's date is the default value. + +An error is thrown if an argument `date` and a default is used. From ab36443943ccba69420b99883c79edda5b826a5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Thu, 22 Jan 2015 17:35:37 +0100 Subject: [PATCH 26/28] documentation for routing refs #273 --- source/development/index.rst | 1 + source/development/routing.rst | 68 ++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 source/development/routing.rst diff --git a/source/development/index.rst b/source/development/index.rst index eb5f2f7bf..68b5d62f2 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -16,6 +16,7 @@ As Chill rely on the `symfony `_ framework, reading the fram Install Chill for development Instructions to create a new bundle + Routing Menus Message to users Database migrations diff --git a/source/development/routing.rst b/source/development/routing.rst new file mode 100644 index 000000000..519490918 --- /dev/null +++ b/source/development/routing.rst @@ -0,0 +1,68 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + + +Routing +####### + +Our goal is to ease the installation of the different bundle. Users should not have to dive into complicated config files to install bundles. + +A routing loader available for all bundles +=========================================== + +A Chill bundle may rely on the Routing Loader defined in ChillMain. + +The loader will load `yml` or `xml` files. You simply have to add them into `chill_main` config + +.. code-block:: yaml + + chill_main: + # ... other stuff here + routing: + resources: + - @ChillMyBundle/Resources/config/routing.yml + +Load routes automatically +------------------------- + +But this force users to modify config files. To avoid this, you may prepend config implementing the `PrependExtensionInterface` in the `YourBundleExtension` class. This is an example from **chill main** bundle : + + +.. code-block:: php + + namespace Chill\MainBundle\DependencyInjection; + + use Symfony\Component\DependencyInjection\ContainerBuilder; + use Symfony\Component\HttpKernel\DependencyInjection\Extension; + use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface; + + class ChillMainExtension extends Extension implements PrependExtensionInterface + { + + public function load(array $configs, ContainerBuilder $container) + { + // ... + } + + public function prepend(ContainerBuilder $container) + { + + //add current route to chill main + //this is where the resource is added automatically in the config + $container->prependExtensionConfig('chill_main', array( + 'routing' => array( + 'resources' => array( + '@ChillMainBundle/Resources/config/routing.yml' + ) + + ) + )); + } + } + + From 458a2e71a5aed948c72c13aa0d4d25567890ff3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Fri, 23 Jan 2015 15:01:47 +0100 Subject: [PATCH 27/28] add doc for date localisation Introduce the twig Intl extension and make ref to the doc. refs #272 --- source/development/index.rst | 1 + source/development/localisation.rst | 29 +++++++++++++++++++++++++++++ 2 files changed, 30 insertions(+) create mode 100644 source/development/localisation.rst diff --git a/source/development/index.rst b/source/development/index.rst index 68b5d62f2..a5b832b36 100644 --- a/source/development/index.rst +++ b/source/development/index.rst @@ -19,6 +19,7 @@ As Chill rely on the `symfony `_ framework, reading the fram Routing Menus Message to users + Localisation Database migrations Searching Testing diff --git a/source/development/localisation.rst b/source/development/localisation.rst new file mode 100644 index 000000000..04cb54b89 --- /dev/null +++ b/source/development/localisation.rst @@ -0,0 +1,29 @@ +.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +Localisation +************* + +Date and time +============== + +The `Intl extension `_ is enabled on the Chill application. + +You may format date and time using the `localizeddate` function : + +.. code-block:: jinja + + date|localizeddate('long', 'none') + +By default, we prefer using the `long` format for date formatting. + +.. seealso:: + + `Documentation for Intl Extension `_ + Read the complete doc for the Intl extension. + From 74bf42e350935afa7e3d50cc49ec7941cca7ac6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Fri, 23 Jan 2015 15:19:14 +0100 Subject: [PATCH 28/28] documentation for locale in url close #288 --- source/development/localisation.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/source/development/localisation.rst b/source/development/localisation.rst index 04cb54b89..fca5ad8ba 100644 --- a/source/development/localisation.rst +++ b/source/development/localisation.rst @@ -9,6 +9,26 @@ Localisation ************* +Language in url +=============== + +Language should be present in URL, conventionnaly as first argument. + +.. code-block:: none + + /fr/your/url/here + +This allow users to change from one language to another one on each page, which may be useful in multilanguages teams. If the installation is single-language, the language switcher will not appears. + +This is an example of routing defined in yaml : + +.. code-block:: yaml + + chill_person_general_edit: + pattern: /{_locale}/person/{person_id}/general/edit + defaults: {_controller: ChillPersonBundle:Person:edit } + + Date and time ==============