Update README files and submit initial templates (square#75)

shahzadwaris · Aug 14, 2018 · 97906cf · 97906cf
1 parent 87eec1d
commit 97906cf
Show file tree

Hide file tree

Showing 7 changed files with 552 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -1,18 +1,52 @@
 # Square Connect API Examples
 
-**IMPORTANT:** On 16 February 2016, changes were made to the representation of a
-Square merchant in the Connect API. These changes slightly altered the behavior of the
-Connect API for applications created after 16 February. The samples in this repository
-now reflect this altered behavior. If you created your Connect API application _before_
-16 February, samples that reflect your application's behavior are available in the
-`v1` directory.
-
-On 23 May 2017, We made a significant improvement to our SDK to expand their
-functionality and make them even easier to use. Unfortunately, some of the
-changes are not backward compatible.  The samples in this repository now contain
-three different folders `v1`, `v2.0`, and `v2.1`.  You can read more about the
-new SDK in our [blog post](https://medium.com/square-corner-blog/announcing-our-new-versions-of-our-client-sdks-1336d26e8099)
-
-This repository contains simple code samples that demonstrate use of the Square Connect API. Complete documentation for the API is available at [connect.squareup.com](https://connect.squareup.com).
-
-If you have questions about Square Connect API features or implementation, please see the [FAQ](https://docs.connect.squareup.com/articles/faq/).
+This repository contains code samples demonstrating the functionality of the
+Square Connect API and templates to simplify use of our SDKs and APIs.
+
+
+## In this repository
+
+* `connect-examples/oauth` - samples implementing OAuth
+* `connect-examples/v1` - samples demonstrating Connect v1 functionality
+* `connect-examples/v2` - samples demonstrating Connect v2 functionality
+* `templates/` - code blocks and function definitions to simplify common usage
+
+
+## Getting help
+
+Complete documentation for Square APIs is available at
+[docs.connect.squareup.com].
+
+If you have questions about Square Connect API features or implementation,
+you can ask for help on [Stack Overflow] or in our [Slack community].
+
+
+--------------------------------------------------------------------------------
+
+## Release notes
+
+### 2018-08-13
+
+Updating directory structure and submitting inaugural code templates.
+
+### 2017-05-23
+
+On 23 May 2017, we improved our SDKs to expand their functionality and make them
+easier to use. Unfortunately, some of the changes are not backward compatible.
+You can read more about the changes in our [SDK blog post].
+
+
+### 2016-02-16
+
+On 16 February 2016, we changed the way merchant data is represented in the
+Connect APIs. The data change also altered API behavior slightly. The samples
+in this repository reflect this altered behavior. If you created your Connect
+API application *before* 16 February, you can find samples that reflect your
+application's behavior in the `v1` directory.
+
+
+[//]: # "Link anchor definitions"
+[SDK blog post]: https://medium.com/square-corner-blog/announcing-our-new-versions-of-our-client-sdks-1336d26e8099
+[Stack Overflow]: https://stackoverflow.com/questions/tagged/square-connect
+[Slack community]: https://squ.re/2Hks3YE
+[docs.connect.squareup.com]: https://docs.connect.squareup.com
diff --git a/templates/README.md b/templates/README.md
@@ -0,0 +1,15 @@
+# Square Connect API Templates
+
+This directory contains code templates to simplify use of our SDKs and APIs.
+These templates are also referenced in setup guides at
+[docs.connect.squareup.com].
+
+## In this directory
+
+* `php` - server-side code templates in PHP
+* `web-ui` - client-side UI templates and themes for Square Payment Form
+
+--------------------------------------------------------------------------------
+
+[//]: # "Link anchor definitions"
+[docs.connect.squareup.com]: https://docs.connect.squareup.com
diff --git a/templates/php/sq_config.php b/templates/php/sq_config.php
@@ -0,0 +1,115 @@
+<?php
+/**
+ * Connect SDK Configuration File
+ *
+ * This template provides useful constants and skeleton functions that can make
+ * working with Connect SDKs easier. You can find more information on how to
+ * use these templates at [docs.connect.squareup.com]
+ */
+
+// {{{ constants
+
+/**
+* Your Square sandbox token
+* Used to make test calls against the Square sandbox
+* REPLACE_ME = a sandbox access token from the application Credentials tab
+*/
+if (!defined(_SQ_SANDBOX_TOKEN)) {
+    define('_SQ_SANDBOX_TOKEN', "REPLACE_ME") ;
+}
+
+/**
+* Your Square sandbox application ID
+* Used to make test calls against the Square sandbox
+* REPLACE_ME = a sandbox application ID from the application Credentials tab
+*/
+if (!defined(_SQ_SANDBOX_APP_ID)) {
+    define('_SQ_SANDBOX_APP_ID', "REPLACE_ME") ;
+}
+
+/**
+* Your Square application ID
+* REPLACE_ME = an application ID from the application Credentials tab
+*/
+if (!defined(_SQ_APP_ID)) {
+    define('_SQ_APP_ID', "REPLACE_ME") ;
+}
+
+/**
+* Your Square application secret
+* REPLACE_ME = an application secrete from the application OAuth tab
+*/
+if (!defined(_SQ_APP_SECRET)) {
+    define('_SQ_APP_SECRET', "REPLACE_ME") ;
+}
+
+/**
+* Square domain for REST API calls
+*/
+if (!defined(_SQ_DOMAIN)) {
+    define('_SQ_DOMAIN', "connect.squareup.com") ;
+}
+
+// }}}
+
+// {{{ functions
+
+/**
+ * Returns an access token for Square API calls
+ *
+ * By default, the function below returns sandbox credentials for testing and
+ * development.For production, replace the function implementation with a valid
+ * OAuth flow to generate OAuth credentials. See the OAuth Setup Guide for more
+ * information on implementing OAuth.
+ *
+ * @return string a valid access token
+ */
+function getAccessToken() {
+
+  $accessToken = _SQ_SANDBOX_TOKEN;
+
+  return $accessToken;
+}
+
+/**
+ * Returns an application Id for Square API calls
+ *
+ * By default, the function below returns a sandbox application ID for testing
+ * and development. For production, replace the function implementation with a
+ * valid production credential.
+ *
+ * @return string a valid application ID token
+ */
+function getApplicationId() {
+
+  $accessToken = _SQ_SANDBOX_APP_ID;
+
+  return $accessToken;
+}
+
+
+/**
+ * Returns a location ID for Square API calls
+ *
+ * By default, the function below returns a hardcoded location ID from the
+ * Application Dashboard. For production, update the function implementation
+ * to fetch a valid location ID programmtically.
+ *
+ * @return string a valid location ID
+ */
+function getLocationId() {
+
+  // Replace the string with a sandbox location ID from the Application Dashboard
+  return "REPLACE_ME" ;
+
+}
+
+// }}}
+
+/**
+ * Include the Square Connect SDK loader
+ * Uncomment the line below if you are installing the SDK manually instead of
+ * using a package manager to install the Connect SDK
+ */
+//require_once 'local/path/to/autoload.php';
+?>
diff --git a/templates/web-ui/payment-form/README.md b/templates/web-ui/payment-form/README.md
@@ -0,0 +1,12 @@
+# Templates and themes for Square Payment Form
+
+This directory contains collections of HTML, Javascript, and CSS templates for
+Square Payment Form. For instructions on using this templates, see the Payment
+Form Setup guide at [docs.connect.squareup.com].
+
+## In this directory
+
+* `basic` - templates for a basic Payment Form integration
+
+[//]: # "Link anchor definitions"
+[docs.connect.squareup.com]: https://docs.connect.squareup.com
diff --git a/templates/web-ui/payment-form/basic/sqpaymentform-basic.css b/templates/web-ui/payment-form/basic/sqpaymentform-basic.css
@@ -0,0 +1,102 @@
+/* Define how SqPaymentForm iframes should look */
+.sq-input {
+  border: 1px solid rgb(223, 223, 223);
+  outline-offset: -2px;
+  margin-bottom: 5px;
+  display: inline-block;
+}
+
+/* Define how SqPaymentForm iframes should look when they have focus */
+.sq-input--focus {
+  outline: 5px auto rgb(59, 153, 252);
+}
+
+/* Define how SqPaymentForm iframes should look when they contain invalid values */
+.sq-input--error {
+  outline: 5px auto rgb(255, 97, 97);
+}
+
+/* Customize the "Pay with Credit Card" button */
+.button-credit-card {
+  min-width: 200px;
+  min-height: 20px;
+  padding: 0;
+  margin: 5px;
+  line-height: 20px;
+  box-shadow: 2px 2px 1px rgb(200, 200, 200);
+  background: rgb(255, 255, 255);
+  border-radius: 5px;
+  border: 1px solid rgb(200, 200, 200);
+  font-weight: bold;
+  cursor:pointer;
+}
+
+
+/* Customize the "{{Wallet}} not enabled" message */
+.wallet-not-enabled {
+  min-width: 200px;
+  min-height: 40px;
+  max-height: 64px;
+  padding: 0;
+  margin: 10px;
+  line-height: 40px;
+  background: #eee;
+  border-radius: 5px;
+  font-weight: lighter;
+  font-style: italic;
+  font-family: inherit;
+  display: block;
+}
+
+/* Customize the Apple Pay on the Web button */
+.button-apple-pay {
+  min-width: 200px;
+  min-height: 40px;
+  max-height: 64px;
+  padding: 0;
+  margin: 10px;
+  background-image: -webkit-named-image(apple-pay-logo-white);
+  background-color: black;
+  background-size: 100% 60%;
+  background-repeat: no-repeat;
+  background-position: 50% 50%;
+  border-radius: 5px;
+  cursor:pointer;
+  display: none;
+}
+
+/* Customize the Masterpass button */
+.button-masterpass {
+  min-width: 200px;
+  min-height: 40px;
+  max-height: 40px;
+  padding: 0;
+  margin: 10px;
+  background-image: url(https://static.masterpass.com/dyn/img/btn/global/mp_chk_btn_147x034px.svg);
+  background-color: black;
+  background-size: 100% 100%;
+  background-repeat: no-repeat;
+  background-position: 50% 50%;
+  border-radius: 5px;
+  border-color: rgb(255, 255, 255);
+  cursor:pointer;
+  display: none;
+}
+
+#sq-walletbox {
+  float:left;
+  margin:5px;
+  padding:10px;
+  text-align: center;
+  vertical-align: top;
+  font-weight: bold;
+}
+
+#sq-ccbox {
+  float:left;
+  margin:5px;
+  padding:10px;
+  text-align: center;
+  vertical-align: top;
+  font-weight: bold;
+}
diff --git a/templates/web-ui/payment-form/basic/sqpaymentform-basic.html b/templates/web-ui/payment-form/basic/sqpaymentform-basic.html
@@ -0,0 +1,74 @@
+<html>
+
+<head>
+
+  <!-- link to the SqPaymentForm library -->
+  <script type="text/javascript" src="https://js.squareup.com/v2/paymentform">
+  </script>
+
+  <!-- link to the local SqPaymentForm initialization -->
+  <script type="text/javascript" src="path/to/sqpaymentform.js">
+  </script>
+
+  <!-- link to the custom styles for SqPaymentForm -->
+  <link rel="stylesheet" type="text/css" href="path/to/sqpaymentform.css">
+
+</head>
+
+<body>
+
+<div id="sq-ccbox">
+  <!--
+    You should replace the action attribute of the form with the path of
+    the URL you want to POST the nonce to (for example, "/process-card")
+  -->
+  <form id="nonce-form" novalidate action="path/to/payment/processing/page" method="post">
+    Pay with a Credit Card
+    <table>
+    <tbody>
+      <tr>
+        <td>Card Number:</td>
+        <td><div id="sq-card-number"></div></td>
+      </tr>
+      <tr>
+        <td>CVV:</td>
+        <td><div id="sq-cvv"></div></td>
+      </tr>
+      <tr>
+        <td>Expiration Date: </td>
+        <td><div id="sq-expiration-date"></div></td>
+      </tr>
+      <tr>
+        <td>Postal Code:</td>
+        <td><div id="sq-postal-code"></div></td>
+      </tr>
+      <tr>
+        <td colspan="2">
+          <button id="sq-creditcard" class="button-credit-card" onclick="requestCardNonce(event)">
+            Pay with card
+          </button>
+        </td>
+      </tr>
+    </tbody>
+    </table>
+
+    <!--
+      After a nonce is generated it will be assigned to this hidden input field.
+    -->
+    <input type="hidden" id="card-nonce" name="nonce">
+  </form>
+</div>
+
+<div id="sq-walletbox">
+  Pay with a Digital Wallet
+  <div id="sq-apple-pay-label" class="wallet-not-enabled">Apple Pay for Web not enabled</div>
+  <!-- Placeholder for Apple Pay for Web button -->
+  <button id="sq-apple-pay" class="button-apple-pay"></button>
+
+  <div id="sq-masterpass-label" class="wallet-not-enabled">Masterpass not enabled</div>
+  <!-- Placeholder for Masterpass button -->
+  <button id="sq-masterpass" class="button-masterpass"></button>
+</div>
+
+</body>
+</html>