Skip to content

Commit

Permalink
Convert all highlight tags to markdown fenced code blocks
Browse files Browse the repository at this point in the history
Since Github:pages support fenced code blocks
  • Loading branch information
robin850 committed Mar 12, 2013
1 parent a0918e1 commit ec941c4
Show file tree
Hide file tree
Showing 49 changed files with 1,272 additions and 1,268 deletions.
3 changes: 3 additions & 0 deletions _config.yml
@@ -1,2 +1,5 @@
pygments: true
permalink: none
markdown: redcarpet
redcarpet:
extensions: ["tables", "no_intra_emphasis"]
32 changes: 16 additions & 16 deletions behaviors/aggregate-column.markdown
Expand Up @@ -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 aggegate `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" />
Expand All @@ -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?');
Expand All @@ -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" />
Expand Down Expand Up @@ -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)
Expand All @@ -107,7 +107,7 @@ 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.

Expand All @@ -116,7 +116,7 @@ You can override this method in the model class to customize the aggregate colum
What if you use your own soft deletion and want to calculate only comments which are not marked as deleted?
It is possible to add a custom SQL condition:

{% 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" />
Expand All @@ -127,11 +127,11 @@ It is possible to add a custom SQL condition:
<parameter name="condition" value="is_deleted = false" />
</behavior>
</table>
{% endhighlight %}
```

Which will result in generated SQL query:

{% highlight php %}
```php
<?php
// in om/BasePost.php
public function computeNbComments(PropelPDO $con)
Expand All @@ -141,13 +141,13 @@ public function computeNbComments(PropelPDO $con)
$stmt->execute();
return $stmt->fetchColumn();
}
{% endhighlight %}
```

## 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" />
Expand All @@ -158,4 +158,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 %}
```
12 changes: 6 additions & 6 deletions behaviors/alternative-coding-standards.markdown
Expand Up @@ -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
/**
Expand Down Expand Up @@ -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" />
Expand All @@ -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.
64 changes: 32 additions & 32 deletions behaviors/archivable.markdown
Expand Up @@ -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');
Expand All @@ -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()
Expand All @@ -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" />
Expand All @@ -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" />
Expand All @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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 %}
```

0 comments on commit ec941c4

Please sign in to comment.