Permalink
Browse files

MINOR: documentation fixes from comments provided by the community. S…

…ee below for a list of fixes:

* fixed typo in Email documentation.
* updated link for tutorial code to be relative now that bug #6408 is fixed
* removed 2.3 related docs from 2.4 docs folder
* fixed typo with Orientation documentation
* updated old task url for images/flush
  • Loading branch information...
1 parent 9d344a0 commit 62ed1386a38a47371bdd58db238afcb42406b019 @wilr wilr committed Aug 11, 2011
@@ -31,12 +31,14 @@ your tmp folder.
// values
$image->getHeight() // Returns the height of the image.
$image->getWidth() // Returns the width of the image
- $image->getOrienation() // Returns a class constant: ORIENTATION_SQUARE or ORIENTATION_PORTRAIT or ORIENTATION_LANDSCAPE
+ $image->getOrientation() // Returns a class constant: ORIENTATION_SQUARE or ORIENTATION_PORTRAIT or ORIENTATION_LANDSCAPE
You can also create your own functions by extending the image class, for example
:::php
+ <?php
+
class MyImage extends Image {
public function generateRotateClockwise(GD $gd) {
return $gd->rotate(90);
@@ -101,18 +103,21 @@ For output of an image tag with the image automatically resized to 80px width, y
### Form Upload
For usage on a website form, see `[api:SimpleImageField]`.
+
If you want to upload images within the CMS, see `[api:ImageField]`.
### Clearing Thumbnail Cache
Images are (like all other Files) synchronized with the SilverStripe database.
+
This syncing happens whenever you load the "Files & Images" interface,
and whenever you upload or modify an Image through SilverStripe.
If you encounter problems with images not appearing, or have mysteriously disappeared, you can try manually flushing the
image cache.
- http://www.mysite.com/images/flush
+ http://www.mysite.com/dev/tasks/FlushGeneratedImagesTask
## API Documentation
+
`[api:Image]`
@@ -7,25 +7,12 @@ The Versioned class is a `[api:DataObject]` that adds versioning and staging cap
Sometimes, you'll want to do something whenever a particular kind of page is published. This example sends an email
whenever a blog entry has been published.
-*SilverStripe 2.3*
-
- :::php
- class Page extends SiteTree {
- // ...
- function publish($fromStage, $toStage, $createNewVersion = false) {
- mail("sam@silverstripe.com", "Blog published", "The blog has been published");
- return $this->extension_instances['Versioned']->publish($fromStage, $toStage, $createNewVersion);
- }
- }
-
-
-*SilverStripe 2.4*
-
:::php
class Page extends SiteTree {
// ...
function onAfterPublish() {
mail("sam@silverstripe.com", "Blog published", "The blog has been published");
parent::onAfterPublish();
}
- }
+ }
+
View
@@ -1,22 +1,25 @@
# Email
SilverStripe has emailing functionality using the built-in mail() function in PHP.
-Features include sending plaintext- and HTML emails, sending bulk emails, subscription, handling bounced back emails.
+Features include sending plaintext- and HTML emails, sending bulk emails,
+subscription, handling bounced back emails.
## Configuration
Your PHP configuration needs to include the SMTP module for sending emails.
-If you are not running an SMTP server together with your webserver, you might need to setup PHP with the credentials for
-an external SMTP server (see [PHP documentation for mail()](http://php.net/mail)).
+If you are not running an SMTP server together with your webserver, you might
+need to setup PHP with the credentials for an external SMTP server
+(see [PHP documentation for mail()](http://php.net/mail)).
## Usage
### Sending combined HTML and Plaintext
By default, emails are sent in both HTML and Plaintext format.
-A plaintext representation is automatically generated from the system
-by stripping HTML markup, or transforming it where possible
-(e.g. `<strong>text</strong>` is converted to `*text*`).
+
+A plaintext representation is automatically generated from the system by stripping
+HTML markup, or transforming it where possible (e.g. `<strong>text</strong>` is
+converted to `*text*`).
:::php
$email = new Email($from, $to, $subject, $body);
@@ -31,29 +34,48 @@ The default HTML template is located in `sapphire/templates/email/GenericEmail.s
$email = new Email($from, $to, $subject, $body);
$email->sendPlain();
-### Templates
+### Custom Template
+
+The emails you create may contain quite a bit of content and perhaps custom elements,
+background images and generally be too complex to write out in PHP code.
+
+To support this you can specify a [SilverStripe Template](/topics/templates) to be used
+instead of the built in GenericEmail.ss file.
-**Requirements: SilverStripe 2.3+**
+* Create a 'MyEmailTemplate.ss' file inside `mysite/templates/email`.
+* Fill MyEmailTemplate.ss with what you need to include. You can use any of the [SilverStripe Template syntax](/topics/templates)
+ (e.g. `<% control %>`, `<% if %>`, $FirstName etc). Such as the following:
+
+ :::ss
+ <h1>Hi <% if FirstName %>$FirstName<% end_if %></h1>
+ <p>$WelcomeMessage</p>
+
+The above is a simple hello email that prints out the first name of the user and
+a welcome message. We're not finished quite yet, there is a couple things we need
+to do:
-* Create a SS-template file called, in this example we will use 'MyEmail.ss' inside `mysite/templates/email`.
-* Fill this out with the body text for your email. You can use any [SS-template syntax](/topics/templates) (e.g. `<% control %>`,
-`<% if %>`, $FirstName etc)
-* Choose your template with **setTemplate()**
-* Populate any custom data into the template before sending with **populateTemplate()**
+* Before you call `send()` on your email, set the template with `setTemplate()`
+* Populate any custom data into the template with `populateTemplate()` again,
+you need to do this before you call `send()`. In this example above, we used 2
+fields - `$FirstName` and `$WelcomeMessage` so we need to ensure they are populated:
:::php
- $email = new Email($from, $to, $subject, $body);
- $email->setTemplate('MyEmail');
+ $email = new Email("from@example.com", "to@example.com", "Welcome to mysite");
+
+ // sets the template to be used - MyEmail.ss.
+ $email->setTemplate('MyEmailTemplate');
- // You can call this multiple times or bundle everything into an array, including DataSetObjects
+ // You can call populateTemplate multiple times or bundle everything into an array,
+ // including DataSetObjects.
+
+ // Member::currentUser() includes $FirstName
$email->populateTemplate(Member::currentUser());
- $welcomeMsg = 'Thank you for joining on '.date('Y-m-d'.'!';
- $email->populateTemplate(
- array(
- 'WelcomeMessage' => $welcomeMsg, // Accessible in template via $WelcomeMessage
- )
- );
+ $welcomeMsg = 'Thank you for joining on '.date('Y-m-d').'!';
+
+ $email->populateTemplate(array(
+ 'WelcomeMessage' => $welcomeMsg,
+ ));
$email->send();
@@ -71,30 +93,38 @@ Class definition:
$from = 'email@email.com',
$ss_template = 'MyEmail';
}
- ?>
-
Usage:
:::php
- <?php
$email = new MyEmail();
- $email->populateTemplate(Member::currentUser()); // This will populate the template, $to, $from etc variables if they exist
- $email->send(); // Will immediately send an HTML email with appropriate plain-text content
- ?>
+ $email->send();
### Administrator Emails
-The static function `Email::setAdminEmail()` can be called from a `_config.php` file to set the address that these
-emails should originate from. This address is used if the `from` field is empty.
+The static function `Email::setAdminEmail()` can be called from a `_config.php`
+file to set the address that these emails should originate from. This address
+is used if the `from` field is empty.
### Redirecting Emails
-* `Email::send_all_emails_to($address)` will redirect all emails sent to the given address. Handy for testing!
-* `Email::cc_all_emails_to()` and `Email::bcc_all_emails_to()` will keep the email going to its original recipients, but
-add an additional recipient in the BCC/CC header. Good for monitoring system-generated correspondence on the live
-systems.
+`Email::send_all_emails_to($address)` will redirect all emails sent to the given
+address. We recommend using this in your local development environment. You can
+either configure this in your mysite/_config.php:
+
+ :::php
+ if(Director::isDev()) Email::send_all_emails_to("me@example.com");
+
+If you use a [SilverStripe Environment](environment-management) file to manage your
+configuration then you should include the following in your development copy:
+
+ :::php
+ define('SS_SEND_ALL_EMAILS_TO', 'me@example.com');
+
+`Email::cc_all_emails_to()` and `Email::bcc_all_emails_to()` will keep the email
+going to its original recipients, but adds an additional recipient in the BCC/CC
+header.
:::php
if(Director::isLive()) Email::bcc_all_emails_to("client@example.com");
@@ -8,8 +8,8 @@ the *Image* table by storing the id of the respective *Image* in the first table
relations between [DataObjects](/topics/datamodel#relations) and the way to manage them easily.
<div class="notice" markdown='1'>
- I'm using the default tutorial theme in the following examples so the templates may vary or you may need to change
- the template code in this example to fit your theme
+I'm using the default tutorial theme in the following examples so the templates may vary or you may need to change
+the template code in this example to fit your theme
</div>
## What are we working towards?
@@ -770,6 +770,6 @@ CMS and how to display them on the website.
## Download the code
-Download all the [code](http://doc.silverstripe.org/src/github/master/sapphire/docs/en/tutorials/_images/tutorial5-completecode.zip) for this tutorial.
+Download all the [code](_images/tutorial5-completecode.zip) for this tutorial.
-You can also download the [code](http://doc.silverstripe.org/src/github/master/sapphire/docs/en/tutorials/_images/tutorial5-completecode-blackcandy.zip) for use in the blackcandy template.
+You can also download the [code](_images/tutorial5-completecode-blackcandy.zip) for use in the blackcandy template.

0 comments on commit 62ed138

Please sign in to comment.