Add Table of Contents to README and create USE_CASES sectionorigin/toc-template

2 files changed, 162 insertions, 0 deletions

diff --git a/README.md b/README.md
index 438c1c5..9817c56 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,19 @@ Please browse the rest of this README for further detail.
 
 We appreciate your continued support, thank you!
 
+# Table of Contents
+
+* [Installation](#installation)
+* [Quick Start](#quick_start)
+* [Usage](#usage)
+* [Use Cases](#use_cases)
+* [Announcements](#announcements)
+* [Roadmap](#roadmap)
+* [How to Contribute](#contribute)
+* [Troubleshooting](#troubleshooting)
+* [About](#about)
+
+<a name="installation"></a>
 # Installation
 
 ## Prerequisites
@@ -64,6 +77,7 @@ Previous versions of the library can be found in the [version index](https://sen
 - The SendGrid Service, starting at the [free level](https://sendgrid.com/free?source=sendgrid-php)
 - [php-HTTP-Client](https://github.com/sendgrid/php-http-client)
 
+<a name="quick_start"></a>
 # Quick Start
 
 ## Hello Email
@@ -100,6 +114,13 @@ The `SendGrid\Mail` constructor creates a [personalization object](https://sendg
 The following is the minimum needed code to send an email without the /mail/send Helper ([here](https://github.com/sendgrid/sendgrid-php/blob/master/examples/mail/mail.php#L28) is a full example):
 
 ```php
+<?php
+// If you are using Composer
+require 'vendor/autoload.php';
+
+// If you are not using Composer (recommended)
+// require("path/to/sendgrid-php/sendgrid-php.php");
+
 $request_body = json_decode('{
   "personalizations": [
     {
@@ -121,6 +142,10 @@ $request_body = json_decode('{
     }
   ]
 }');
+
+$apiKey = getenv('SENDGRID_API_KEY');
+$sg = new \SendGrid($apiKey);
+
 $response = $sg->client->mail()->send()->post($request_body);
 echo $response->statusCode();
 echo $response->body();
@@ -167,6 +192,7 @@ print $response->headers();
 print $response->body();
 ```
 
+<a name="usage"></a>
 # Usage
 
 - [SendGrid Docs](https://sendgrid.com/docs/API_Reference/index.html)
@@ -176,14 +202,22 @@ print $response->body();
 - [How-to: Migration from v2 to v3](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/how_to_migrate_from_v2_to_v3_mail_send.html)
 - [v3 Web API Mail Send Helper](https://github.com/sendgrid/sendgrid-php/tree/master/lib/helpers/mail/README.md) - build a request object payload for a v3 /mail/send API call.
 
+<a name="use_cases">
+# Use Cases
+
+[Examples of common API use cases](https://github.com/sendgrid/sendgrid-php/blob/master/USE_CASES.md), such as how to send an email with a transactional template.
+
+<a name="announcements"></a>
 # Announcements
 
 All updates to this library is documented in our [CHANGELOG](https://github.com/sendgrid/sendgrid-php/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-php/releases)
 
+<a name="roadmap"></a>
 # Roadmap
 
 If you are interested in the future direction of this project, please take a look at our open [issues](https://github.com/sendgrid/sendgrid-php/issues) and [pull requests](https://github.com/sendgrid/sendgrid-php/pulls). We would love to hear your feedback.
 
+<a name="contribute"></a>
 # How to Contribute
 
 We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING](https://github.com/sendgrid/sendgrid-php/blob/master/CONTRIBUTING.md) guide for details.
@@ -195,10 +229,12 @@ Quick links:
 - [Sign the CLA to Create a Pull Request](https://github.com/sendgrid/sendgrid-php/blob/master/CONTRIBUTING.md#cla)
 - [Improvements to the Codebase](https://github.com/sendgrid/sendgrid-php/blob/master/CONTRIBUTING.md#improvements_to_the_codebase)
 
+<a name="troubleshooting"></a>
 # Troubleshooting
 
 Please see our [troubleshooting guide](https://github.com/sendgrid/sendgrid-php/blob/master/TROUBLESHOOTING.md) for common library issues.
 
+<a name="about"></a>
 # About
 
 sendgrid-php is guided and supported by the SendGrid [Developer Experience Team](mailto:dx@sendgrid.com).
diff --git a/USE_CASES.md b/USE_CASES.md
new file mode 100644
index 0000000..dd4b709
--- /dev/null
+++ b/USE_CASES.md
@@ -0,0 +1,126 @@
+This documentation provides examples for specific use cases. Please [open an issue](https://github.com/sendgrid/sendgrid-php/issues) or make a pull request for any use cases you would like us to document here. Thank you!
+
+# Table of Contents
+
+* [Transactional Templates](#transactional_templates)
+
+<a name="transactional_templates"></a>
+# Transactional Templates
+
+For this example, we assume you have created a [transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). Following is the template content we used for testing.
+
+Template ID (replace with your own):
+
+```text
+13b8f94f-bcae-4ec6-b752-70d6cb59f932
+```
+
+Email Subject:
+
+```text
+<%subject%>
+```
+
+Template Body:
+
+```html
+<html>
+<head>
+	<title></title>
+</head>
+<body>
+Hello -name-,
+<br /><br/>
+I'm glad you are trying out the template feature!
+<br /><br/>
+<%body%>
+<br /><br/>
+I hope you are having a great day in -city- :)
+<br /><br/>
+</body>
+</html>
+```
+
+## With Mail Helper Class
+
+```php
+<?php
+// If you are using Composer
+require 'vendor/autoload.php';
+
+// If you are not using Composer (recommended)
+// require("path/to/sendgrid-php/sendgrid-php.php");
+
+$from = new SendGrid\Email(null, "test@example.com");
+$subject = "I'm replacing the subject tag";
+$to = new SendGrid\Email(null, "test@example.com");
+$content = new SendGrid\Content("text/html", "I'm replacing the <strong>body tag</strong>");
+$mail = new SendGrid\Mail($from, $subject, $to, $content);
+$mail->personalization[0]->addSubstitution("-name-", "Example User");
+$mail->personalization[0]->addSubstitution("-city-", "Denver");
+$mail->setTemplateId("13b8f94f-bcae-4ec6-b752-70d6cb59f932");
+
+$apiKey = getenv('SENDGRID_API_KEY');
+$sg = new \SendGrid($apiKey);
+
+try {
+    $response = $sg->client->mail()->send()->post($mail);
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+}
+
+echo $response->statusCode();
+echo $response->headers();
+echo $response->body();
+```
+
+## Without Mail Helper Class
+
+```php
+<?php
+// If you are using Composer
+require 'vendor/autoload.php';
+
+// If you are not using Composer (recommended)
+// require("path/to/sendgrid-php/sendgrid-php.php");
+
+$request_body = json_decode('{
+  "personalizations": [
+    {
+      "to": [
+        {
+          "email": "dx@sendgrid.com"
+        }
+      ],
+      "substitutions": {
+        "-name-": "Example User",
+        "-city-": "Denver"
+      },
+      "subject": "I\'m replacing the subject tag"
+    }
+  ],
+  "from": {
+    "email": "elmer@sendgrid.com"
+  },
+  "content": [
+    {
+      "type": "text/html",
+      "value": "I\'m replacing the <strong>body tag</strong>"
+    }
+  ],
+  "template_id": "13b8f94f-bcae-4ec6-b752-70d6cb59f932"
+}');
+
+$apiKey = getenv('SENDGRID_API_KEY');
+$sg = new \SendGrid($apiKey);
+
+try {
+    $response = $sg->client->mail()->send()->post($request_body);
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+}
+
+echo $response->statusCode();
+echo $response->body();
+echo $response->headers();
+```
\ No newline at end of file