Permalink
Browse files

Use fenced code blocks instead of highlight tags

Rely on Markdown's fenced code blocks instead of Jekyll Liquid tag
  • Loading branch information...
1 parent db17449 commit a4028a011976e9b6f73e3a6f66795a09e55da7c5 @robin850 committed Jun 9, 2013
Showing with 1,343 additions and 1,342 deletions.
  1. +12 −12 documentation/behaviors/aggregate-column.markdown
  2. +6 −6 documentation/behaviors/alternative-coding-standards.markdown
  3. +32 −32 documentation/behaviors/archivable.markdown
  4. +12 −12 documentation/behaviors/auto-add-pk.markdown
  5. +18 −18 documentation/behaviors/delegate.markdown
  6. +22 −22 documentation/behaviors/i18n.markdown
  7. +36 −36 documentation/behaviors/nested-set.markdown
  8. +10 −10 documentation/behaviors/query-cache.markdown
  9. +18 −18 documentation/behaviors/sluggable.markdown
  10. +34 −34 documentation/behaviors/sortable.markdown
  11. +12 −12 documentation/behaviors/timestampable.markdown
  12. +56 −56 documentation/behaviors/validate.markdown
  13. +24 −24 documentation/behaviors/versionable.markdown
  14. +26 −26 documentation/contribute.markdown
  15. +6 −6 documentation/cookbook/adding-additional-sql-files.markdown
  16. +4 −4 documentation/cookbook/copying-persisted-objects.markdown
  17. +18 −18 documentation/cookbook/customizing-build.markdown
  18. +4 −4 documentation/cookbook/dbdesigner.markdown
  19. +33 −32 documentation/cookbook/multi-component-data-model.markdown
  20. +16 −16 documentation/cookbook/namespaces.markdown
  21. +10 −10 documentation/cookbook/replication.markdown
  22. +26 −26 documentation/cookbook/runtime-introspection.markdown
  23. +18 −18 documentation/cookbook/symfony1/how-to-use-Propel i18n-behavior-with-sf1.4.markdown
  24. +18 −18 documentation/cookbook/symfony1/how-to-use-old-SfPropelBehaviori18n-with-sf1.4.markdown
  25. +26 −26 documentation/cookbook/symfony2/mastering-symfony2-forms-with-propel.markdown
  26. +29 −29 documentation/cookbook/symfony2/symfony2-and-propel-in-real-life.markdown
  27. +8 −8 documentation/cookbook/symfony2/the-symfony2-security-component-and-propel.markdown
  28. +22 −22 documentation/cookbook/symfony2/working-with-symfony2.markdown
  29. +29 −29 documentation/cookbook/using-mssql-server.markdown
  30. +12 −12 documentation/cookbook/using-sql-schemas.markdown
  31. +20 −20 documentation/cookbook/working-with-advanced-column-types.markdown
  32. +18 −18 documentation/cookbook/working-with-existing-databases.markdown
  33. +34 −34 documentation/cookbook/writing-behavior.markdown
  34. +20 −20 documentation/documentation/01-installation.markdown
  35. +36 −36 documentation/documentation/02-buildtime.markdown
  36. +48 −48 documentation/documentation/03-basic-crud.markdown
  37. +48 −48 documentation/documentation/04-relationships.markdown
  38. +24 −24 documentation/documentation/06-transactions.markdown
  39. +44 −44 documentation/documentation/07-behaviors.markdown
  40. +40 −40 documentation/documentation/08-logging.markdown
  41. +38 −38 documentation/documentation/09-inheritance.markdown
  42. +36 −36 documentation/documentation/10-migrations.markdown
  43. +64 −64 documentation/documentation/whats-new.markdown
  44. +10 −10 documentation/download.markdown
  45. +2 −2 documentation/index.markdown
  46. +58 −58 documentation/reference/active-record.markdown
  47. +18 −18 documentation/reference/buildtime-configuration.markdown
  48. +124 −124 documentation/reference/model-criteria.markdown
  49. +30 −30 documentation/reference/runtime-configuration.markdown
  50. +34 −34 documentation/reference/schema.markdown
