SpreadKit 1.1

您想将类似以下内容添加到 Podfile 中pod 'SpreadKit', '~> 1.1'

target 'MyApp' do
  pod 'SpreadKit', '~> 1.1'
end

然后在您的终端或从 CocoaPods.app 中运行 pod install

另外，如果想先测试运行，可以运行以下命令

pod try SpreadKit


依赖
RestKit	~> 0.20.0
SBJson	= 3.2
GMGridView	>= 0

SpreadKit 1.1

作者：
sprd.net AG

欢迎使用 SpreadKit。SpreadKit 是一个用于与 Spreadshirt API 交互的 iOS 框架。

使用 SpreadKit，您可以将目录浏览、产品创建和购物车管理集成到您的 iOS 应用中。本指南将帮助您开始使用 SpreadKit。

有关 Spreadshirt API 的有用信息和所有资源的参考，请参阅 Spreadshirt 开发者网络（SDN）。在那里，您可以了解 Spreadshirt API 的功能并获取使用它的构建想法。

先决条件

SpreadKit 专门为 iOS 编写，从版本 5.0 开始。目前没有计划开发 Mac OS X 框架。

为了能够创建产品、购物车等，您需要在使用 SDN 的 API 密钥进行申请。

强烈建议您使用 CocoaPods 来管理您的项目依赖项，主要原因有两个：(1) 使用这种方式安装 SpreadKit 将会更加容易，(2) 它很棒 :).

注意事项

以下功能尚未实现，但计划实现

支持 Spreadshirt 订单 API
支持产品上的文本配置
支持在 get 请求中提供搜索查询
支持会话

设置

将 SpreadKit 安装到您的项目的唯一支持方式是通过 CocoaPods，并且非常简单。如果您还没有，请在与您的项目根同级的文件夹中创建一个名为 Podfile 的文件，并包括以下行

platform :ios, '5.0'
pod 'SpreadKit', '~> 1.0'

假设您已经安装了 CocoaPods（运行 sudo gem install cocoapods && pod setup），您可以通过运行 pod install 来运行它，然后用 Xcode 打开创建的 .xcworkspace 文件。这将安装当前的 SpreadKit 版本（~> 1.0 表示它将安装最新的 1.x 版本）。

在您的代码中，无论您在哪里需要 SpreadKit，只需

#import <SpreadKit/SpreadKit.h>

（也可以在您的前缀头中做这件事）您就可以开始运行了。

初始化

SpreadKit的主入口点是SPClient类。它代表了您对所有Spreadshirt API调用的主要接口。它可以根据您的应用需求被初始化为针对用户或商店的。初始化方法为

[SPClient clientWithShopId:@"yourShopID"
                 andApiKey:@"yourAPIKey" 
                 andSecret:@"yourSecret"
               andPlatform:SPPlatformEU];

或

[SPClient clientWithUserId:@"yourShopID"
                 andApiKey:@"yourAPIKey" 
                 andSecret:@"yourSecret"
               andPlatform:SPPlatformEU];

请注意，平台参数只能是SPPlatformEU（针对欧洲平台）或SPPlatformNA（针对北美平台）中的一个。

首先初始化的客户端稍后可以通过[SPClient sharedClient]选择器获取。如果需要同时使用多个客户端（例如，一个用于欧洲，一个用于北美），只需初始化并将它们存储在您的应用程序中的变量中。在这种情况下，不能使用[SPClient sharedClient]。

基础

块

SpreadKit几乎在每个地方使用Objective-C块。在处理异步调用（如与Spreadshirt API等Web服务）时，它们提供了一种方便的编程环境。如果您不熟悉块，强烈建议您阅读有关它们的信息。

基本上，您对Spreadshirt API的每一项调用都将包括一个名为completion的块参数。此块将包含一个NSError对象和您请求的数据。错误处理和数据处理取决于您。为了说明这种编程模型，请看以下代码

[client getShopAndOnCompletion:^(SPShop *shop, NSError *error) {
    if (error) {
        // do some error handling
    } else {
        [controller shopLoaded:shop]
    }
}];

这会获取与客户端关联的SPShop对象，并向视图控制器通知该对象的有效性（例如，显示商店信息或启动进一步请求）。由于完整请求的动作可以直接指定在请求的代码位置，因此无需使用代理方法。

模型

SpreadKit包含与Spreadshirt API每种资源类型对应的Objective-C类。您可以在SDN上查看可用的资源类型。

主入口点

您通过初始化SPClient的方式进入使用Spreadshirt资源所做的一切。它可以是一个商店或用户，这取决于您想要实现什么目标。从那里开始，您将根据这个主要对象访问所有其他资源。例如，您可以通过以下方式检索商店范畴客户端的SPShop对象

SPClient *client = [SPClient clientWithShopId:...];
[client getShopAndOnCompletion:^(SPShop *shop, NSError *error) {
    // do something with your retrieved shop object
}];

对于用户范畴客户端，可以使用getUserAndOnCompletion:completion方法以类似的方式完成。

浏览和获取对象

一旦您掌握了您的对象，您可能想浏览API。一般方法是使用SPClient的get方法。

通过get即可从Spreadshirt API获取资源，这是一种奇妙且直观的获取资源的方法。您可以向其传递一个现有对象存根以填写详细信息，一个列表以获取该列表中的数量或只需请求对象的类型和ID。在其completion块中，get将返回您请求的内容。

列表

一开始，您的主要对象的大部分属性都是SPList类。这些都是页面列表对象的引用。假设您有一个名为shop的SPShop对象，您可以通过以下方式访问商店产品的第一页

[client get:shop.products completion:^(id loaded, NSError *error) {
    NSArray *products = (NSArray *)loaded;
   // do something with the first page of products
}];

如果您想获取列表对象的下一页，只需通过more属性获取即可（这会自动指向已加载页面的下一页）

[client get:shop.products.more completion:^(id loaded, NSError *error) {
    NSArray *productsPage2 = (NSArray *)loaded;
}];

您可以使用SPList的elements属性在任何时候访问先前加载的对象的NSArray

NSArray *alreadyLoadedProducts = shop.products.elements;

要获取可用的页面概述，您可以使用SPList的pages属性。请注意，这只有在至少加载了第一页之后才可用。

您可以使用SPList的hasNextPage属性在任何时候检查是否还有可加载的页面。

单个对象

Spredshirt API通常会返回空对象以保持响应小而快。空对象是没有设置所有属性的空对象。如果遇到具有nil值的对象属性，很可能它只是一个空对象，您可以使用SPClient的get方法获取更多信息

SPShop *shop;
// in this example, we fill out the stub objects of a shops user
[client get:shop.user completion^(id loaded, NSError *error) {
    SPUser *user = (SPUser *)loaded;
}];

如果您知道您要什么，您也可以仅使用对象的类型和ID从Spreadshirt API获取东西

[client get:[SPProduct class] identifier:@"22169128" completion:^(id loaded, NSError *error) {
    SPProduct *product = (SPProduct *)loaded;
    // do something with the product
}];

图像资源

大多数由Spreadshirt API返回的对象都与一个关联的resources NSArray。这包含用于在应用程序内显示的产品、设计等的图像资源。您可以浏览此数组以找到合适的图像。

SPResource最重要的属性是该资源的type。您可以在SDN上找到有关可用的资源类型的更多信息。

一旦您已经选择了要显示的资源，您可以使用特殊的SPImageLoader类来获取用于显示的UIImage。只需获取一个实例

SPImageLoader *loader = [[SPImageLoader alloc] init]

并加载一个指定大小的所需资源（您想要显示图像的大小）

[self loadImageForResource:resource withSize:size completion:^(UIImage *image, NSURL *imageURL, NSError *error) {
    // do something with your image 
}];

在completion块中，也返回图像的URL，以防您想使用它（例如，防止在UITableView中切换图像）。

图像会自动以正确的分辨率加载（retina或非retina）。只需指定所需的大小，SpreadKit会将其处理。

可选地，您可以指定用于加载图像资源的外观。当获取具有可自定义颜色（外观）的产品的图像时需要这样做。在这种情况下，您可以使用SPImageLoader的loadImageForResource:withSize:andAppearanceId:completion:方法。