@@ -11,7 +11,7 @@ The `aggregate_column` behavior keeps a column updated using an aggregate functi
In the `schema.xml`, use the `<behavior>` tag to add the `aggregate_column` behavior to a table. You must provide parameters for the aggregate column `name`, the foreign table name, and the aggregate `expression`. For instance, to add an aggregate column keeping the comment count in a `post` table:
-{% highlight xml %}
+```xml
<table name="post">
<column name="id" type="INTEGER" required="true" primaryKey="true" autoIncrement="true" />
<column name="title" type="VARCHAR" required="true" primaryString="true" />
@@ -28,11 +28,11 @@ In the `schema.xml`, use the `<behavior>` tag to add the `aggregate_column` beha
<reference local="post_id" foreign="id" />
</foreign-key>
</table>
-{% endhighlight %}
+```
Rebuild your model, and insert the table creation sql again. The model now has an additional `nb_comments` column, of type `integer` by default. And each time an record from the foreign table is added, modified, or removed, the aggregate column is updated:
-{% highlight php %}
+```php
<?php
$post = new Post();
$post->setTitle('How Is Life On Earth?');
@@ -48,23 +48,23 @@ $comment2->save();
echo $post->getNbComments(); // 2
$comment2->delete();
echo $post->getNbComments(); // 1
-{% endhighlight %}
+```
The aggregate column is also kept up to date when related records get modified through a Query object:
-{% highlight php %}
+```php
<?php
CommentQuery::create()
->filterByPost($post)
->delete():
echo $post->getNbComments(); // 0
-{% endhighlight %}
+```
## Customizing The Aggregate Calculation ##
Any aggregate function can be used on any of the foreign columns. For instance, you can use the `aggregate_column` behavior to keep the latest update date of the related comments, or the total votes on the comments. You can even keep several aggregate columns in a single table:
-{% highlight xml %}
+```xml
<table name="post">
<column name="id" type="INTEGER" required="true" primaryKey="true" autoIncrement="true" />
<column name="title" type="VARCHAR" required="true" primaryString="true" />
@@ -93,11 +93,11 @@ Any aggregate function can be used on any of the foreign columns. For instance,
<column name="created_at" type="TIMESTAMP" />
<column name="vote" type="INTEGER" />
</table>
-{% endhighlight %}
+```
The behavior adds a `computeXXX()` method to the `Post` class to compute the value of the aggregate function. This method, called each time records are modified in the related `comment` table, is the translation of the behavior settings into a SQL query:
-{% highlight php %}
+```php
<?php
// in om/BasePost.php
public function computeNbComments(PropelPDO $con)
@@ -107,15 +107,15 @@ public function computeNbComments(PropelPDO $con)
$stmt->execute();
return $stmt->fetchColumn();
}
-{% endhighlight %}
+```
You can override this method in the model class to customize the aggregate column calculation.
## Customizing The Aggregate Column ##
By default, the behavior adds one columns to the model. If this column is already described in the schema, the behavior detects it and doesn't add it a second time. This can be useful if you need to use a custom `type` or `phpName` for the aggregate column:
-{% highlight xml %}
+```xml
<table name="post">
<column name="id" type="INTEGER" required="true" primaryKey="true" autoIncrement="true" />
<column name="title" type="VARCHAR" required="true" primaryString="true" />
@@ -126,4 +126,4 @@ By default, the behavior adds one columns to the model. If this column is alread
<parameter name="expression" value="COUNT(id)" />
</behavior>
</table>
-{% endhighlight %}
+```
@@ -10,17 +10,17 @@ The `alternative_coding_standards` behavior changes the coding standards of the
## Basic Usage ##
In the `schema.xml`, use the `<behavior>` tag to add the `alternative_coding_standards` behavior to a table:
-{% highlight xml %}
+```xml
<table name="book">
<column name="id" required="true" primaryKey="true" autoIncrement="true" type="INTEGER" />
<column name="title" type="VARCHAR" required="true" primaryString="true" />
<behavior name="alternative_coding_standards" />
</table>
-{% endhighlight %}
+```
Rebuild your model, and you're ready to go. The code of the model classes now uses an alternative set of coding standards:
-{% highlight php %}
+```php
<?php
// in om/BaseBook.php
/**
@@ -66,15 +66,15 @@ Rebuild your model, and you're ready to go. The code of the model classes now us
return $this;
} // setTitle()
-{% endhighlight %}
+```
The behavior replaces tabulations by whitespace (2 spaces by default), places opening brackets on newlines, removes closing brackets comments, and can even strip every comments in the generated classes if you wish.
## Parameters ##
Each of the new coding style rules has corresponding parameter in the behavior description. Here is the default configuration:
-{% highlight xml %}
+```xml
<table name="book">
<column name="id" required="true" primaryKey="true" autoIncrement="true" type="INTEGER" />
<column name="title" type="VARCHAR" required="true" primaryString="true" />
@@ -86,6 +86,6 @@ Each of the new coding style rules has corresponding parameter in the behavior d
<parameter name="strip_comments" value="false" />
</behavior>
</table>
-{% endhighlight %}
+```
You can change these settings to better match your own coding styles.
@@ -11,52 +11,52 @@ The `archivable` behavior gives model objects the ability to be copied to an arc
In the `schema.xml`, use the `<behavior>` tag to add the `archivable` behavior to a table:
-{% highlight xml %}
+```xml
<table name="book">
<column name="id" required="true" primaryKey="true" autoIncrement="true" type="INTEGER" />
<column name="title" type="VARCHAR" required="true" primaryString="true" />
<behavior name="archivable" />
</table>
-{% endhighlight %}
+```
Rebuild your model, insert the table creation sql again, and you're ready to go. The model now has one new table, `book_archive`, with the same columns as the original `book` table. This table stores the archived `books` together with their archive date. To archive an object, call the `archive()` method:
-{% highlight php %}
+```php
<?php
$book = new Book();
$book->setTitle('War And Peace');
$book->save();
// copy the current Book to a BookArchive object and save it
$archivedBook = $book->archive();
-{% endhighlight %}
+```
The archive table contains only the freshest copy of each archived objects. Archiving an object twice doesn't create a new record in the archive table, but updates the existing archive.
The `book_archive` table has generated ActiveRecord and ActiveQuery classes, so you can browse the archive at will. The archived objects have the same primary key as the original objects. In addition, they contain an `ArchivedAt` property storing the date where the object was archived.
-{% highlight php %}
+```php
<?php
// find the archived book
$archivedBook = BookArchiveQuery::create()->findPk($book->getId());
echo $archivedBook->getTitle(); // 'War And Peace'
echo $archivedBook->getArchivedAt(); // 2011-08-23 18:14:23
-{% endhighlight %}
+```
The ActiveRecord class of an `archivable` model has more methods to deal with the archive:
-{% highlight php %}
+```php
// restore an object to the state it had when last archived
$book->restoreFromArchive();
// find the archived version of an existing book
$archivedBook = $book->getArchive();
// populate a book based on an archive
$book = new book();
$book->populateFromArchive($archivedBook);
-{% endhighlight %}
+```
By default, an `archivable` model is archived just before deletion:
-{% highlight php %}
+```php
<?php
$book = new Book();
$book->setTitle('Sense and Sensibility');
@@ -67,48 +67,48 @@ echo BookQuery::create()->count(); // 0
// find the archived book
$archivedBook = BookArchiveQuery::create()
->findOneByTitle('Sense and Sensibility');
-{% endhighlight %}
+```
>**Tip**<br />The behavior does not take care of archiving the related objects. This may be surprising on deletions if the deleted object has 'ON DELETE CASCADE' foreign keys. If you want to archive relations, override the generated `archive()` method in the ActiveRecord class with your custom logic.
To recover deleted objects, use `populateFromArchive()` on a new object and save it:
-{% highlight php %}
+```php
<?php
// create a new object based on the archive
$book = new Book();
$book->populateFromArchive($archivedBook);
$book->save();
echo $book->getTitle(); // 'Sense and Sensibility'
-{% endhighlight %}
+```
If you want to delete an `archivable` object without archiving it, use the `deleteWithoutArchive()` method generated by the behavior:
-{% highlight php %}
+```php
<?php
// delete the book but don't archive it
$book->deleteWithoutArchive();
-{% endhighlight %}
+```
## Archiving A Set Of Objects ##
The `archivable` behavior also generates an `archive()` method on the generated ActiveQuery class. That means you can easily archive a set of objects, in the same way you archive a single object:
-{% highlight php %}
+```php
<?php
// archive all books having a title starting with "war"
$nbArchivedObjects = BookQuery::create()
->filterByTitle('War%')
->archive();
-{% endhighlight %}
+```
`archive()` returns the number of archived objects, and not the current ActiveQuery object, so it's a termination method.
>**Tip**<br />Since the `archive()` method doesn't duplicate archived objects, it must iterate over the results of the query to check whether each object has already been archived. In practice, `archive()` issues 2n+1 database queries, where `n` is the number of results of the query as returned by a `count()`.
As explained earlier, an `archivable` model is archived just before deletion by default. This is also true when using the `delete()` and `deleteAll()` methods of the ActiveQuery class:
-{% highlight php %}
+```php
<?php
// delete and archive all books having a title starting with "war"
$nbDeletedObjects = BookQuery::create()
@@ -126,13 +126,13 @@ $nbDeletedObjects = BookQuery::create()
->filterByTitle('War%')
->setArchiveOnDelete(false)
->delete();
-{% endhighlight %}
+```
## Archiving on Insert, Update, or Delete ##
As explained earlier, the `archivable` behavior archives objects on deletion by default, but insertions and updates don't trigger the `archive()` method. You can disable the auto archiving on deletion, as well as enable it for insertion and update, in the behavior `<parameter>` tags. Here is the default configuration:
-{% highlight xml %}
+```xml
<table name="book">
<column name="id" required="true" primaryKey="true" autoIncrement="true" type="INTEGER" />
<column name="title" type="VARCHAR" required="true" primaryString="true" />
@@ -142,27 +142,27 @@ As explained earlier, the `archivable` behavior archives objects on deletion by
<parameter name="archive_on_delete" value="true" />
</behavior>
</table>
-{% endhighlight %}
+```
If you turn on `archive_on_insert`, a call to `save()` on a new ActiveRecord object archives it - unless you call `saveWithoutArchive()`.
If you turn on `archive_on_update`, a call to `save()` on an existing ActiveRecord object archives it, and a call to `update()` on an ActiveQuery object archives the results as well. You can still use `saveWithoutArchive()` on the ActiveRecord class and `updateWithoutArchive()` on the ActiveQuery class to skip archiving on updates.
Of course, even if `archive_on_insert` or any of the similar parameters isn't turned on, you can always archive manually an object after persisting it by simply calling `archive()`:
-{% highlight php %}
+```php
<?php
// create a new object, save it, and archive it
$book = new Book();
$book->save();
$book->archive();
-{% endhighlight %}
+```
## Archiving To Another Database ##
The behavior can use another database connection for the archive table, to make it safer. To allow cross-database archives, you must declare the archive schema manually in another XML schema, and reference the archive class on in the behavior parameter:
-{% highlight xml %}
+```xml
<database name="main">
<table name="book">
<column name="id" required="true" primaryKey="true" autoIncrement="true" type="INTEGER" />
@@ -179,7 +179,7 @@ The behavior can use another database connection for the archive table, to make
<column name="archived_at" type="TIMESTAMP" />
</table>
</database>
-{% endhighlight %}
+```
The archive table must have the same columns as the archivable table, but without autoIncrements, and without foreign keys.
@@ -189,7 +189,7 @@ With this setup, the behavior uses `MyBookArchive` and `MyBookArchiveQuery` for
If you use `archivable` as a replacement for the `soft_delete` behavior, here is how you should update your code:
-{% highlight php %}
+```php
<?php
// do a soft delete
$book->delete(); // with soft_delete
@@ -218,32 +218,32 @@ $book->unDelete();
$book = new Book();
$book->populateFromArchive($bookArchive);
$book->save();
-{% endhighlight %}
+```
## Additional Parameters ##
You can change the name of the archive table added by the behavior by setting the `archive_table` parameter. If the table doesn't exist, the behavior creates it for you.
-{% highlight xml %}
+```xml
<behavior name="archivable">
<parameter name="archive_table" value="special_book_archive" />
</behavior>
-{% endhighlight %}
+```
>**Tip**<br />The `archive_table` and `archive_class` parameters are mutually exclusive. You can only use either one of the two.
You can also change the name of the column storing the archive date:
-{% highlight xml %}
+```xml
<behavior name="archivable">
<parameter name="archived_at_column" value="archive_date" />
</behavior>
-{% endhighlight %}
+```
Alternatively, you can disable the addition of an archive date column altogether:
-{% highlight xml %}
+```xml
<behavior name="archivable">
<parameter name="log_archived_at" value="false" />
</behavior>
-{% endhighlight %}
+```
Oops, something went wrong.

0 comments on commit a4028a0

Please sign in to comment.