创建、更新和删除对象

就像获取对象一样，您也可以创建、更新和删除它们。这是通过SPClient的post、put和delete方法完成的。请注意，对于大多数更改对象的操作，您需要一个正确配置的API密钥。

要创建新对象，只需使用post方法，例如用于设计

SPDesign *design = [[SPDesign alloc] init];
design.name = @"Super Cool Test Design";
design.description = @"This is a Design created with SpreadKit";
[client post:design completion:^(id newObject, NSError *error){
    if (error) {
        // something went wrong, check the error
    }
    // newObject should be the object you just created
}];

更新以相同的方式进行，只需使用put方法

design.description = @"I totally updated that description!"
[client put:design completion:^(id updatedObject, NSError *error) {
   if (error) {
        // something went wrong, check the error
    }
    // updatedObject should be the object you just updated
}];

某些对象可以使用Spreadshirt API删除，例如篮子或自行创建的产品。这可以通过使用SPClient的delete方法来完成。

SPDesign *design;
[client delete:design completion:^(NSError *error) {
    if (error) {
        // something went wrong during deletion, check error
    }
    // if object was deleted, error is nil
}];

篮子

为了使用户能够购买产品，能够处理购物车并引导他们进行结账是至关重要的。这可以使用 SPBasketManager 轻松完成。

管理购物车项目

要开始购物车管理，请获取一个闪亮的新的 SPBasketManager 实例。

SPBasketManager *basketManager = [SPBasketManager alloc] init];

对于您想要添加的每个项目，请调用 SPBasketManager 的 addToBasket:withSize:andAppearance 方法。一个项目可以是 SPArticle 或 SPProduct。要了解更多关于两者之间区别的信息，请参阅 SDN。

addToBasket:withSize:andAppearance 返回一个 SPBasketItem 的实例，您可以用来进一步指定购物车的内容。在以下示例中，添加了一个 SPProduct 并然后更改了购物车中的数量。

SPProduct *product;
SPBasketManager *basketManager = [SPBasketManager alloc] init];
SPBasketItem *item = [basketManager addToBasket:product 
                                       withSize:[product.productType.sizes objectAtIndex:0] 
                                  andAppearance:product.appearance];
item.quantity = @2;

(此示例使用了新的 Objective-C literals for NSNumber。如果您不了解它们，我强烈建议查看它们！)

您可以使用 basketManager.items 检查当前购物车中的项目，并使用 SPBasketManager 的 removeItem 方法删除它们。

结账

目前，Spreadshirt API 只支持通过网页进行结账。要检索结账 URL，您可以使用您的 SPBasketManager。

[basketManagerm checkoutURLWithCompletion:^(NSURL *checkoutURL, NSError *error) {
    if (error) {
        // something is wrong with your basket, check the error messages
    } else {
        // for example, show a UIWebView for the checkoutURL
    }
}];

创建产品

通过 Spreadshirt API 创建自定义产品是复杂的。为了使您创建产品更容易，SpreadKit 包含了 SPProductCreator。目前，此类支持创建具有一种图片配置的产品，并位于所选产品类型的默认打印区域。

使用 SPProductCreator 是 straightforward

SPProductCreator *creator = [[SPProductCreator alloc] init];
UIImage *image; // for example a picture taken with the camera
SPProductType *type; // a product type you have previosuly loaded from the API
SPProduct *product = [creator createProductWithProductType:type andImage:image];

创建后，您仍然可以根据喜好修改产品。完成后，将其上传到 Spreadshirt。

[creator uploadProduct:self.product completion:^(SPProduct *uploaded, NSError *error) {
    if (error) {
        // something is wrong woth your product, check the error
    }
    // use your product, e.g. put it in a basket! 
}];

对于更复杂的产品，您必须修改产品的配置。在 SDN 上阅读有关信息。

结论

这是对 SpreadKit 的快速浏览。欢迎您探索代码以发现更多与之相关的功能。要了解 Spreadshirt 域模型以及您可以使用 Spreadshirt API 实现的内容，请阅读完整文档，请参阅 SDN。