├── .gitignore ├── .travis.yml ├── README.md ├── docs ├── android │ ├── index.md │ └── tutorials │ │ ├── advanced-filtering-and-searching.md │ │ ├── advanced-types.md │ │ ├── content-type-id.png │ │ ├── field-codename.png │ │ ├── getting-started-with-contentful-and-android.md │ │ ├── offline-persistence-with-vault.md │ │ └── story-fields.png ├── concepts │ ├── apis.md │ ├── data-model.md │ ├── editor-interfaces.md │ ├── images.md │ ├── links.md │ ├── locales.md │ ├── multiple-environments.md │ ├── sync.md │ ├── uiextensions.md │ └── webhooks.md ├── index.md ├── ios │ ├── index.md │ └── tutorials │ │ ├── content-type-id.png │ │ ├── offline-persistence-in-ios-sdk.md │ │ ├── using-contentful-xcode-plugin.md │ │ ├── using-delivery-api-on-ios.md │ │ ├── using-delivery-api-with-swift.md │ │ └── using-management-api-on-ios.md ├── java │ └── index.md ├── javascript │ ├── index.md │ └── tutorials │ │ ├── create-expressjs-app-using-contentful.md │ │ ├── default_website.png │ │ ├── keys_and_ids.png │ │ ├── using-js-cda-sdk.md │ │ └── using-the-sync-api-with-js.md ├── net │ ├── index.md │ └── tutorials │ │ ├── aspnet-core.md │ │ ├── management-api.md │ │ ├── using-net-cda-sdk.md │ │ └── webhook-roles-snapshots.md ├── php │ ├── index.md │ └── tutorials │ │ ├── getting-started-with-contentful-and-laravel.md │ │ ├── getting-started-with-contentful-and-php.md │ │ ├── getting-started-with-contentful-and-symfony.md │ │ └── using-the-sync-api-with-php.md ├── python │ ├── index.md │ └── tutorials │ │ ├── full-stack-getting-started.md │ │ └── getting-started-with-contentful-and-python.md ├── references │ ├── authentication.html.haml │ ├── content-delivery-api.md │ ├── content-management-api.md │ ├── content-preview-api.md │ ├── errors.md │ ├── http-details.md │ └── images-api.md ├── ruby │ ├── index.md │ └── tutorials │ │ ├── automated-rebuild-and-deploy-with-circleci-and-webhooks.md │ │ ├── create-your-own-rails-app.md │ │ ├── full-stack-getting-started.md │ │ ├── getting-started-with-contentful-and-ruby.md │ │ ├── getting-started-with-contentful-cma-and-ruby.md │ │ └── using-contentful-bootstrap-for-keeping-up-with-your-spaces.md ├── tools │ ├── applications.md │ ├── extensions.md │ ├── spacemanagement.md │ └── staticsitegenerators.md └── tutorials │ └── general │ ├── delivery-api-lambda-and-api-gateway.md │ ├── import-and-export.md │ └── scheduling-posts.md ├── generate-docs.sh ├── package.json ├── placeholder-replacements.sh └── raw_docs ├── _partials ├── content-type-filter-output.md ├── content-type-filter.md ├── credentials.md ├── field-filter-ne-output.md ├── field-filter-output.md ├── get-all-asset-output.md ├── get-all-entry-linked-output.md ├── get-all-entry-output-android.md ├── get-all-entry-output-python.md ├── get-all-entry-output.md ├── get-asset-output.md ├── get-asset-processed-output.md ├── get-entry-output-android.md ├── get-entry-output.md ├── getting-started-intro.md ├── ruby-python-object-complex-output.md ├── ruby-python-object-output.md └── sorted-entries-out.md ├── android ├── index.md └── tutorials │ ├── advanced-filtering-and-searching.md │ ├── advanced-types.md │ ├── content-type-id.png │ ├── field-codename.png │ ├── getting-started-with-contentful-and-android.md │ ├── offline-persistence-with-vault.md │ └── story-fields.png ├── concepts ├── apis.md ├── data-model.md ├── editor-interfaces.md ├── images.md ├── links.md ├── locales.md ├── multiple-environments.md ├── sync.md ├── uiextensions.md └── webhooks.md ├── index.md ├── ios ├── index.md └── tutorials │ ├── content-type-id.png │ ├── offline-persistence-in-ios-sdk.md │ ├── using-contentful-xcode-plugin.md │ ├── using-delivery-api-on-ios.md │ ├── using-delivery-api-with-swift.md │ └── using-management-api-on-ios.md ├── java └── index.md ├── javascript ├── index.md └── tutorials │ ├── create-expressjs-app-using-contentful.md │ ├── default_website.png │ ├── keys_and_ids.png │ ├── using-js-cda-sdk.md │ └── using-the-sync-api-with-js.md ├── net ├── index.md └── tutorials │ ├── aspnet-core.md │ ├── management-api.md │ ├── using-net-cda-sdk.md │ └── webhook-roles-snapshots.md ├── php ├── index.md └── tutorials │ ├── getting-started-with-contentful-and-laravel.md │ ├── getting-started-with-contentful-and-php.md │ ├── getting-started-with-contentful-and-symfony.md │ └── using-the-sync-api-with-php.md ├── python ├── index.md └── tutorials │ ├── full-stack-getting-started.md │ └── getting-started-with-contentful-and-python.md ├── references ├── authentication.html.haml ├── content-delivery-api.md ├── content-management-api.md ├── content-preview-api.md ├── errors.md ├── http-details.md └── images-api.md ├── ruby ├── index.md └── tutorials │ ├── automated-rebuild-and-deploy-with-circleci-and-webhooks.md │ ├── create-your-own-rails-app.md │ ├── full-stack-getting-started.md │ ├── getting-started-with-contentful-and-ruby.md │ ├── getting-started-with-contentful-cma-and-ruby.md │ └── using-contentful-bootstrap-for-keeping-up-with-your-spaces.md ├── tools ├── applications.md ├── extensions.md ├── spacemanagement.md └── staticsitegenerators.md └── tutorials └── general ├── delivery-api-lambda-and-api-gateway.md ├── import-and-export.md └── scheduling-posts.md /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | .idea/ 3 | *.md.map 4 | *.md-e 5 | node_modules 6 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | node_js: 3 | - 6 4 | 5 | script: 6 | - ./generate-docs.sh 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # THIS REPOSITORY IS DEPRECATED 2 | 3 | Please do not open new PRs or issues. 4 | 5 | # Legacy README 6 | 7 | ## Contributing 8 | 9 | - __Do not__ modify manually files in the `docs/` directory. 10 | - __Do__ modify files in the `raw_dows/` directory. 11 | - Before opening a PR, run `./generate-docs.sh`. It'll prepare files in the `/docs` directory as described below. 12 | - Changes in both `raw_docs/` (manually introduced) and `docs/` (automatically generated) need to be committed to the repository. 13 | - After opening a PR, ping developers and ask for a review. 14 | 15 | ## Documentation generation 16 | 17 | Currently the `./generate-docs.sh` script does two things: 18 | 19 | ### Including other content 20 | 21 | You can use [hercule](https://github.com/jamesramsay/hercule) to include (transclude) other partial markdown files and reduce repetition. You can find the current partial files in the `raw_docs/_partials` folder and you include them with the following syntax: 22 | 23 | ``` 24 | :[Getting started tutorial intro](../../_partials/getting-started-intro.md) 25 | ``` 26 | 27 | ### Placeholders 28 | 29 | Placeholders for variables in code examples are enclosed in angled brackets, for example: 30 | 31 | ``` 32 | 33 | ``` 34 | 35 | When you build the documentation these are replaced with the real values you can find in `placeholder-replacements.sh` via the `sed` command. Feel free to add new variables you need. 36 | -------------------------------------------------------------------------------- /docs/android/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsAndroid 3 | name: Android 4 | title: Using Contentful with Android 5 | metainformation: 'Our Android SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - Basics 9 | - SDKs 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | - [Tools](#tools-and-integrations) 16 | - [Example apps](#example-apps) 17 | 18 | ## SDKs 19 | 20 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 21 | 22 | ### Content Delivery API SDK 23 | 24 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
25 | [View on GitHub](https://github.com/contentful/contentful.java)
26 | [API reference](https://contentful.github.io/contentful.java/) 27 | 28 | ### Content Management API SDK 29 | 30 | This SDK interacts with the Content Management API, and allows you to create, edit, manage, and publish content.
31 | [View on GitHub](https://github.com/contentful/contentful-management.java)
32 | [API reference](https://contentful.github.io/contentful-management.java/) 33 | 34 | ## Tutorials 35 | 36 | ### API demo 37 | 38 | [This guide](/developers/api-demo/java/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 39 | 40 | ### Getting started with the Content Delivery API SDK and Android 41 | 42 | [This tutorial](/developers/docs/android/tutorials/getting-started-with-contentful-and-android/) will walk you through the first steps using the Content Delivery API with a Java application. 43 | 44 | ### Offline persistence with Vault on Android 45 | 46 | [Vault](https://github.com/contentful/vault) is an Android library that lets you define Java representations for your Contentful models and simplifies the persistence of data from Contentful via SQLite.
47 | [View the tutorial](/developers/docs/android/tutorials/offline-persistence-with-vault/) 48 | 49 | ### Type retrieval 50 | 51 | [This tutorial](/developers/docs/android/tutorials/advanced-types/) helps you understand how to filter fetching entries from Contentful based on content and asset types. 52 | 53 | ### Filtering and searching 54 | 55 | [This tutorial](/developers/docs/android/tutorials/advanced-filtering-and-searching/) shows how to filter, search and order entries fetched from Contentful. 56 | 57 | ## Tools and integrations 58 | 59 | ### IntelliJ / Android Studio plugin 60 | 61 | This plugin generates model classes automatically from your Contentful content model.
62 | [View on GitHub](https://github.com/contentful/cf-generator-intellij) 63 | 64 | ### Vault 65 | 66 | A library to simplify persisting data retrieved from Contentful and storing it offline in SQLite.
67 | [View on GitHub](https://github.com/contentful/vault) 68 | 69 | ### Generator.java 70 | 71 | This tool helps you fetch content types from a Contentful space, and generate corresponding java source files.
72 | [View on GitHub](https://github.com/contentful/generator.java) 73 | 74 | ## Example apps 75 | 76 | These example apps are the best way to start building with Contentful. They show you how to start a project based on example spaces available in the Contentful web app. 77 | 78 | ### Discovery App 79 | 80 | This app lets you browse and preview your Contentful spaces.
81 | [Download on Google Play](https://play.google.com/store/apps/details?id=discovery.contentful)
82 | [View on GitHub](https://github.com/contentful/discovery-app-android) 83 | 84 | ### Blog 85 | 86 | A generic blog app connected to a Contentful example space.
87 | [Download on Google Play](https://play.google.com/store/apps/details?id=blog.contentful)
88 | [View on GitHub](https://github.com/contentful/blog-app-android) 89 | 90 | ### Gallery 91 | 92 | A generic gallery app connected to a Contentful example space.
93 | [Download on Google Play](https://play.google.com/store/apps/details?id=gallery.templates.contentful)
94 | [View on GitHub](https://github.com/contentful/gallery-app-android) 95 | 96 | ### Product catalogue 97 | 98 | A generic product catalogue / e-commerce app connected to a Contentful example space.
99 | [Download on Google Play](https://play.google.com/store/apps/details?id=catalogue.contentful)
100 | [View on GitHub](https://github.com/contentful/product-catalogue-android) 101 | 102 | ### Contentful Android Cardboard 103 | 104 | A example to show how to use Google VR with Contentful.
105 | [View on GitHub](https://github.com/contentful-labs/contentful-cardboard) 106 | -------------------------------------------------------------------------------- /docs/android/tutorials/content-type-id.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/docs/android/tutorials/content-type-id.png -------------------------------------------------------------------------------- /docs/android/tutorials/field-codename.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/docs/android/tutorials/field-codename.png -------------------------------------------------------------------------------- /docs/android/tutorials/story-fields.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/docs/android/tutorials/story-fields.png -------------------------------------------------------------------------------- /docs/concepts/apis.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsApis 3 | name: API basics 4 | title: Four content APIs 5 | metainformation: 'Contentful is an API first content management system, offering four REST APIs for working with your content.' 6 | slug: null 7 | tags: 8 | - API 9 | - Basics 10 | nextsteps: null 11 | --- 12 | 13 | Contentful is an API first content management system, offering four REST APIs for working with your content. Each of these APIs serve a different purpose, so which one to use depends on what you want to do: 14 | 15 | - If you're retrieving content to display to users in an app or website, use the [Content Delivery API][cda-section]. 16 | - If you want to programmatically create or update content items, use the [Content Management API][cma-section]. 17 | - If you want to retrieve unpublished content to show in-context previews to content creators and editors, use the [Preview API][cpa-section]. This API behaves like the Content Delivery API, but includes content that has not yet been published. 18 | - If you want to retrieve and apply transformations to images stored in Contentful, use the [Images API][images-section]. 19 | 20 | ## Content Delivery API 21 | 22 | The Content Delivery API (CDA), available at cdn.contentful.com, is a read-only API for delivering content from Contentful to apps, websites and other media. Content is delivered as JSON data, and images, videos and other media as files. 23 | 24 | The API is available via a globally distributed content delivery network. The server closest to the user serves all content, both JSON and binary. This minimizes latency, which especially benefits mobile apps. Hosting content in multiple global data centers also greatly improves the availability of content. 25 | 26 | For more details [read the reference guide for the Content Delivery API][1]. 27 | 28 | ## Content Management API 29 | 30 | The Content Management API (CMA), available at api.contentful.com, is a read-write API for managing content. Unlike the Content Delivery API, the management API requires you to authenticate as a Contentful user. You could use the CMA for several use cases, such as: 31 | 32 | - Automatic imports from different CMSes like WordPress or Drupal. 33 | - Integration with other backend systems, such as an e-commerce shop. 34 | - Building custom editing experiences. We built the [Contentful web app](https://app.contentful.com) on top of this API. 35 | 36 | {: .note} 37 | **Note**: You can also use the Content Management API to retrieve content. But as it's used to manage content, it will retrieve **all** items (i.e. all localized and unpublished content). 38 | 39 | For more details [read the reference documentation for the Content Management API][2]. 40 | 41 | ## Preview API 42 | 43 | The Preview API, available at preview.contentful.com, is a variant of the CDA for previewing your content before delivering it to your customers. You use the Preview API in combination with a "preview" deployment of your website (or a "preview" build of your mobile app) that allows content managers and authors to view their work in-context, as if it were published, using a "preview" access token as though it were delivered by the CDA. 44 | 45 | For more details [read the reference documentation for the Preview API][3]. 46 | 47 | ## Images API 48 | 49 | The Images API, available at images.contentful.com, allows you to resize and crop images, change their background color and convert them to different formats. Using our API for these transformations lets you upload high-quality assets, deliver exactly what your app needs, and still get all the benefits of our caching CDN. 50 | 51 | For more details [read the reference documentation for the Images API][4]. 52 | 53 | [1]: /developers/docs/references/content-delivery-api/ 54 | [2]: /developers/docs/references/content-management-api/ 55 | [3]: /developers/docs/references/content-preview-api/ 56 | [4]: /developers/docs/references/images-api/ 57 | [cda-section]: #content-delivery-api 58 | [cma-section]: #content-management-api 59 | [cpa-section]: #content-preview-api 60 | [images-section]: #images-api 61 | -------------------------------------------------------------------------------- /docs/concepts/sync.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsSync 3 | name: Synchronization 4 | title: Synchronization 5 | metainformation: 'The Sync API allows you to keep a local copy of all content in a space up-to-date via delta updates or content that has changed.' 6 | slug: null 7 | tags: 8 | - Basics 9 | - Content model 10 | nextsteps: 11 | - text: How to use the Sync API with a PHP project 12 | link: /developers/docs/php/tutorials/using-the-sync-api-with-php/ 13 | - text: Syncing offline content to an Android app 14 | link: /developers/docs/android/tutorials/offline-persistence-with-vault/ 15 | - text: Syncing offline content to an iOS app 16 | link: /developers/docs/ios/tutorials/offline-persistence-in-ios-sdk/ 17 | --- 18 | 19 | The Sync API allows you to keep a local copy of all content in a space up-to-date via [delta updates](https://en.wikipedia.org/wiki/Delta_update), or content that has changed. 20 | 21 | Mobile data connections can be slow with high latency compared to broadband internet connections. When apps sync content to the device and access it from a local database (e.g. Core Data, LocalStorage, SQLite) data access is faster and apps can provide a better user experience. 22 | 23 | Without a Sync API, applications require an ongoing internet connection and have to constantly download all data in each synchronization, including content they are already aware of. This wastes a lot of mobile data and time, especially when syncing on cellular data. 24 | 25 | Using the Sync API, applications sync periodically, syncing every few hours when opened or pending user interaction. To do this, it performs delta updates: 26 | 27 | - **Get** content added or changed since the last sync. 28 | - **Delete** local content deleted since the last sync. 29 | 30 | To enable delta updates, Contentful provides [a synchronization endpoint](/developers/docs/references/content-delivery-api/#/reference/synchronization) to the Content Delivery API. This endpoint delivers only new and changed content and notifies about deleted content. It will never transfer duplicate content the client has received before. 31 | 32 | If you are creating a mobile application, it's a good idea to package the initial data sync inside the app and update it with each new release. 33 | 34 | ## The upside 35 | 36 | Syncing with delta updates has the following advantages: 37 | 38 | - **Data usage reduction**: Most mobile data plans have limits on data transfers. By transferring only content that has changed, the amount of data used is small. Keeping the sync small also means an improved chance of success when a mobile connection is slow. 39 | - **Time saving**: Because individual syncs are small they will take less time than repeatedly loading data that hasn't changed. 40 | - **Less resource usage**: Less data to process also means less resources required for processing the data and less waiting time. 41 | - **Content entirety**: The initial sync will transfer all entries since the creation of the space alongside all available localizations, which doesn't happen in the Content Delivery API. 42 | 43 | ## The downside 44 | 45 | The synchronization endpoint will always return the content of a space or a specific content type, so it may not make sense to use it for every use case: 46 | 47 | - If users only want to see the newest content, it would be wasteful to download everything immediately. In this case, it might be better to only fetch selected content based on the date, using search. 48 | - Because the Sync API retrieves all localized content, it might be better to use the delivery API to retrieve results of a single locale. 49 | - Following the initial sync, the API will still transfer deleted entries, which lengthens each response. 50 | - The synchronization endpoint delivers a maximum of 100 items per page. You will need multiple requests to sync large data sets. 51 | 52 | ## Usage 53 | 54 | The first time you use the Sync API in your application, you need to specify the `initial` URL parameter: 55 | 56 | ~~~bash 57 | curl -X GET \ 58 | -H 'Authorization: Bearer b4c0n73n7fu1' \ 59 | 'https://cdn.contentful.com/spaces/cfexampleapi/sync?initial=true' 60 | ~~~ 61 | 62 | The response will contain a `nextPageUrl` value if your request returned more results than fit into a single page. When retrieving the last page, the response will contain a `nextSyncUrl` which contains a sync token you can use to receive delta updates of changes since your last request. 63 | 64 | In addition to the regular `Entry` and `Asset` item types, there can also be `DeletedEntry` and `DeletedAsset` items in the synchronization response. These show that a specific resource has been deleted as delta updates work at the resource level, if a resource has changed, its whole content will be part of the synchronization response. 65 | 66 | ## Localization 67 | 68 | Syncing entries or assets returns all available localizations instead of a single one. Usually resources returned from the delivery API have only a single value per field, the value of the locale you requested or the default locale, but the sync endpoint returns all locales per field. 69 | 70 | ## Further information 71 | 72 | - Using the Sync API for [offline persistence on iOS](/developers/docs/ios/tutorials/offline-persistence-in-ios-sdk/). 73 | - Using synchronization with the [Content Delivery API](/developers/docs/references/content-delivery-api/#/reference/synchronization). 74 | - Using synchronization with the [PHP SDK](/developers/docs/php/tutorials/using-the-sync-api-with-php/). 75 | - Using synchronization with the [JavaScript SDK](/developers/docs/javascript/tutorials/using-the-sync-api-with-js/). 76 | -------------------------------------------------------------------------------- /docs/concepts/uiextensions.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsUiExtensions 3 | name: UI Extensions 4 | title: UI Extensions 5 | metainformation: 'The UI Extensions SDK allows you to customize and extend the functionality of the Contentful Web App entry editor.' 6 | slug: null 7 | tags: 8 | - Customization 9 | nextsteps: 10 | - text: Integrate Contentful with other services via Webhooks 11 | link: /developers/docs/concepts/webhooks/ 12 | - text: Tools and libraries to make your Contentful experience better 13 | link: /developers/docs/tools/extensions/ 14 | --- 15 | 16 | The [UI Extensions SDK](https://github.com/contentful/ui-extensions-sdk) allows you to customize and extend the functionality of the Contentful Web App's entry editor. The editor itself is a container for components that enable editors to manipulate the content stored in content fields. Extensions can be simple user interface controls, such as a dropdown, or more complex micro web applications such as our Markdown editor. Extensions are decoupled entities from field types, and you can reuse them, for example using a dropdown to edit number or text fields. Custom extensions that you create are rendered inside a secure iframe. 17 | 18 | ## Examples 19 | 20 | We have created some example extensions to help you understand how to create your own. 21 | 22 | ### Basic rating dropdown 23 | 24 | A dropdown component to change the value of a number field and make a Content Management API request. 25 | 26 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/rating-dropdown) 27 | 28 | {: .img} 29 | ![Basic rating dropdown extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/45NRCrYg8gwKW08kug8M2W/3050ef93c62eff65642dc29d0cb8821d/BBD4DC36-163A-43A4-B13F-8AE5F6993434.png_dl_1) 30 | 31 | ### Rich text editor 32 | 33 | This example integrates the Alloy rich text editor into text fields. 34 | 35 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/alloy-editor) 36 | 37 | {: .img} 38 | ![Rich text editor extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/3Rzmmj2fuEgwg6kwQ8kSmg/4e9dc78ee1fc95df3bd6063c73fd9bc6/9CDF5788-57FC-444C-8199-04408341F0D7.png_dl_1) 39 | 40 | ### Chessboard 41 | 42 | This extension displays a chessboard and stores the board position as a JSON object. You can drag pieces on the chessboard and the position data updates automatically. The extension also supports collaborative editing, so if two editors open the same entry, moves are synced between them. 43 | 44 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/chessboard) 45 | 46 | {: .img} 47 | ![Chessboard extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/1cSM1cmGUKIIMqcAI8KE4u/c740287f67d682ffbbc014665500efe0/B58EE807-A598-478E-A509-C7203A0C35A2.gif_dl_1) 48 | 49 | ### Slug generator 50 | 51 | This extension automatically generates its value from the title field of an entry. For example typing "Hello World" into the title field will set the extensions input field to "hello-world". It will also check the uniqueness of the slug across a customizable list of content types. 52 | 53 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/slug) 54 | 55 | {: .img} 56 | ![Slug generator extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/3JUTcNxs7eSkIMKgKeCA62/2f0bcb05d409436c322fb425f8838c78/D0B28EA2-9E86-4A23-ACE0-EED81A758A6D.png_dl_1) 57 | 58 | ### Translator 59 | 60 | This extension translates text from the default locale to other locales in a space using the Yandex translation API. 61 | 62 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/translate) 63 | 64 | {: .img} 65 | ![Translator extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/4qrgjGbN7y0oMYSkS6cyko/ee50c251463c954ec875ee35775deefa/92CB0364-E3DA-4649-9D99-8458D7A6A6DD.png_dl_1) 66 | 67 | ### JSON editor 68 | 69 | This extension formats and validates JSON based on the CodeMirror library. You can use it with fields of type "Object". 70 | 71 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/json-editor) 72 | 73 | {: .img} 74 | ![Translator extension](https://images.contentful.com/tz3n7fnw4ujc/47FwXETOc0E4u8U62sImq4/b409b273b03a1ed897c88d576ad5e6af/C020349F-ECC0-49D8-A22F-B143F4233F2C.png_dl_1) 75 | 76 | ### JSON form editor 77 | 78 | This extension integrates the JSON editor library to display an edit form based on a predefined JSON schema. The form input gets stored as a JSON object. 79 | 80 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/json-form-editor) 81 | 82 | {: .img} 83 | ![Translator extension](https://images.contentful.com/tz3n7fnw4ujc/1M9qxfkvLqi4wI0GGASMwq/5da14e00202b17ae754aedcafe662c5a/E200B073-BC43-4B2E-A89B-6EC48D5AD722.png_dl_1) 84 | 85 | ### YouTube ID 86 | 87 | This extension extracts the video id from a valid YouTube URL for a simple way to integrate with 3rd party media services. 88 | 89 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/youtube-id) 90 | 91 | {: .img} 92 | ![YouTube ID extension](https://images.contentful.com/tz3n7fnw4ujc/4M2yCNPQTK8wmiSGmmKIaI/36ec7f8fc7990fff1b521da1dcb359b0/ACC6E270-9904-45F6-94E2-FE0ECEAEADD1.png_dl_1) 93 | 94 | ### Wistia Videos 95 | 96 | The extension loads videos from a project on [wistia](https://wistia.com/) into the Contentful Web Application. A video can be previewed, selected and then stored as part of your content. 97 | 98 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/wistia) 99 | 100 | {: .img} 101 | ![Wistia Video extension](https://images.contentful.com/tz3n7fnw4ujc/4Olj3gwXIAEMCqscKIq0yC/68f37a3b6a5daf2664e0b2b3aad6063e/D1F4EE3E-D811-4C4C-BBA5-C990E5B1DD85.gif_dl_1) 102 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsOverview 3 | name: Developer center 4 | title: Developer center 5 | subtitle: Learn how to build with Contentful 6 | metainformation: Everything you need to understand and use Contentful. Includes an overview of concepts, API reference, tutorials, SDKs and code samples. 7 | --- 8 | 9 | You're in the right place to find everything you need to deeper understand and use Contentful. This includes an overview of Contentful concepts, API references, tutorials, details of SDKs and libraries for major platforms, helpful tools and code samples. 10 | 11 | ## Concepts 12 | 13 | These concepts introduce the basics of Contentful. This is the best place to start if you haven't built anything with Contentful before. 14 | 15 | - [API basics](/developers/docs/concepts/apis/) 16 | - [Content model](/developers/docs/concepts/data-model/) 17 | - [Links](/developers/docs/concepts/links/) 18 | - [Images](/developers/docs/concepts/images/) 19 | - [Locales](/developers/docs/concepts/locales/) 20 | - [Synchronization](/developers/docs/concepts/sync/) 21 | - [Multiple environments](/developers/docs/concepts/multiple-environments/) 22 | - [Webhooks](/developers/docs/concepts/webhooks/) 23 | - [Editor interfaces](/developers/docs/concepts/editor-interfaces/) 24 | - [UI extensions](/developers/docs/concepts/uiextensions/) 25 | 26 | ## Reference 27 | 28 | Our four APIs are the core of Contentful, with each one serving a specific purpose: 29 | 30 | - [Content Delivery API](/developers/docs/references/content-delivery-api/) for retrieving content. 31 | - [Content Management API](/developers/docs/references/content-management-api/) for managing content (e.g. creating, updating and deleting content). 32 | - [Preview API](/developers/docs/references/content-preview-api/) for previewing the content before publishing it to production. 33 | - [Images API](/developers/docs/references/images-api/) for requesting images in specific sizes and formats. 34 | 35 | These guides will help you answer questions you have when using our APIs: 36 | 37 | - [Authentication](/developers/docs/references/authentication/) 38 | - [Errors](/developers/docs/references/errors/) 39 | - [HTTP response details](/developers/docs/references/http-details/) 40 | 41 | ## Platforms 42 | 43 | We provide libraries and SDKs for major programming languages and platforms so you don't have to write code for interacting with our APIs from scratch. 44 | 45 | - [Android](/developers/docs/android/) 46 | - [Java](/developers/docs/java/) 47 | - [Objective-C / Swift](/developers/docs/ios/) 48 | - [JavaScript](/developers/docs/javascript/) 49 | - [PHP](/developers/docs/php/) 50 | - [Ruby](/developers/docs/ruby/) 51 | - [Python](/developers/docs/python/) 52 | - [.NET](/developers/docs/net/) 53 | 54 | ## Tools 55 | 56 | We have content import/export tools, iOS and Android development plugins and more, all designed to help speed up development. 57 | 58 | - [Static site generators](/developers/docs/tools/staticsitegenerators/) 59 | - [Space management tools](/developers/docs/tools/spacemanagement/) 60 | - [Extensions](/developers/docs/tools/extensions/) 61 | - [Others and third party tools](/developers/docs/tools/applications/) 62 | 63 | ## More 64 | 65 | Looking for support or detail on our release schedule? 66 | 67 | - [Changelog](/developers/changelog/) 68 | - [Support](https://support.contentful.com/hc/en-us/requests/new) 69 | - [Stack Overflow](http://stackoverflow.com/questions/tagged/contentful?sort=newest) 70 | -------------------------------------------------------------------------------- /docs/ios/tutorials/content-type-id.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/docs/ios/tutorials/content-type-id.png -------------------------------------------------------------------------------- /docs/ios/tutorials/using-contentful-xcode-plugin.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsContentfulXcode 3 | name: Using the Contentful Xcode Plugin 4 | title: Using the Contentful Xcode Plugin 5 | metainformation: 'Our plugin for Xcode generates a Core Data model directly from your content model.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - iOS 10 | - Mobile 11 | nextsteps: 12 | - text: Learn more about content modelling 13 | link: /developers/docs/concepts/data-model/ 14 | --- 15 | 16 | If you are using Contentful with Core Data in your iOS app, a painful manual step is recreating your content model inside Xcode. This is often both time consuming and prone to errors because mismatches between the two models can lead to bugs that are hard to spot. Today we are releasing a plugin for Xcode, which generates a Core Data model directly from your content model, making it easier than ever to use the Content Delivery API in your iOS and macOS projects. 17 | 18 | ## Installation 19 | 20 | You can either clone the [repository][1] and build the plugin yourself or install the [binary release][9]. Installing via [Alcatraz][2] is not supported right now. 21 | 22 | ## Usage 23 | 24 | The plugin adds a new "Generate Model from Contentful..." item to the "Product" menu. 25 | 26 | ![Screen Shot 2014-11-26 at 13.51.52](//images.contentful.com/256tjdsmm689/1Qyzs5KFkkyiIiky0ccYmk/9deb635fae91511e8ceaf9a9cdee858b/Screen_Shot_2014-11-26_at_13.51.52.png) 27 | 28 | This will bring up a dialog where, after providing your CMA access token, you will be able to select a space and a target from your Xcode project. 29 | 30 | ![Screen Shot 2014-11-26 at 13.52.04](//images.contentful.com/256tjdsmm689/6uNk5czVx6COwMy8oauyys/072bbb82082553dd8490262175473638/Screen_Shot_2014-11-26_at_13.52.04.png) 31 | 32 | Using this information, a Core Data model for use with our [CoreDataManager class][3] will be generated and added to the specified target. The file itself will reside in the *"Resources"* group or in the root if that doesn't exist. 33 | 34 | Keep in mind that your own `NSManagedObject` subclasses will still need to conform to the `CDAPersistedAsset`, `CDAPersistedEntry` and `CDAPersistedSpace` protocols as before. You will not need to provide a mapping between your content model and Core Data anymore, though, as this is [derived automatically][4] if field and property names match, which is always the case when using the plugin. 35 | 36 | It is also required that you add [content type validations][5] for any links in your content model, as links in Core Data are always typed. If you require one link field to refer to entries of different content types, your model cannot be represented by Core Data and therefore the model generation will fail and tell you which content type’s field was the culprit. 37 | 38 | You can also use the model generator from the commandline: 39 | 40 | ~~~ bash 41 | ContentfulModelGenerator generate \ 42 | --spaceKey=$CONTENTFUL_SPACE_KEY \ 43 | --accessToken=$CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN 44 | ~~~ 45 | 46 | As there are a lot of ways of building your content model, please report any issues with the generator so that we can continue to improve it in the future. 47 | 48 | ## Implementation 49 | 50 | As an introduction to writing Xcode plugins, you can check out the writing plugins post on the [Alcatraz][2] blog. 51 | 52 | This plugin is generally rather small, because the majority of the work does not involve Xcode. The class [XcodeProjectManipulation][6] demonstrates how to interact with the project file using the `PBXProject` class from the `DevToolsCore` framework. 53 | 54 | The Core Data model generation revolves around two parts and is encapsulated in a separate commandline utility. This allows its use in build scripts and also avoids problems regarding the use of Swift dependencies in a plugin written in Objective-C. 55 | 56 | The first part is converting from the content model to a `NSManagedObjectModel` instance, accomplished by the [ContentfulModelGenerator][7]. A managed object model consists of `NSEntityDescription` instances, which in turn are a container for `NSAttributeDescription` and `NSRelationshipDescription` objects. The latter is the most critical part, because we have to ensure that each relationship is typed and has an inverse to avoid any warnings when using the model. This is done by introspecting the validations on your content model and by creating missing inverse relations where needed. 57 | 58 | The second part is handled by the [ManagedObjectModelSerializer][8] framework we created, which generates the XML representation from an in-memory `NSManagedObjectModel` instance. This can be utilized to write other tools which need to generate Core Data models and it has a really simple API: 59 | 60 | ~~~ swift 61 | let bundleName = "MyModel" 62 | let model: NSManagedObjectModel 63 | let pathURL: NSURL 64 | 65 | let error = ModelSerializer(model: model!).generateBundle(bundleName, atPath:pathURL) 66 | ~~~ 67 | 68 | [1]: https://github.com/contentful/ContentfulXcodePlugin 69 | [2]: http://alcatraz.io 70 | [3]: /blog/2014/05/09/ios-content-synchronization/ 71 | [4]: https://github.com/contentful/contentful.objc/commit/b82c0f2a68095e28d0d127bd9d070b09daf9b9ed 72 | [5]: /r/knowledgebase/validations/ 73 | [6]: https://github.com/contentful/ContentfulXcodePlugin/blob/master/Code/XcodeProjectManipulation.m 74 | [7]: https://github.com/contentful/ContentfulXcodePlugin/blob/master/Code/ContentfulModelGenerator.m 75 | [8]: https://github.com/contentful/ManagedObjectModelSerializer 76 | [9]: https://github.com/contentful/ContentfulXcodePlugin/releases/tag/0.3 77 | -------------------------------------------------------------------------------- /docs/ios/tutorials/using-management-api-on-ios.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsCmaIos 3 | name: Using the Management API on iOS 4 | title: Using the Management API on iOS 5 | metainformation: This post will walk you through implementing a simple iOS app for uploading images from the device Camera Roll to Contentful. 6 | slug: null 7 | tags: 8 | - CMA 9 | - iOS 10 | - Mobile 11 | nextsteps: 12 | - text: The Contentful Management API reference 13 | link: /developers/docs/references/content-management-api/ 14 | --- 15 | 16 | This post will walk you through implementing a simple iOS app for uploading images from the device's Camera Roll to Contentful. 17 | 18 | Like the [CDA SDK][1] before, you simply install the CMA SDK via [CocoaPods][2]: 19 | 20 | ~~~objc 21 | platform :ios, '7.0' 22 | pod 'ContentfulManagementAPI' 23 | ~~~ 24 | 25 | In the project's [README][3], you can also find explanations for other options, like Git submodules or a pre-built static framework. 26 | 27 | After you successfully installed the library you need to create a client object. For this you need to obtain a Content Management API token. A token can easily be obtained in the [developer center][4]. 28 | 29 | With it, you can instantiate a client object: 30 | 31 | ~~~objc 32 | CMAClient* client = [[CMAClient alloc] initWithAccessToken:@"your-token"]; 33 | ~~~ 34 | 35 | Next we need to fetch a space to use. Contrary to the Content Delivery API, we can just list all spaces the given account has access to: 36 | 37 | ~~~objc 38 | [client fetchAllSpacesWithSuccess:^(CDAResponse *response, CDAArray *array) { 39 | self.spaces = array.items; 40 | 41 | [self.tableView reloadData]; 42 | } failure:^(CDAResponse *response, NSError *error) { 43 | NSLog(@"Error: %@", error); 44 | }]; 45 | ~~~ 46 | 47 | ![In our app, they are displayed as a list of names in a table view](https://images.contentful.com/m5kgizmngfqu/2qSSJ4l0IYQq2WeoaAoUOc/b88666a983860c36385f3d0cccc10244/table-view.png?w=250) 48 | 49 | Once we have selected a specific space, we can create resources, in our case an asset. This can be done using the [`-createAssetWithTitle:description:fileToUpload:success:failure:`][5] method. For this, we need to specify an URL to a file, though and we just have a local image in the photo library at the moment. For a temporary upload, we use [this Pod][6], which just gives us a file URL back, as we need it: 50 | 51 | ~~~objc 52 | [[BBUUploadsImUploader sharedUploader] uploadImage:someImage 53 | completionHandler:^(NSURL *uploadURL, NSError *error) { 54 | if (!uploadURL) { 55 | NSLog(@"Error: %@", error); 56 | return; 57 | } 58 | 59 | NSLog(@"URL of uploaded image: %@", uploadURL); 60 | }]; 61 | ~~~ 62 | 63 | We can obtain the latest photo from the Camera Roll using the `AssetsLibrary` framework quite easily: 64 | 65 | ~~~objc 66 | -(void)fetchLatestPhotoWithCompletionHandler:(void (^)(UIImage* latestPhoto, NSError* error))handler { 67 | NSParameterAssert(handler); 68 | 69 | ALAssetsLibrary *library = [ALAssetsLibrary new]; 70 | 71 | [library enumerateGroupsWithTypes:ALAssetsGroupSavedPhotos usingBlock:^(ALAssetsGroup *group, 72 | BOOL *stop) { 73 | [group setAssetsFilter:[ALAssetsFilter allPhotos]]; 74 | 75 | [group enumerateAssetsWithOptions:NSEnumerationReverse usingBlock:^(ALAsset *alAsset, 76 | NSUInteger index, 77 | BOOL *innerStop) { 78 | if (alAsset) { 79 | ALAssetRepresentation *representation = [alAsset defaultRepresentation]; 80 | UIImage *latestPhoto = [UIImage imageWithCGImage:[representation fullScreenImage]]; 81 | 82 | *stop = YES; *innerStop = YES; 83 | 84 | handler(latestPhoto, nil); 85 | } 86 | }]; 87 | } failureBlock: ^(NSError *error) { 88 | handler(nil, error); 89 | }]; 90 | } 91 | ~~~ 92 | 93 | Using the upload URL, we can create our asset and start the processing of the image: 94 | 95 | ~~~objc 96 | [self.space createAssetWithTitle:@{ @"en-US": @"Some image caption" } 97 | description:@{ @"en-US": @"Upload from iOS" } 98 | fileToUpload:@{ @"en-US": uploadURL.absoluteString } 99 | success:^(CDAResponse *response, CMAAsset *asset) { 100 | [asset processWithSuccess:^{ 101 | NSLog(@"Upload successful."); 102 | } failure:^(CDAResponse *response, NSError *error) { 103 | NSLog(@"Error: %@", error); 104 | }]; 105 | } failure:^(CDAResponse *response, NSError *error) { 106 | NSLog(@"Error: %@", error); 107 | }]; 108 | ~~~ 109 | 110 | As you can see, the Content Management API allows us the specify values for different locales in just one API call. Keep in mind that [`-processWithSuccess:failure:`][7] is asynchronous and will not report errors of the actual image processing back. If it was successful, you can publish the resulting asset from the Contentful [web app][8] as you normally would. 111 | 112 | ![such content, very uploading, wow](https://images.contentful.com/m5kgizmngfqu/31PAoh4jVCqeEKYICEsSkA/0758f8b5bc927ac77a280fa52bf81060/uploading.png?w=250) 113 | 114 | When building the app, be aware that it will automatically upload the lastest image from your Camera Roll. Also, we have the SDK [on GitHub][10] and the API documentation [on CocoaDocs][11]. 115 | 116 | [1]: https://github.com/contentful/contentful.objc 117 | [10]: https://github.com/contentful/contentful-management.objc 118 | [11]: http://cocoadocs.org/docsets/ContentfulManagementAPI 119 | [2]: https://cocoapods.org/ 120 | [3]: https://github.com/contentful/contentful-management.objc#installation 121 | [4]: /developers/docs/references/authentication/ 122 | [5]: http://cocoadocs.org/docsets/ContentfulManagementAPI/0.5.1/Classes/CMASpace.html#//api/name/createAssetWithTitle:description:fileToUpload:success:failure: 123 | [6]: https://github.com/neonichu/IAmUpload 124 | [7]: http://cocoadocs.org/docsets/ContentfulManagementAPI/0.5.1/Classes/CMAAsset.html#//api/name/processWithSuccess:failure: 125 | [8]: https://app.contentful.com/ 126 | -------------------------------------------------------------------------------- /docs/java/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsJava 3 | name: Java 4 | title: Using Contentful with Java 5 | metainformation: 'Our Java SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: null 8 | nextsteps: null 9 | --- 10 | 11 | - [SDKs](#sdks) 12 | - [Tutorials](#tutorials) 13 | - [Tools](#tools-and-integrations) 14 | - [Example apps](#example-apps) 15 | 16 | ## SDKs 17 | 18 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 19 | 20 | ### Content Delivery API SDK 21 | 22 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
23 | [View on GitHub](https://github.com/contentful/contentful.java)
24 | [API reference](https://contentful.github.io/contentful.java/) 25 | 26 | ### Content Management API SDK 27 | 28 | This SDK interacts with the Content Management API, and allows you to create, edit, manage, and publish content.
29 | [View on GitHub](https://github.com/contentful/contentful-management.java)
30 | [API reference](https://contentful.github.io/contentful-management.java/) 31 | 32 | ## Tutorials 33 | 34 | ### Create and deploy a Java application using Contentful 35 | 36 | [This guide](https://github.com/contentful/product-catalogue-java) shows you how to create and deploy a web application with Java and Spring Boot that uses Contentful. 37 | 38 | ### API demo 39 | 40 | [This guide](/developers/api-demo/java/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 41 | 42 | ## Tools and integrations 43 | 44 | ## Example apps 45 | 46 | These example apps are the best way to start building with Contentful. They show you how to start a project based on example spaces available in the Contentful web app. 47 | 48 | ### Product catalogue 49 | 50 | A generic product catalogue / e-commerce app connected to a Contentful example space.
51 | [View on GitHub](https://github.com/contentful/product-catalogue-java) 52 | -------------------------------------------------------------------------------- /docs/javascript/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsJavascript 3 | name: JavaScript 4 | title: Using Contentful with JavaScript 5 | metainformation: 'Our JavaScript SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - Basics 9 | - SDKs 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | - [Tools](#tools-and-integrations) 16 | - [Example apps](#example-apps) 17 | 18 | ## SDKs 19 | 20 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 21 | 22 | ### Content Delivery API SDK 23 | 24 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
25 | [View on GitHub](https://github.com/contentful/contentful.js)
26 | [SDK reference](https://contentful.github.io/contentful.js)
27 | [Try out the browser SDK with JSFiddle](https://jsfiddle.net/contentful/kefaj4s8/)
28 | [Try out the Node.js package with Tonic](https://runkit.com/npm/contentful) 29 | 30 | ### Content Management API SDK 31 | 32 | This SDK interacts with the Content Management API, and allows you to create, edit, manage, and publish content. The API also offers tools for managing editorial teams and cooperation.
33 | [View on GitHub](https://github.com/contentful/contentful-management.js)
34 | [SDK reference](https://contentful.github.io/contentful-management.js/contentful-management/1.3.0) 35 | 36 | ## Tutorials 37 | 38 | ### Create and deploy a Node.js application using Contentful 39 | 40 | [This guide](/developers/docs/javascript/tutorials/create-expressjs-app-using-contentful/) shows you how to create and deploy an Express.js app that uses Contentful. 41 | 42 | ### API demo 43 | 44 | [This guide for JavaScript](/developers/api-demo/javascript/) and [this guide for Node.js](/developers/api-demo/nodejs/) are the perfect starting points to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 45 | 46 | ### Getting started with the Content Delivery API SDK and JavaScript 47 | 48 | [This tutorial](/developers/docs/javascript/tutorials/using-js-cda-sdk/) will walk you through the first steps using the Content Delivery API with a JavaScript application. 49 | 50 | ### Using the Sync API with JavaScript 51 | 52 | The Sync API allows you to keep a local copy of all content from a space up to date via delta updates. [This tutorial](/developers/docs/javascript/tutorials/using-the-sync-api-with-js/) will show you how to use the Sync API with the Contentful JavaScript SDK. 53 | 54 | ## Example apps 55 | 56 | ### Product catalogue 57 | 58 | This demo project shows how to build a frontend JavaScript based application with Contentful for a product catalogue, based on the Contentful starter product catalogue example space.
59 | [Try it out](https://contentful.github.io/product-catalogue-js/)
60 | [View on GitHub](https://github.com/contentful/product-catalogue-js) 61 | 62 | ### Photo gallery 63 | 64 | This single page application shows how to build a photo gallery app with [React](https://facebook.github.io/react/) connected to a Contentful space.
65 | [Try it out](https://contentful.github.io/gallery-app-react/)
66 | [View on GitHub](https://github.com/contentful/gallery-app-react) 67 | 68 | ### Discovery app 69 | 70 | The Discovery App allows you to browse and preview your Contentful content.
71 | [Try it out](https://contentful.github.io/discovery-app-react)
72 | [View on GitHub](https://github.com/contentful/discovery-app-react) 73 | 74 | ## Tools and integrations 75 | 76 | These third-party libraries are **not officially supported** by Contentful and may be incomplete. If you want to include your own libraries on this list open a pull request that matches our [contribution guidelines](https://github.com/contentful-labs/awesome-contentful/blob/master/CONTRIBUTING.md). 77 | 78 | ### Angular-Contentful 79 | 80 | An **unsupported** AngularJS library to access the Content Delivery API.
81 | [View on GitHub](https://github.com/jvandemo/angular-contentful) 82 | -------------------------------------------------------------------------------- /docs/javascript/tutorials/create-expressjs-app-using-contentful.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsExpressjsApp 3 | name: Creating an Express JavaScript application with Contentful 4 | title: Creating an Express JavaScript application with Contentful 5 | metainformation: 'This guide will walk you through your first steps using Contentful with an Express Node.js application.' 6 | slug: null 7 | tags: 8 | - JavaScript 9 | - SDKs 10 | nextsteps: 11 | - text: Using the Contentful Delivery API in a JavaScript app 12 | link: /developers/docs/javascript/tutorials/using-js-cda-sdk/ 13 | - text: How to only update content that has changed 14 | link: /developers/docs/javascript/tutorials/using-the-sync-api-with-js/ 15 | --- 16 | 17 | This guide will walk you through your first steps using Contentful with an Express Node.js application. It will provide a step-by-step guide on how to get your first entries and start using the content you create on Contentful. 18 | 19 | ## Requirements 20 | 21 | - A [Heroku][1] account 22 | - [Heroku CLI][14] installed 23 | - [Node.js][2] 6.2.1 installed 24 | - Npm 3.10.7 which should be installed with `Node.js` 25 | - [Git][12] installed 26 | - Basic Command Line Interface knowledge 27 | 28 | ## Check out the final project 29 | 30 | You can deploy the final project to Heroku to see how it works by clicking the button below. 31 | 32 | [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/contentful/contentful_express_tutorial) 33 | 34 | ## Start from a demo application 35 | 36 | First we'll start with a [demo project][3], which is a simple Express.js application using Contentful's 'Product Catalogue' template, so that you can see it running for yourself. 37 | 38 | Run the following commands to get started. 39 | 40 | - Clone the example repository: 41 | 42 | ~~~bash 43 | git clone https://github.com/contentful/contentful_express_tutorial.git 44 | ~~~ 45 | 46 | - Navigate into the repository's directory: 47 | 48 | ~~~bash 49 | $ cd contentful_express_tutorial 50 | ~~~ 51 | 52 | - Install dependencies: 53 | 54 | ~~~bash 55 | $ npm install 56 | ~~~ 57 | 58 | - Run the server: 59 | 60 | ~~~bash 61 | $ npm run dev 62 | ~~~ 63 | 64 | Everything is now set up. You can view your new data by opening _http://localhost:3000_ in your browser. 65 | 66 | It should look something like this: 67 | 68 | ![Express js Demo Application](./default_website.png) 69 | 70 | ### Using your own content 71 | 72 | You can create your own custom data by following these steps: 73 | 74 | - Create an account with [Contentful][6] or [Log In][5]. 75 | - Create a new Space with the 'Product Catalogue' template, name it whatever you like. 76 | - Copy the space Id and API key as shown in the screenshot 77 | 78 | ![Keys Page](keys_and_ids.png) 79 | 80 | - In the Express js application: 81 | 82 | - navigate to the package.json file open it and change the values `accessToken` and `space` in the `config` section and save. 83 | - run `npm run dev` to start the server 84 | - Your space will be now displayed in your application 85 | 86 | Next in the [Contentful web app][6] > Content: 87 | 88 | - Open the product called 'Playsam Streamliner Classic Car, Espresso'. 89 | - Change the value of the _Product name_ field to a new value, 90 | - Click the _Publish changes_ button 91 | - Wait a few seconds for the changes to propagate to the CDN. 92 | - Reload your Express js application and you will see the new product name. 93 | 94 | You can continue to edit your content inside the [Contentful web app][13] and see the content change inside your application. 95 | 96 | ### Deploy the demo to Heroku 97 | 98 | To view the demo application live in your own production environment, follow these steps: 99 | 100 | - Having Heroku CLI Installed, Login to Heroku if you're not logged in already: 101 | 102 | ~~~bash 103 | heroku login 104 | ~~~ 105 | 106 | - Create a new instance: 107 | 108 | ~~~bash 109 | heroku create 110 | ~~~ 111 | 112 | - Commit your change: 113 | 114 | ~~~bash 115 | git add . 116 | git commit -m "Add Website" 117 | ~~~ 118 | 119 | - Deploy to Heroku: 120 | 121 | ~~~bash 122 | git push heroku master 123 | ~~~ 124 | 125 | - Open the application in your browser: 126 | 127 | ~~~bash 128 | heroku open 129 | ~~~ 130 | 131 | ## Next Steps 132 | 133 | After this guide, you should be able to start using Contentful with your Express js applications, but every project has different needs and we want to provide you with the best solutions we can. 134 | 135 | You can read about the Contentful CDA library in more detail on our [contentful.js GitHub][1] or our [Getting Started with CDA SDK tutorial][9]. We also suggest taking a look at our [Product Example Application][10]. 136 | 137 | Do you like building static sites? Check how to build static sites using Contentful with [Metalsmith][11] 138 | 139 | [1]: https://www.heroku.com 140 | [10]: https://github.com/contentful/product-catalogue-js 141 | [11]: https://github.com/contentful-labs/contentful-metalsmith-example 142 | [12]: https://git-scm.com/downloads 143 | [14]: https://devcenter.heroku.com/articles/heroku-cli#download-and-install 144 | [2]: https://nodejs.org 145 | [3]: https://github.com/contentful/contentful_express_tutorial 146 | [5]: /sign-up/#starter 147 | [6]: https://app.contentful.com 148 | [7]: /developers/docs/references/content-delivery-api/#/reference/search-parameters 149 | [8]: https://github.com/contentful/contentful.js 150 | [9]: /developers/docs/javascript/tutorials/using-js-cda-sdk/ 151 | -------------------------------------------------------------------------------- /docs/javascript/tutorials/default_website.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/docs/javascript/tutorials/default_website.png -------------------------------------------------------------------------------- /docs/javascript/tutorials/keys_and_ids.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/docs/javascript/tutorials/keys_and_ids.png -------------------------------------------------------------------------------- /docs/javascript/tutorials/using-the-sync-api-with-js.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsSyncApiWithJS 3 | name: Using the Sync API with JavaScript 4 | title: Using the Sync API with JavaScript 5 | metainformation: 'This tutorial will show you how to use the Sync API with the Contentful JavaScript SDK to keep a local copy of content up to date via delta updates.' 6 | slug: null 7 | tags: 8 | - Basics 9 | - Content model 10 | nextsteps: 11 | - text: Further details on our Syncronization endpoint 12 | link: /developers/docs/references/content-delivery-api/#/reference/synchronization/ 13 | --- 14 | 15 | The [sync](/developers/docs/concepts/sync/) API allows you to keep a local copy of all content of a space up to date via delta updates. This tutorial will show you how to use the Sync API with the Contentful JavaScript SDK. 16 | 17 | This tutorial shows some examples using the [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) API on a browser, but you can also use any other [storage](https://github.com/localForage/localForage) [wrapper](https://pouchdb.com/) or any [storage layer](https://github.com/Level/levelup) in Node.js. 18 | 19 | ## Getting started 20 | 21 | After you've [installed the SDK](/developers/docs/javascript/tutorials/using-js-cda-sdk/#setting-up-the-client) you'll need to setup the client with your credentials: 22 | 23 | ~~~javascript 24 | var client = contentful.createClient({ 25 | space: 'cfexampleapi', 26 | accessToken: 'b4c0n73n7fu1' 27 | }) 28 | ~~~ 29 | 30 | Now you can run your first sync: 31 | 32 | ~~~javascript 33 | client.sync({initial: true}) 34 | .then((response) => { 35 | console.log(response.entries) 36 | console.log(response.assets) 37 | }) 38 | ~~~ 39 | 40 | As this is the first sync, your response will contain all existing entries and assets. 41 | 42 | Any links from entries to other entries and assets will also be resolved. If you don't want that to happen, you can turn it off: 43 | 44 | ~~~javascript 45 | client.sync({ 46 | initial: true, 47 | resolveLinks: false 48 | }) 49 | .then((response) => { 50 | console.log(response.entries) 51 | console.log(response.assets) 52 | }) 53 | ~~~ 54 | 55 | If you'd like to store the retrieved content, you can use the convenient `toPlainObject` method or `stringifySafe` to prevent issues with circular links, for example: 56 | 57 | ~~~javascript 58 | client.sync({initial: true}) 59 | .then((response) => { 60 | const responseObj = JSON.parse(response.stringifySafe()); 61 | const entries = responseObj.entries; 62 | window.localStorage.setItem('contentfulEntries', JSON.stringify(entries)) 63 | }) 64 | ~~~ 65 | 66 | 67 | Your response will also contain a token, which you should store: 68 | 69 | ~~~javascript 70 | client.sync({initial: true}) 71 | .then((response) => { 72 | window.localStorage.setItem('contentfulSyncToken', response.nextSyncToken) 73 | }) 74 | ~~~ 75 | 76 | ### Continuing the sync 77 | 78 | The next time you want to get updated content, you can use the token you previously stored. This will give you only new, and updated content, as well as a list of what content has been deleted: 79 | 80 | ~~~javascript 81 | client.sync({nextSyncToken: window.localStorage.getItem('contentfulSyncToken')}) 82 | .then((response) => { 83 | console.log(response.entries) 84 | console.log(response.assets) 85 | console.log(response.deletedEntries) 86 | console.log(response.deletedAssets) 87 | // store the new token 88 | window.localStorage.setItem('contentfulSyncToken', response.nextSyncToken) 89 | }) 90 | ~~~ 91 | 92 | Every time you perform a sync you get a new token, which represents that point in time for your space, so don't forget to store it again. 93 | 94 | You can then loop through the content you have previously stored and removed any content that is now marked as deleted, but that is left as an exercise to the reader. 95 | 96 | ## Conclusion 97 | 98 | Using the Sync API, you can keep your users easily up to date with your latest content. 99 | 100 | You can find the JavaScript SDK on [Github](https://github.com/contentful/contentful.js). Don't forget to open an issue if you run into any trouble. 101 | -------------------------------------------------------------------------------- /docs/net/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsNet 3 | name: .NET 4 | title: Using Contentful with .NET 5 | metainformation: 'Our .NET SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - .Net 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | 16 | ## SDKs 17 | 18 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 19 | 20 | ### Content Delivery API SDK 21 | 22 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
23 | [View on GitHub](https://github.com/contentful/contentful.net) 24 | 25 | ## Tutorials 26 | 27 | ### API demo 28 | 29 | [This guide](/developers/api-demo/dotnet/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 30 | 31 | ### Getting started with the Content Delivery API SDK and .Net 32 | 33 | [This tutorial](/developers/docs/net/tutorials/using-net-cda-sdk/) will walk you through the first steps using the Content Delivery API with a .Net application. 34 | 35 | ### Getting started with the Content Management API and .Net 36 | 37 | [This tutorial](/developers/docs/net/tutorials/management-api/) will guide you through most of the methods available in the Content Management API with a .Net application. 38 | 39 | [This tutorial](/developers/docs/net/tutorials/webhook-roles-snapshots/) will go in depth into managing webhooks, roles and space memberships and versioning entries with snapshots. 40 | 41 | ### Gettings started with Contentful and ASP.NET core 42 | 43 | [This tutorial](/developers/docs/net/tutorials/aspnet-core/) will walk you through the first steps using the .Net SDK with an ASP.NET core application. 44 | -------------------------------------------------------------------------------- /docs/php/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsPhp 3 | name: PHP 4 | title: Using Contentful with PHP 5 | metainformation: 'Our PHP SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - PHP 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | - [Tools](#tools-and-integrations) 16 | - [Example apps](#example-apps) 17 | 18 | ## SDKs 19 | 20 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 21 | 22 | ### Content Delivery API SDK 23 | 24 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
25 | [View on GitHub](https://github.com/contentful/contentful.php)
26 | [API reference](https://contentful.github.io/contentful.php/api/) 27 | 28 | ## Tutorials 29 | 30 | ### API demo 31 | 32 | [This guide](/developers/api-demo/php/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 33 | 34 | ### Getting started with the Content Delivery API SDK and PHP 35 | 36 | [This tutorial](/developers/docs/php/tutorials/getting-started-with-contentful-and-php/) will walk you through the first steps using the Content Delivery API with a PHP application. 37 | 38 | ### Using the Sync API with PHP 39 | 40 | The Sync API allows you to keep a local copy of all the content in a space up-to-date via delta updates. [This tutorial](/developers/docs/php/tutorials/using-the-sync-api-with-php/) shows you how to use the Sync API with the Contentful PHP SDK. 41 | 42 | ### Getting started with Contentful and Symfony 43 | 44 | [This tutorial](/developers/docs/php/tutorials/getting-started-with-contentful-and-symfony/) shows you how to include and setup the `ContentfulBundle` in your [Symfony](https://symfony.com/) application. 45 | 46 | ### Getting started with Contentful and Laravel 47 | 48 | [This tutorial](/developers/docs/php/tutorials/getting-started-with-contentful-and-laravel/) shows you how to setup integration with Contentful and [Laravel](https://laravel.com/). 49 | 50 | ## Tools and integrations 51 | 52 | ### Symfony bundle 53 | 54 | This bundle helps you integrate Symfony with the Content Delivery API
55 | [View on GitHub](https://github.com/contentful/ContentfulBundle) 56 | 57 | ### Laravel integration 58 | 59 | This bundle helps you integrate Laravel with the Content Delivery API
60 | [View on GitHub](https://github.com/contentful/contentful-laravel) 61 | 62 | ## Example apps 63 | 64 | These example apps are the best way to start building with Contentful. They show you how to start a project based on example spaces available in the Contentful web app. 65 | 66 | ### Symfony 67 | 68 | A generic product catalogue / e-commerce app connected to an example space using Symfony.
69 | [View on GitHub](https://github.com/contentful/product-catalogue-app-symfony) 70 | 71 | ### Laravel 72 | 73 | A simple blog using Contentful and Laravel.
74 | [View on GitHub](https://github.com/contentful/blog-app-laravel) 75 | -------------------------------------------------------------------------------- /docs/php/tutorials/getting-started-with-contentful-and-laravel.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsGettingStartedLaravel 3 | name: Getting Started with Contentful and Laravel 4 | title: Getting Started with Contentful and Laravel 5 | metainformation: 'This tutorial will walk you through your first steps in using Contentful with a PHP application.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - PHP 10 | nextsteps: null 11 | --- 12 | 13 | This tutorial will show you how to setup the Content Delivery API in your Laravel application and how to access your content 14 | inside the framework. 15 | 16 | {: .note} 17 | The ContentfulBundle and the PHP SDK are currently in beta and their APIs may change before a stable release. 18 | 19 | ## Requirements 20 | 21 | The Contentful Laravel integrations requires at least PHP 5.5.9 and Laravel 5. PHP 7 is supported. 22 | 23 | ## Installation 24 | 25 | The easiest way to install the Laravel integration is is to use [Composer][1]. If you've downloaded 26 | `composer.phar`, the integration can be installed by executing: 27 | 28 | ~~~ bash 29 | php composer.phar require contentful/contentful:@beta 30 | php composer.phar require contentful/laravel:@beta 31 | ~~~ 32 | 33 | {: .note} 34 | Currently the SDK and the integration both need to be added to your composer.json because both only have had beta quality releases. 35 | 36 | ### Enable the Service Provider 37 | 38 | Next you need to enable the Service Provider by adding it to `config/app.php`: 39 | 40 | ~~~ php 41 | [ 44 | // ... 45 | new Contentful\ContentfulBundle\ContentfulBundle(), 46 | // ... 47 | ] 48 | ]; 49 | ~~~ 50 | 51 | ### Configuration 52 | 53 | Before the Contentful SDK can be configured, the necessary config files have to be published. To do so execute the following command: 54 | 55 | ~~~ bash 56 | php artisan vendor:publish 57 | ~~~ 58 | 59 | This will add a file called `contentful.php` to your `/config` folder. 60 | 61 | Now open that file and fill in your space ID and API key. 62 | 63 | ~~~ php 64 | 'cfexampleapi', 67 | 'delivery.token' => 'b4c0n73n7fu1' 68 | ]; 69 | ~~~ 70 | 71 | To use the Preview API instead of the Content Delivery API, simply add `'delivery.preview' => true`: 72 | 73 | ~~~ php 74 | 'cfexampleapi', 77 | 'delivery.token' => 'e5e8d4c5c122cf28fc1af3ff77d28bef78a3952957f15067bbc29f2f0dde0b50', 78 | 'delivery.preview' => true 79 | ]; 80 | ~~~ 81 | 82 | ## Using Contentful 83 | 84 | You now have a service for the class `Contentful\Delivery\Client` available. A small controller displaying an entry 85 | based on an ID in the URL could look like this: 86 | 87 | ~~~ php 88 | client = $client; 103 | } 104 | 105 | public function entryAction($id) 106 | { 107 | $entry = $this->client->getEntry($id); 108 | 109 | if (!$entry) { 110 | abort(404); 111 | } 112 | 113 | return view('entry', [ 114 | 'entry' => $entry 115 | ]); 116 | } 117 | } 118 | ~~~ 119 | 120 | To discover how to use the Contentful client, check out the 121 | [getting started with Contentful and PHP](/developers/docs/php/tutorials/getting-started-with-contentful-and-php/) tutorial. 122 | 123 | ## Conclusion 124 | 125 | Now you should be familiar with the basics of how to use Contentful in a Laravel application. You can find the integration on 126 | [GitHub](https://github.com/contentful/contentful-laravel/) and [Packagist](https://packagist.org/packages/contentful/laravel). 127 | To get a deeper understanding, read some of our other [PHP tutorials](/developers/docs/php/#tutorials). If you find a bug, 128 | or have an idea how to further integrate with Laravel, please open an [issue on GitHub](https://github.com/contentful/contentful-laravel/issues). 129 | 130 | [1]: https://getcomposer.org 131 | -------------------------------------------------------------------------------- /docs/php/tutorials/using-the-sync-api-with-php.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsSyncApiWithPhp 3 | name: Using the Sync API with PHP 4 | title: Using the Sync API with PHP 5 | metainformation: 'This tutorial will walk you how to use the Sync API with the Contentful PHP SDK to keep a local copy of content up-to-date via delta updates.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - PHP 10 | nextsteps: null 11 | --- 12 | 13 | The [sync](/developers/docs/concepts/sync/) API allows you to keep a local copy of all content of a space up-to-date via 14 | delta updates. This tutorial will walk you how to use the Sync API with the Contentful PHP SDK. 15 | 16 | {: .note} 17 | The Contentful PHP SDK is currently in beta and the API may change before a stable release. 18 | 19 | ## Getting started 20 | 21 | After you've [installed the SDK](/developers/docs/php/tutorials/getting-started-with-contentful-and-php/#installation) 22 | you need to set up the client and get an instance of the synchronization manager. For this tutorial we'll be using an example space. 23 | 24 | ~~~ php 25 | getSynchronizationManager(); 28 | ~~~ 29 | 30 | Now we're able to start the initial synchronization. 31 | 32 | ~~~ php 33 | startSync(); 35 | $items = $result->getItems(); 36 | ~~~ 37 | 38 | As this is the initial sync `$items` will contain the entries and assets of your space. Storing these objects to the 39 | filesystem or a database will be left to you. To make it somewhat easier, all objects can be serialized to JSON and 40 | later revived: 41 | 42 | ~~~ php 43 | reviveJson($json); 46 | ~~~ 47 | 48 | If you have a space that's bigger than the example space, the sync might involve 49 | more records that can't be handled with one API call. To get absolutely everything you have to check `$result->isDone()`: 50 | 51 | ~~~ php 52 | startSync(); 54 | 55 | while (!$result->isDone()) { 56 | $result = $syncManager->continueSync($result); 57 | } 58 | ~~~ 59 | 60 | ### Continuing the sync 61 | 62 | To be able to get new changes later, you need to save the last token after the initial synchronization is complete. Using 63 | this token you can then resume the synchronization at the last state you've saved. 64 | 65 | ~~~ php 66 | getToken(); 69 | 70 | // Whenever you want to sync again 71 | 72 | $result = $syncManager->continueSync($token); 73 | ~~~ 74 | 75 | When continuing the sync you might encounter instances of the classes `DeletedEntry` and `DeletedEntry`. These give you 76 | access to some metadata, most importantly the ID, to delete the resources from your local storage. 77 | 78 | ## Conclusion 79 | 80 | With this information you should be able to implement a solution syncing your content to local storage. If you run into 81 | any trouble please open an issue. 82 | 83 | You can find the Contentful PHP SDK on [GitHub][1]. 84 | 85 | [1]: https://github.com/contentful/contentful.php 86 | -------------------------------------------------------------------------------- /docs/python/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsPython 3 | name: Python 4 | title: Using Contentful with Python 5 | metainformation: 'Our Python SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Python 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | 16 | ## SDKs 17 | 18 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 19 | 20 | ### CDA - Content Delivery API 21 | 22 | Contentful's Content Delivery API (CDA) is a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to an user's location by using our global CDN.
23 | [View on GitHub](https://github.com/contentful/contentful.py) 24 | [API reference](https://contentful.github.io/contentful.py) 25 | 26 | ## Tutorials 27 | 28 | ### Create and deploy a Django application using Contentful 29 | 30 | [This guide](/developers/docs/python/tutorials/full-stack-getting-started/) explains how to use Contentful with a Django application. 31 | 32 | ### Getting started with the Content Delivery API SDK and Python 33 | 34 | [This tutorial](/developers/docs/python/tutorials/getting-started-with-contentful-and-python/) will walk you through the first steps using the Content Delivery API with a Python application. 35 | 36 | ### API demo 37 | 38 | This guide shows how to make a call to the Contentful API, explains what the response looks like, and suggests some relevant next steps.
39 | View in [cURL](/developers/api-demo/curl/) 40 | -------------------------------------------------------------------------------- /docs/python/tutorials/full-stack-getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPythonFullStack 3 | name: Getting Started with Contentful 4 | title: Getting Started with Contentful 5 | metainformation: 'This guide will walk you through your first steps using Contentful within a Rails application.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Python 10 | - Django 11 | nextsteps: 12 | - text: The Contentful Management API reference 13 | link: /developers/docs/references/content-management-api/ 14 | - text: The Contentful Delivery API reference 15 | link: /developers/docs/references/content-delivery-api/ 16 | --- 17 | 18 | This guide will walk you through your first steps using Contentful within a Django application. It will provide a step-by-step guide on how to get your first entries and start using the content you create on Contentful. 19 | 20 | ## Requirements 21 | 22 | - A [Heroku][7] account 23 | - Python 2.7+ or 3.3+ 24 | - [Git][5] installed 25 | - Basic Command Line Interface, Python and Django knowledge 26 | 27 | {: .note} 28 | **Note:** During this guide we'll assume that you're running inside a `virtualenv`. If not, append `sudo` when installing dependencies if you are using system-provided Python. 29 | 30 | Optionally: 31 | 32 | - Ruby 1.9+ for running `contentful-bootstrap` to create your own space with the provided template 33 | 34 | ## Start from a demo application 35 | 36 | First we'll start with a [demo project][2], which is a simple Django application using a basic Blog template, so that you can see it running for yourself. 37 | 38 | Run the following commands to get started. 39 | 40 | - Clone the example repository: 41 | 42 | ~~~bash 43 | git clone https://github.com/contentful/contentful_django_tutorial.git 44 | ~~~ 45 | 46 | - Navigate into the repository's directory: 47 | 48 | ~~~bash 49 | cd contentful_django_tutorial 50 | ~~~ 51 | 52 | - Install dependencies: 53 | 54 | ~~~bash 55 | pip install -r requirements.txt 56 | ~~~ 57 | 58 | - *Optional* Create your space using Contentful Bootstrap: 59 | 60 | {: .note} 61 | **Note**: If skipped, the example will use a read-only space that's already provided for you. 62 | 63 | ~~~bash 64 | bundle install 65 | bundle exec contentful_bootstrap create_space django_demo -j bootstrap/template.json 66 | ~~~ 67 | 68 | After following the steps, the tool will provide you with a Space ID and Access Token. Then run the following commands replacing the values where they correspond: 69 | 70 | ~~~bash 71 | export CTF_SPACE_ID=YOUR_SPACE_ID 72 | export CTF_DELIVERY_KEY=YOUR_ACCESS_TOKEN 73 | ~~~ 74 | 75 | It should look something like this: 76 | 77 | ![Bootstrap Tool Output](https://i.imgur.com/RkmNaes.png) 78 | 79 | This will allow the application to use your own space, allowing you to edit content and allowing you to see your application changing. You can edit content freely in our [Web App][3]. 80 | 81 | - Run the application: 82 | 83 | ~~~bash 84 | python manage.py runserver 85 | ~~~ 86 | 87 | Everything is now set up. You can view your space by opening _http://localhost:8000_ in your browser. 88 | 89 | It should look something like this: 90 | 91 | ![Django Demo Application](https://i.imgur.com/Zmum6k4.png) 92 | 93 | ### Deploy the demo to Heroku 94 | 95 | To view the demo application live in your own production environment, follow these steps: 96 | 97 | - Install the [Heroku toolbelt](https://devcenter.heroku.com/articles/heroku-cli#download-and-install) if you don't already have it. 98 | - Login to Heroku if you're not already: 99 | 100 | ~~~bash 101 | heroku login 102 | ~~~ 103 | 104 | - Create a new instance: 105 | 106 | ~~~bash 107 | heroku create 108 | ~~~ 109 | 110 | - Set Python Buildpack: 111 | 112 | ~~~bash 113 | heroku buildpacks:set heroku/python 114 | ~~~ 115 | 116 | - Deploy to Heroku: 117 | 118 | ~~~bash 119 | git push heroku master 120 | ~~~ 121 | 122 | - *Optional* Add your personalized credentials to your Heroku Instance: 123 | 124 | 1. Open [Heroku](https://dashboard.heroku.com) 125 | 2. Go to your application 126 | 3. Go to Settings 127 | 4. Press _Reveal Config Vars_ 128 | 5. Add `CTF_SPACE_ID` and `CTF_DELIVERY_KEY` with their respective values 129 | 6. Go to Resources and restart your application 130 | 131 | - Open the application in your browser: 132 | 133 | ~~~bash 134 | heroku open 135 | ~~~ 136 | 137 | ## Next Steps 138 | 139 | After this guide, you should be able to start using Contentful with your Django applications, but every project has different needs and we want to provide you with the best solutions we can. 140 | 141 | You can read about the Contentful CDA library in more detail on our [contentful.py GitHub][1] or our [Getting Started with CDA SDK tutorial][4], we also suggest taking a look at our [Contentful Django Example Application][2]. 142 | 143 | If you want to set up new spaces via the command line we also provide [Contentful Bootstrap][6]. 144 | 145 | [1]: https://github.com/contentful/contentful.py 146 | [2]: https://github.com/contentful/contentful_django_tutorial 147 | [3]: https://app.contentful.com 148 | [4]: /developers/docs/python/tutorials/getting-started-with-contentful-and-python/ 149 | [5]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git 150 | [6]: https://github.com/contentful/contentful-bootstrap.rb 151 | [7]: https://www.heroku.com 152 | -------------------------------------------------------------------------------- /docs/references/content-delivery-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: api_reference 3 | page: :docsContentfulCda 4 | --- 5 | -------------------------------------------------------------------------------- /docs/references/content-management-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: api_reference 3 | page: :docsContentfulCma 4 | --- 5 | -------------------------------------------------------------------------------- /docs/references/content-preview-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: api_reference 3 | page: :docsContentPreviewApi 4 | --- 5 | -------------------------------------------------------------------------------- /docs/references/errors.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsErrors 3 | name: Errors 4 | title: Errors 5 | metainformation: 'When something goes wrong with an API request, our server generates an error. The error message contains an appropriate HTTP status code in the header and a JSON response in the body.' 6 | slug: null 7 | tags: 8 | - Reference 9 | - Errors 10 | nextsteps: 11 | - text: Details of our HTTP transport 12 | link: /developers/docs/references/http-details/ 13 | --- 14 | 15 | When something goes wrong with an API request, our server generates an error. The error message contains an appropriate HTTP status code in the header and a JSON response in the body. 16 | 17 | Errors share the same common attributes as other API resources. They have a `sys` property, where `sys.type` is always `"Error"` and a `sys.id` that identifies the exact error code (see table below) that occurred. They always have a `message` property which will be a short description of what went wrong. 18 | 19 | Errors resulting from bad input (such as `ValidationFailed` errors) contain a `details` property. This property is structured data that indicates more precisely what was wrong with the input. 20 | 21 | ## Error types 22 | 23 | {:.table} 24 | HTTP status code |Error code |Description 25 | -------------------|-----------------|-------------------------------------- 26 | `400 Bad Request` |`BadRequestError`|The request was malformed or missing a required parameter. 27 | `400 Invalid query`|`InvalidQueryError`|The request contained invalid or unknown query parameters. 28 | `401 Unauthorized` |`AccessTokenInvalidError`|The authorization token was invalid. 29 | `403 Access Denied`|`AccessDeniedError`|The user tried to access a resource they do not have access to. This could include a missing role. 30 | `404 Not Found`|`NotFoundError`|The requested resource or endpoint could not be found. 31 | `409 Version Mismatch`|`VersionMismatchError`|This error occurs when you're trying to update an existing asset, entry or content type, and you didn't specify the current version of the object or specify an outdated version. 32 | `422 Validation Error`|`ValidationFailedError`|The request payload was valid JSON, but something was wrong with the data. The error details should provide more specific information about the error. 33 | `422 Unknown Field`|`ValidationFailedError`|The triggered query references an invalid field. 34 | `422 Invalid Entry`| `InvalidEntryError`|The entered value is invalid. 35 | `429 Rate Limit Exceeded Error`|`RateLimitExceededError`|The user sent too many requests per second. 36 | `500 Server Error`|`ServerError`|Something went wrong on the Contentful servers. 37 | `502 Hibernated`|`AccessDeniedError`|The space has not been used for a long time and was hibernated. It will become active again if the user begins using it. 38 | -------------------------------------------------------------------------------- /docs/references/http-details.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsHttpDetails 3 | name: HTTP details 4 | title: HTTP details 5 | metainformation: 'The Content Delivery API and Preview API are fully available via SSL. You should request JSON data and assets through a secure transport.' 6 | slug: null 7 | tags: 8 | - Reference 9 | - Network 10 | nextsteps: 11 | - text: Details of our error messages 12 | link: /developers/docs/references/errors/ 13 | --- 14 | 15 | ## Security 16 | 17 | The Content Delivery API and Preview API are fully available via SSL. You should request JSON data and assets through a secure transport. 18 | 19 | Our client libraries enable SSL by default. Unless there is a reason to disable SSL you should leave it enabled to ensure maximum privacy for clients. 20 | 21 | The Content Management API is only available via SSL, and you must make all requests using the _https_ protocol. 22 | 23 | Using SSL ensures that the content and access tokens of a space remain secure and that potential eavesdroppers cannot intercept your data. 24 | 25 | ## Cross-origin resource sharing 26 | 27 | [CORS (Cross-origin resource sharing)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) allows JavaScript web apps to make HTTP requests to other domains. This is important for third party web apps using Contentful, as without CORS, a JavaScript app hosted on _example.com_ couldn't access our APIs because they're hosted on _contentful.com_ which is a different domain. 28 | 29 | CORS is [supported by all modern browsers](http://caniuse.com/cors). Read more about using CORS in this [tutorial](https://www.html5rocks.com/en/tutorials/cors/). 30 | 31 | To allow JavaScript applications running inside browsers to interact with our APIs, we set the following HTTP response headers: 32 | 33 | - `Access-Control-Allow-Origin`: `*`, or all. 34 | - `Access-Control-Allow-Headers`: A long list of common headers, if you want to know more, [read the reference below](#allow-headers). 35 | - `Access-Control-Allow-Methods`: HTTP verbs. Typically the request type, plus `OPTIONS` and `HEAD`. 36 | - `Access-Control-Max-Age`: This varies depending on endpoint, but is a high value to avoid preflight requests. 37 | 38 | {: .note} 39 | **Note:** Allowing all origins is safe because all requests must include an access token in the query string or as header. The token will never be sent implicitly by a cookie. You can only issue destructive requests against the HTTPS endpoint. 40 | 41 | ## ETag/If-None-Match 42 | 43 | Our APIs support conditional `GET` requests via [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) and `If-None-Match` headers. 44 | 45 | Every API response (both single resources and searches) includes an `ETag` header. The `ETag` header changes depending on the content of the response. If a resource is updated or a search result changes, the ETag also changes. 46 | 47 | To avoid unnecessary transfers you can set the `If-None-Match` header of an API request to the `ETag` previously received for the same API request. 48 | 49 | If the content hasn't changed in the meantime the API will respond with a 304 Not Modified response. This makes a difference for large responses and especially binary files. 50 | 51 | ## GZip compression 52 | 53 | All API endpoints support GZip compression to save bandwidth. Please take into account that enabling compression will put more load on your clients' processors. 54 | 55 | ## JSON format details 56 | 57 | Contentful represents resources as [JSON](http://json.org), encoded in UTF-8. Contentful represents dates and times as [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)-encoded string, with system-generated dates represented as UTC. 58 | 59 | ### Allow headers reference 60 | 61 | Contentful sets the following headers: 62 | 63 | `Accept`, `Accept-Language`, `Authorization`, `Cache-Control`, `Content-Length`, `Content-Range`, `Content-Type`, `DNT`, `Destination`, `Expires`, `If-Match`, `If-Modified-Since`, `If-None-Match`, `Keep-Alive`, `Last-Modified`, `Origin`, `Pragma`, `Range`, `User-Agent`, `X-Http-Method-Override`, `X-Mx-ReqToken`, `X-Requested-With`, `X-Contentful-Version`, `X-Contentful-Content-Type`, `X-Contentful-Organization`, `X-Contentful-Skip-Transformation`, `X-Contentful-User-Agent` 64 | -------------------------------------------------------------------------------- /docs/references/images-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: api_reference 3 | page: :docsContentfulImagesApi 4 | --- 5 | 6 | -------------------------------------------------------------------------------- /docs/ruby/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsRuby 3 | name: Ruby 4 | title: Using Contentful with Ruby 5 | metainformation: 'Our Ruby SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Ruby 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | - [Tools](#tools-and-integrations) 16 | - [Example apps](#example-apps) 17 | 18 | ## SDKs 19 | 20 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 21 | 22 | ### Content Delivery API SDK 23 | 24 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
25 | [View on GitHub](https://github.com/contentful/contentful.rb)
26 | [API reference](http://www.rubydoc.info/gems/contentful/) 27 | 28 | ### Content Management API SDK 29 | 30 | This SDK interacts with the Content Management API, and allows you to create, edit, manage, and publish content. The API also offers tools for managing editorial teams and cooperation.
31 | [View on GitHub](https://github.com/contentful/contentful-management.rb)
32 | [API reference](http://www.rubydoc.info/gems/contentful-management/) 33 | 34 | ## Tutorials 35 | 36 | ### Create and deploy a Rails application using Contentful 37 | 38 | [This guide](/developers/docs/ruby/tutorials/full-stack-getting-started/) explains how to use Contentful with a Ruby on Rails application. 39 | 40 | ### API demo 41 | 42 | [This guide](/developers/api-demo/ruby/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 43 | 44 | ### Getting started with the Content Delivery API SDK and Ruby 45 | 46 | [This tutorial](/developers/docs/ruby/tutorials/getting-started-with-contentful-and-ruby/) will walk you through the first steps using the Content Delivery API with a Ruby application. 47 | 48 | ### Create your own Rails application using Contentful 49 | 50 | [This guide](/developers/docs/ruby/tutorials/create-your-own-rails-app/) shows you how to create a Ruby on Rails application from scratch and integrate it with Contentful. 51 | 52 | ### Getting started with the Content Management API SDK and Ruby 53 | 54 | [This tutorial](/developers/docs/ruby/tutorials/getting-started-with-contentful-cma-and-ruby/) will walk you through the first steps using the Contentful Management API with a Ruby application. 55 | 56 | ## Tools and integrations 57 | 58 | ### Contentful bootstrap command line tool 59 | 60 | [This tool](https://github.com/contentful/contentful-bootstrap.rb) will help you create, populate and manage your Contentful spaces from the command line. [Read this tutorial](/developers/docs/ruby/tutorials/using-contentful-bootstrap-for-keeping-up-with-your-spaces/) to learn more about how to use the tool. 61 | 62 | ### Contentful webhook listener 63 | 64 | A simple HTTP webserver for listening to API webhooks that you can override to suit your own behaviors.
65 | [View on GitHub](https://github.com/contentful/contentful-webhook-listener.rb) 66 | 67 | ### Rails integration 68 | 69 | A collection of useful gems that make it easier to integrate Contentful into a Rails app. [Read this blog post](/blog/2016/07/21/contentful-on-rails/) to find out how to use them in your applications.
70 | [View Contentful Rails on GitHub](https://github.com/contentful/contentful_rails)
71 | [View Contentful Model on GitHub](https://github.com/contentful/contentful_model) 72 | 73 | ## Example apps 74 | 75 | ### Rails product demo 76 | 77 | A Rails application that connects to a Contentful product catalogue example space.
78 | [View on GitHub](https://github.com/contentful/contentful_rails_tutorial) 79 | 80 | ### Sinatra product demo 81 | 82 | A Sinatra application that connects to a Contentful product catalogue example space.
83 | [View on GitHub](https://github.com/contentful/contentful_sinatra_tutorial) 84 | -------------------------------------------------------------------------------- /docs/ruby/tutorials/automated-rebuild-and-deploy-with-circleci-and-webhooks.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsRubyAutomatedRebuild 3 | name: Automated rebuild and deploy with CircleCI and Webhooks 4 | title: Automated rebuild and deploy with CircleCI and Webhooks 5 | metainformation: 'This guide will show you how you can automate Contentful deployments using Webhooks and CircleCI.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Ruby 10 | - Workflow 11 | nextsteps: null 12 | --- 13 | 14 | If you're running our [Jekyll](https://github.com/contentful/jekyll-contentful-data-import) or [Middleman](https://github.com/contentful/contentful_middleman) integrations, 15 | you might be wondering how to automate your site building and publishing process. 16 | 17 | Here we'll discuss how you can automate this process using [Contentful Webhooks](/developers/docs/concepts/webhooks/) 18 | and CircleCI API. 19 | 20 | > Everything we'll discuss here is for the case of using a public [GitHub](https://github.com) repository, 21 | > using [CircleCI.com](https://circleci.com) and deploying on [GitHub Pages](https://pages.github.com/). 22 | > This setup can be replicated on a private repository with CircleCI.com integration 23 | > enabled. Just make sure to change the URLs in the examples appropriately. 24 | 25 | ## Requirements 26 | 27 | * A Contentful Space and API Key 28 | * Your Jekyll or Middleman application with Contentful hosted on GitHub 29 | * CircleCI integration enabled on your repository 30 | * GitHub Pages repository for deploying your site 31 | 32 | We'll assume that you know how to set up your Jekyll or Middleman projects. 33 | If not, you can check the basic example applications here: 34 | 35 | * [Middleman Examples](https://github.com/contentful/contentful_middleman_examples) 36 | * [Jekyll Examples](https://github.com/contentful/contentful_jekyll_examples) 37 | 38 | ## Setup your Contentful webhooks to trigger Circle builds 39 | 40 | * Generate your CircleCI Token [here](https://circleci.com/docs/api/#getting-started). 41 | * On the Contentful webhook admin page, create a webhook with (replacing the upper-cased values): 42 | 43 | ~~~ 44 | Name: CircleCI 45 | URL: https://circleci.com/api/v1/project/YOUR_COMPANY/YOUR_PROJECT/tree/YOUR_BRANCH?circle-token=YOUR_CIRCLECI_TOKEN 46 | On: Entry -> publish, unpublish 47 | ~~~ 48 | 49 | ## Create automated build script 50 | 51 | Here the setups differ a bit, but the structure is pretty similar. 52 | 53 | Create a file called `automated_build.sh` and include the following: 54 | 55 | * Middleman: 56 | 57 | ~~~bash 58 | # Copy static site 59 | CWD=`pwd` 60 | 61 | # Clone Pages repository 62 | cd /tmp 63 | git clone YOUR_PAGES_REPO build 64 | 65 | # cd build && git checkout -b YOUR_BRANCH origin/YOUR_BRANCH # If not using master 66 | 67 | # Trigger Middleman rebuild 68 | cd $CWD 69 | bundle exec middleman contentful --rebuild 70 | 71 | # Push newly built repository 72 | cp -r $CWD/build/* /tmp/build 73 | 74 | cd /tmp/build 75 | 76 | git config --global user.email "YOUR_EMAIL@example.com" 77 | git config --global user.name "YOUR NAME" 78 | 79 | git add . 80 | git commit -m "Automated Rebuild" 81 | git push -f origin YOUR_PAGES_BRANCH 82 | ~~~ 83 | 84 | * Jekyll: 85 | 86 | ~~~bash 87 | # Copy static site 88 | CWD=`pwd` 89 | 90 | # Clone Pages repository 91 | cd /tmp 92 | git clone YOUR_PAGES_REPO build 93 | # cd build && git checkout -b YOUR_BRANCH origin/YOUR_BRANCH # If not using master 94 | 95 | # Trigger Jekyll rebuild 96 | cd $CWD 97 | bundle exec jekyll contentful 98 | bundle exec jekyll build 99 | 100 | # Push newly built repository 101 | cp -r $CWD/_build/* /tmp/build # or $CWD/_site 102 | 103 | cd /tmp/build 104 | 105 | git config --global user.email "YOUR_EMAIL@example.com" 106 | git config --global user.name "YOUR NAME" 107 | 108 | git add . 109 | git commit -m "Automated Rebuild" 110 | git push -f origin YOUR_PAGES_BRANCH 111 | ~~~ 112 | 113 | > Make sure your CircleCI machine has access to your Pages repository. 114 | > This requires adding SSH Keys to the CircleCI machine and configuring them on GitHub. 115 | 116 | ## Setup Circle build steps 117 | 118 | Now we have everything we need to create our automated builds, only thing missing 119 | is to add a build step in Circle to run our build. 120 | 121 | In `circle.yml`, add the following: 122 | 123 | ~~~yml 124 | machine: 125 | ruby: 126 | version: 2.3.1 127 | dependencies: 128 | pre: 129 | - gem install bundler 130 | checkout: 131 | post: 132 | - bundle install 133 | - bash automated_build.sh 134 | ~~~ 135 | 136 | ## We're done! Automation! 137 | 138 | You can now start testing your automatically rebuilt site. With this setup, any change 139 | pushed on your repository or any publish/unpublish action on Contentful will trigger 140 | an automated rebuild of your site. 141 | -------------------------------------------------------------------------------- /docs/tools/applications.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsToolsApplications 3 | name: Applications 4 | title: Applications 5 | metainformation: 'These applications help you use Contentful.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - Extending 10 | nextsteps: null 11 | --- 12 | 13 | ## macOS media uploader 14 | 15 | Upload images to Contentful with this macOS tool. 16 | 17 | ![macOS media uploader](https://images.contentful.com/tz3n7fnw4ujc/4kQwOdAZksQi8s6yuM8aq2/d3c99346b5ffc5b586f324ead59dd3e9/macos-media-uploader.png) 18 | 19 | [View on GitHub](https://github.com/contentful/image-uploader-app) 20 | 21 | ## Third party tools 22 | 23 | Apart from official tools and libraries, there are others developed by our community, which you can find at [awesome-contentful](https://github.com/contentful-labs/awesome-contentful). These include languages and platforms such as Python and .NET. 24 | -------------------------------------------------------------------------------- /docs/tools/extensions.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsToolsExtensions 3 | name: Extensions 4 | title: Extensions 5 | metainformation: 'These extensions add extra functionality to Contentful, you can find detailed instructions in each individual GitHub repository.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - Extending 10 | nextsteps: null 11 | --- 12 | 13 | These extensions add extra functionality to Contentful, you can find detailed instructions in each individual GitHub repository. 14 | 15 | ## Contentful Scheduler 16 | 17 | This Ruby gem provides automated scheduled entry publishing using our [webhooks API](/developers/docs/references/content-management-api/#/reference/webhooks). 18 | 19 | [View on GitHub](https://github.com/contentful/contentful-scheduler.rb) 20 | 21 | ## Contentful Moderator 22 | 23 | This Ruby gem provides moderated authoring workflows for your entries. 24 | 25 | [View on GitHub](https://github.com/contentful/contentful-moderator.rb) 26 | 27 | ## Contentful Social 28 | 29 | This Ruby gem provides the ability to post directly to social networks when publishing your entries. 30 | 31 | [View on GitHub](https://github.com/contentful/contentful-social.rb) 32 | -------------------------------------------------------------------------------- /docs/tools/spacemanagement.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsToolsSpaceManagement 3 | name: Space management 4 | title: Space management tools 5 | metainformation: 'These tools will help you import and manage entries in your spaces.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - Extending 10 | nextsteps: null 11 | --- 12 | 13 | These tools will help you import and manage entries in your spaces. 14 | 15 | ## Import and Export Tools 16 | 17 | The export tool allows you to export all content, including content types, assets and webhooks from a space. The import tool allows you import all the content into a new space. _These tools replace the space sync tool if you previously used that_. 18 | 19 | Import Tool - [View on GitHub](https://github.com/contentful/contentful-import) 20 | Export Tool - [View on GitHub](https://github.com/contentful/contentful-export) 21 | 22 | For further information on recommended steps for using these tools, read [our guide to maintaining multiple environments with Contentful](/developers/docs/concepts/multiple-environments/). 23 | 24 | ## Data import / Bootstrap 25 | 26 | You can import data from other systems into Contentful using our [contentful-importer.rb](https://github.com/contentful/contentful-importer.rb) gem. 27 | 28 | The importer uses a flexible input format that you can write your own exporters for, we provide exporters for: 29 | 30 | - [Drupal](https://github.com/contentful/drupal-exporter.rb) 31 | - [SQL databases](https://github.com/contentful/database-exporter.rb) 32 | - [WordPress](https://github.com/contentful/wordpress-exporter.rb) 33 | 34 | [Read this tutorial](/developers/docs/tutorials/general/import-and-export/) to learn how to export content from the systems listed above and import it into your Contentful spaces. 35 | 36 | ## Contentful link cleaner 37 | 38 | If you delete an entry linked to another entry, then you will have loose references to non-existent entries. This tool cleans up these links. 39 | 40 | [View on GitHub](https://github.com/contentful/contentful-link-cleaner) 41 | 42 | ## Contentful bootstrap 43 | 44 | This Ruby gem gets you started using Contentful with one command, creating the spaces, entries and more with one command. [Read this tutorial](/developers/docs/ruby/tutorials/using-contentful-bootstrap-for-keeping-up-with-your-spaces/) for more details. 45 | 46 | [View on GitHub](https://github.com/contentful/contentful-bootstrap.rb) 47 | -------------------------------------------------------------------------------- /docs/tools/staticsitegenerators.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsToolsStaticSiteGenerators 3 | name: Static site generators 4 | title: Static site generators 5 | metainformation: 'We love static sites and have plugins to support three of our favorites.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - Extending 10 | nextsteps: null 11 | --- 12 | 13 | We love static sites and have plugins to support three of our favorites. 14 | 15 | ## Middleman 16 | 17 | [Middleman](https://middlemanapp.com/) is a Ruby based static site generator, and this plugin will help you manage your Contentful content. 18 | 19 | [View on GitHub](https://github.com/contentful/contentful_middleman) 20 | 21 | [View examples](https://github.com/contentful/contentful_middleman_examples) 22 | 23 | ## Jekyll 24 | 25 | [Jekyll](https://jekyllrb.com/) is a Ruby based static site generator, and this plugin pulls content from Contentful. 26 | 27 | [View on GitHub](https://github.com/contentful/jekyll-contentful-data-import) 28 | 29 | [View examples](https://github.com/contentful/contentful_jekyll_examples) 30 | 31 | ## Metalsmith 32 | 33 | [Metalsmith](http://www.metalsmith.io/) is a JavaScript based static site generator, and this plugin fetches and renders data from Contentful. 34 | 35 | [View on GitHub](https://github.com/contentful-labs/contentful-metalsmith) 36 | 37 | [View examples](https://github.com/contentful-labs/contentful-metalsmith-example) 38 | 39 | ## Tutorials 40 | 41 | ### Automated rebuild and deployment with CircleCI and Webhooks 42 | 43 | [This tutorial](/developers/docs/ruby/tutorials/automated-rebuild-and-deploy-with-circleci-and-webhooks/) shows you how to setup and automatically deploy static sites using Jekyll or Middleman with CircleCI. 44 | 45 | ## Other tools 46 | 47 | We have more tools available to extend the functionality of Contentful. We have tested these tools, but they are not officially supported by Contentful. 48 | 49 | ### Roots 50 | 51 | [Roots](https://roots.cx/) is a JavaScript based static site generator, and this plugin helps you manage content from Contentful. 52 | 53 | [View on GitHub](https://github.com/carrot/roots-contentful) 54 | 55 | [View examples](/blog/2015/04/28/webinar-contentful-roots-static-sites/) 56 | 57 | ### Simple static site generator 58 | 59 | A CLI tool to generate a site from templates and data in a Contentful space. 60 | 61 | [View on GitHub](https://github.com/Textalk/contentful-static) 62 | 63 | ### AWS Lambda 64 | 65 | An example project for building a static site using AWS Lambda. 66 | 67 | [View example](https://github.com/contentful-labs/contentful-aws-lambda-static) 68 | -------------------------------------------------------------------------------- /generate-docs.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | rm -rf docs 4 | 5 | echo "Processing Markdown" 6 | for filename in $(find raw_docs -type f -name '*.md'); do 7 | echo $filename 8 | original_string=$filename 9 | string_to_replace_with=docs 10 | result_string="${original_string/raw_docs/$string_to_replace_with}" 11 | echo $result_string 12 | 13 | mkdir -p "$(dirname "$result_string")" && touch "$result_string" 14 | ./node_modules/.bin/hercule $filename -o $result_string 15 | ./placeholder-replacements.sh $result_string 16 | done 17 | 18 | cp -v raw_docs/references/authentication.html.haml docs/references/authentication.html.haml 19 | cp -v raw_docs/android/tutorials/*.png docs/android/tutorials/ 20 | cp -v raw_docs/ios/tutorials/*.png docs/ios/tutorials/ 21 | cp -v raw_docs/javascript/tutorials/*.png docs/javascript/tutorials/ 22 | 23 | rm -rf docs/_partials 24 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "slash-developers", 3 | "private": true, 4 | "devDependencies": { 5 | "hercule": "^1.2.5" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /placeholder-replacements.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | result_string=$1 3 | 4 | # Space ID 5 | sed -i -e 's//71rop70dkqaj/g' $result_string 6 | 7 | # Access token 8 | if [[ $2 == "preview" ]]; then 9 | # Preview API 10 | sed -i -e 's//46cc338e0d4647e3b9f98c52615a2414d725b6ddffdbbb2f3bed26f73789dd53/g' $result_string 11 | else 12 | # Delivery API 13 | sed -i -e 's//297e67b247c1a77c1a23bb33bf4c32b81500519edd767a8384a4b8f8803fb971/g' $result_string 14 | fi 15 | 16 | # Specific entry ID 17 | sed -i -e 's//5KsDBWseXY6QegucYAoacS/g' $result_string 18 | 19 | # Specific entry ID two 20 | sed -i -e 's//3DVqIYj4dOwwcKu6sgqOgg/g' $result_string 21 | 22 | # Specific brand content type 23 | sed -i -e 's//sFzTZbSuM8coEwygeUYes/g' $result_string 24 | 25 | # SKU value 26 | sed -i -e 's//B00E82D7I8/g' $result_string 27 | 28 | # Specific product content type 29 | sed -i -e 's//2PqfXUJwE8qSYKuM0U6w8M/g' $result_string 30 | 31 | # Specific city content type 32 | sed -i -e 's//city/g' $result_string 33 | 34 | # SKU value 35 | sed -i -e 's//B00E82D7I8/g' $result_string 36 | 37 | # Specific asset 38 | sed -i -e 's//wtrHxeu3zEoEce2MokCSi/g' $result_string 39 | sed -i -e 's//e86a375b7ad18c25e4ff55de1eac42fe/g' $result_string 40 | sed -i -e 's//quwowooybuqbl6ntboz3.jpg/g' $result_string 41 | sed -i -e "s++//wtrHxeu3zEoEce2MokCSi/e86a375b7ad18c25e4ff55de1eac42fe/quwowooybuqbl6ntboz3.jpg+g" $result_string 42 | sed -i -e 's//Playsam Streamliner/g' $result_string 43 | sed -i -e 's//Playsam Streamliner/g' $result_string 44 | 45 | # Link field 46 | sed -i -e 's//brand/g' $result_string 47 | 48 | # Link field, multiple 49 | sed -i -e 's//tags/g' $result_string 50 | 51 | # Webhook 52 | sed -i -e 's//0KzM2HxYr5O1pZ4SaUzK8h/g' $result_string 53 | 54 | # Snapshot 55 | sed -i -e 's//4lFryO7nDNioplKMFBpyMB/g' $result_string 56 | 57 | # Space membership ID 58 | sed -i -e 's//0xWanD4AZI2AR35wW9q51n/g' $result_string 59 | 60 | # Role 61 | sed -i -e 's//0xvkNW6WdQ8JkWlWZ8BC4x/g' $result_string 62 | 63 | # Locale 64 | sed -i -e 's//en-US/g' $result_string 65 | sed -i -e 's//0xpIUSHPfJRzsAFFaub3hT/g' $result_string 66 | 67 | # Sync token 68 | sed -i -e 's//w7Ese3kdwpMbMhhgw7QAUsKiw6bCi09CwpFYwpwywqVYw6DDh8OawrTDpWvCgMOhw6jCuAhxWX_CocOPwowhcsOzeEJSbcOvwrfDlCjDr8O1YzLDvi9FOTXCmsOqT8OFcHPDuFDCqyMMTsKNw7rDmsOqKcOnw7FCwpIfNMOcFMOxFnHCoCzDpAjCucOdwpwfw4YTK8Kpw6zCtDrChVQlNsO2ZybDnw/g' $result_string 69 | -------------------------------------------------------------------------------- /raw_docs/_partials/content-type-filter-output.md: -------------------------------------------------------------------------------- 1 | ~~~json 2 | "Normann Copenhagen" 3 | "Lemnos" 4 | "Playsam" 5 | ~~~ 6 | -------------------------------------------------------------------------------- /raw_docs/_partials/content-type-filter.md: -------------------------------------------------------------------------------- 1 | The following request filters all entries by a specific content type, using that content type's ID. 2 | 3 | _You can use the content type pre-filled below for our example space or replace it with your own value_. 4 | -------------------------------------------------------------------------------- /raw_docs/_partials/credentials.md: -------------------------------------------------------------------------------- 1 | ## Initializing the client 2 | 3 | You need an API key and a space ID to initialize a client 4 | 5 | _You can use the API key and space ID pre-filled below from our example space or replace them with your own values_. 6 | -------------------------------------------------------------------------------- /raw_docs/_partials/field-filter-ne-output.md: -------------------------------------------------------------------------------- 1 | ~~~json 2 | "B00MG4ULK2" 3 | "B0081F2CCK" 4 | "B001R6JUZ2" 5 | ~~~ 6 | -------------------------------------------------------------------------------- /raw_docs/_partials/field-filter-output.md: -------------------------------------------------------------------------------- 1 | ~~~json 2 | "B00E82D7I8" 3 | ~~~ 4 | -------------------------------------------------------------------------------- /raw_docs/_partials/get-all-asset-output.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | //images.contentful.com/71rop70dkqaj/1MgbdJNTsMWKI0W68oYqkU/4c2d960aa37fe571d261ffaf63f53163/9ef190c59f0d375c0dea58b58a4bc1f0.jpeg 3 | //images.contentful.com/71rop70dkqaj/4zj1ZOfHgQ8oqgaSKm4Qo2/8c30486ae79d029aa9f0ed5e7c9ac100/playsam.jpg 4 | //images.contentful.com/71rop70dkqaj/3wtvPBbBjiMKqKKga8I2Cu/90b69e82b8b735383d09706bdd2d9dc5/zJYzDlGk.jpeg 5 | //images.contentful.com/71rop70dkqaj/wtrHxeu3zEoEce2MokCSi/e86a375b7ad18c25e4ff55de1eac42fe/quwowooybuqbl6ntboz3.jpg 6 | //images.contentful.com/71rop70dkqaj/6t4HKjytPi0mYgs240wkG/b7ba3984167c53d728e7533e54ab179d/toys_512pxGREY.png 7 | //images.contentful.com/71rop70dkqaj/10TkaLheGeQG6qQGqWYqUI/13c64b63807d1fd1c4b42089d2fafdd6/ryugj83mqwa1asojwtwb.jpg 8 | //images.contentful.com/71rop70dkqaj/Xc0ny7GWsMEMCeASWO2um/190cc760e991d27fba6e8914b87a736d/jqvtazcyfwseah9fmysz.jpg 9 | //images.contentful.com/71rop70dkqaj/2Y8LhXLnYAYqKCGEWG4EKI/44105a3206c591d5a64a3ea7575169e0/lemnos-logo.jpg 10 | //images.contentful.com/71rop70dkqaj/6m5AJ9vMPKc8OUoQeoCS4o/07b56832506b9494678d1acc08d01f51/1418244847_Streamline-18-256.png 11 | //images.contentful.com/71rop70dkqaj/6s3iG2OVmoUcosmA8ocqsG/b55b213eeca80de2ecad2b92aaa0065d/1418244847_Streamline-18-256__1_.png 12 | //images.contentful.com/71rop70dkqaj/KTRF62Q4gg60q6WCsWKw8/ae855aa3810a0f6f8fee25c0cabb4e8f/soso.clock.jpg 13 | ~~~ 14 | -------------------------------------------------------------------------------- /raw_docs/_partials/get-all-entry-linked-output.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | {"url":"//images.contentful.com/71rop70dkqaj/2Y8LhXLnYAYqKCGEWG4EKI/44105a3206c591d5a64a3ea7575169e0/lemnos-logo.jpg","details":{"size":7149,"image":{"width":175,"height":32}},"fileName":"lemnos-logo.jpg","contentType":"image/jpeg"} 3 | {"url":"//images.contentful.com/71rop70dkqaj/3wtvPBbBjiMKqKKga8I2Cu/90b69e82b8b735383d09706bdd2d9dc5/zJYzDlGk.jpeg","details":{"size":12302,"image":{"width":353,"height":353}},"fileName":"zJYzDlGk.jpeg","contentType":"image/jpeg"} 4 | {"url":"//images.contentful.com/71rop70dkqaj/4zj1ZOfHgQ8oqgaSKm4Qo2/8c30486ae79d029aa9f0ed5e7c9ac100/playsam.jpg","details":{"size":7003,"image":{"width":100,"height":100}},"fileName":"playsam.jpg","contentType":"image/jpeg"} 5 | ~~~ 6 | -------------------------------------------------------------------------------- /raw_docs/_partials/get-all-entry-output-android.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | I/Contentful: Hudson Wall Cup 3 | I/Contentful: SoSo Wall Clock 4 | I/Contentful: Whisk Beater 5 | I/Contentful: Playsam Streamliner Classic Car, Espresso 6 | ~~~ 7 | -------------------------------------------------------------------------------- /raw_docs/_partials/get-all-entry-output-python.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | Not a product 3 | Not a product 4 | Whisk Beater 5 | Hudson Wall Cup 6 | Not a product 7 | Not a product 8 | Not a product 9 | Not a product 10 | SoSo Wall Clock 11 | Not a product 12 | Not a product 13 | Not a product 14 | Playsam Streamliner Classic Car, Espresso 15 | ~~~ 16 | -------------------------------------------------------------------------------- /raw_docs/_partials/get-all-entry-output.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | Whisk Beater 3 | Playsam Streamliner Classic Car, Espresso 4 | Hudson Wall Cup 5 | SoSo Wall Clock 6 | ~~~ 7 | -------------------------------------------------------------------------------- /raw_docs/_partials/get-asset-output.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | //images.contentful.com/71rop70dkqaj/wtrHxeu3zEoEce2MokCSi/e86a375b7ad18c25e4ff55de1eac42fe/quwowooybuqbl6ntboz3.jpg 3 | ~~~ 4 | -------------------------------------------------------------------------------- /raw_docs/_partials/get-asset-processed-output.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | //images.contentful.com/71rop70dkqaj/wtrHxeu3zEoEce2MokCSi/e86a375b7ad18c25e4ff55de1eac42fe/quwowooybuqbl6ntboz3.jpg//images.contentful.com/71rop70dkqaj/wtrHxeu3zEoEce2MokCSi/e86a375b7ad18c25e4ff55de1eac42fe/quwowooybuqbl6ntboz3.jpg?h=100&fm=jpg 3 | ~~~ 4 | -------------------------------------------------------------------------------- /raw_docs/_partials/get-entry-output-android.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | I/Contentful: CDAEntry{id=''} 3 | ~~~ 4 | -------------------------------------------------------------------------------- /raw_docs/_partials/get-entry-output.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | Playsam Streamliner Classic Car, Espresso 3 | ~~~ 4 | -------------------------------------------------------------------------------- /raw_docs/_partials/getting-started-intro.md: -------------------------------------------------------------------------------- 1 | Contentful's Content Delivery API (CDA) is a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to an user's location by using our global CDN. 2 | 3 | We publish SDKs for various languages to make developing applications easier. 4 | 5 | ## Pre-requisites 6 | 7 | This tutorial assumes you have read and understood [the guide that covers the Contentful data model](/developers/docs/concepts/data-model/). 8 | 9 | ## Authentication 10 | 11 | For every request, clients [need to provide an API key](/developers/docs/references/authentication/), which is created per space and used to delimit applications and content classes. 12 | 13 | You can create an access token using the [Contentful web app](https://be.contentful.com/login) or the [Content Management API](/developers/docs/references/content-management-api/#/reference/api-keys/create-an-api-key). 14 | -------------------------------------------------------------------------------- /raw_docs/_partials/ruby-python-object-complex-output.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | I am tagged with vase and flowers and accessories 3 | My brand is: Normann Copenhagen 4 | I am tagged with wood and toy and car and sweden and design 5 | My brand is: Playsam 6 | I am tagged with kitchen and accessories and whisk and scandinavia and design 7 | My brand is: Normann Copenhagen 8 | I am tagged with home décor and clocks and interior design and yellow and gifts 9 | My brand is: Lemnos 10 | ~~~ 11 | -------------------------------------------------------------------------------- /raw_docs/_partials/ruby-python-object-output.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | Playsam Streamliner Classic Car, Espresso 3 | it costs 44 4 | I am tagged with wood and toy and car and sweden and design 5 | ~~~ 6 | -------------------------------------------------------------------------------- /raw_docs/_partials/sorted-entries-out.md: -------------------------------------------------------------------------------- 1 | ~~~ 2 | Hudson Wall Cup 3 | Whisk Beater 4 | Playsam Streamliner Classic Car, Espresso 5 | SoSo Wall Clock 6 | ~~~ 7 | -------------------------------------------------------------------------------- /raw_docs/android/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsAndroid 3 | name: Android 4 | title: Using Contentful with Android 5 | metainformation: 'Our Android SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - Basics 9 | - SDKs 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | - [Tools](#tools-and-integrations) 16 | - [Example apps](#example-apps) 17 | 18 | ## SDKs 19 | 20 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 21 | 22 | ### Content Delivery API SDK 23 | 24 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
25 | [View on GitHub](https://github.com/contentful/contentful.java)
26 | [API reference](https://contentful.github.io/contentful.java/) 27 | 28 | ### Content Management API SDK 29 | 30 | This SDK interacts with the Content Management API, and allows you to create, edit, manage, and publish content.
31 | [View on GitHub](https://github.com/contentful/contentful-management.java)
32 | [API reference](https://contentful.github.io/contentful-management.java/) 33 | 34 | ## Tutorials 35 | 36 | ### API demo 37 | 38 | [This guide](/developers/api-demo/java/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 39 | 40 | ### Getting started with the Content Delivery API SDK and Android 41 | 42 | [This tutorial](/developers/docs/android/tutorials/getting-started-with-contentful-and-android/) will walk you through the first steps using the Content Delivery API with a Java application. 43 | 44 | ### Offline persistence with Vault on Android 45 | 46 | [Vault](https://github.com/contentful/vault) is an Android library that lets you define Java representations for your Contentful models and simplifies the persistence of data from Contentful via SQLite.
47 | [View the tutorial](/developers/docs/android/tutorials/offline-persistence-with-vault/) 48 | 49 | ### Type retrieval 50 | 51 | [This tutorial](/developers/docs/android/tutorials/advanced-types/) helps you understand how to filter fetching entries from Contentful based on content and asset types. 52 | 53 | ### Filtering and searching 54 | 55 | [This tutorial](/developers/docs/android/tutorials/advanced-filtering-and-searching/) shows how to filter, search and order entries fetched from Contentful. 56 | 57 | ## Tools and integrations 58 | 59 | ### IntelliJ / Android Studio plugin 60 | 61 | This plugin generates model classes automatically from your Contentful content model.
62 | [View on GitHub](https://github.com/contentful/cf-generator-intellij) 63 | 64 | ### Vault 65 | 66 | A library to simplify persisting data retrieved from Contentful and storing it offline in SQLite.
67 | [View on GitHub](https://github.com/contentful/vault) 68 | 69 | ### Generator.java 70 | 71 | This tool helps you fetch content types from a Contentful space, and generate corresponding java source files.
72 | [View on GitHub](https://github.com/contentful/generator.java) 73 | 74 | ## Example apps 75 | 76 | These example apps are the best way to start building with Contentful. They show you how to start a project based on example spaces available in the Contentful web app. 77 | 78 | ### Discovery App 79 | 80 | This app lets you browse and preview your Contentful spaces.
81 | [Download on Google Play](https://play.google.com/store/apps/details?id=discovery.contentful)
82 | [View on GitHub](https://github.com/contentful/discovery-app-android) 83 | 84 | ### Blog 85 | 86 | A generic blog app connected to a Contentful example space.
87 | [Download on Google Play](https://play.google.com/store/apps/details?id=blog.contentful)
88 | [View on GitHub](https://github.com/contentful/blog-app-android) 89 | 90 | ### Gallery 91 | 92 | A generic gallery app connected to a Contentful example space.
93 | [Download on Google Play](https://play.google.com/store/apps/details?id=gallery.templates.contentful)
94 | [View on GitHub](https://github.com/contentful/gallery-app-android) 95 | 96 | ### Product catalogue 97 | 98 | A generic product catalogue / e-commerce app connected to a Contentful example space.
99 | [Download on Google Play](https://play.google.com/store/apps/details?id=catalogue.contentful)
100 | [View on GitHub](https://github.com/contentful/product-catalogue-android) 101 | 102 | ### Contentful Android Cardboard 103 | 104 | A example to show how to use Google VR with Contentful.
105 | [View on GitHub](https://github.com/contentful-labs/contentful-cardboard) 106 | -------------------------------------------------------------------------------- /raw_docs/android/tutorials/content-type-id.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/raw_docs/android/tutorials/content-type-id.png -------------------------------------------------------------------------------- /raw_docs/android/tutorials/field-codename.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/raw_docs/android/tutorials/field-codename.png -------------------------------------------------------------------------------- /raw_docs/android/tutorials/getting-started-with-contentful-and-android.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsGettingStartedAndroid 3 | name: Getting Started with Contentful and Android 4 | title: Getting Started with Contentful and Android 5 | metainformation: This guide will help you get started with your first basic hello world style Android app using Contentful with a demo space. 6 | slug: null 7 | tags: 8 | - Basics 9 | - SDKs 10 | - Android 11 | nextsteps: 12 | - text: Access data offline in your app with Vault 13 | link: /developers/docs/android/tutorials/offline-persistence-with-vault/ 14 | --- 15 | 16 | This guide will show you how to get started using our [Android SDK](https://github.com/contentful/contentful.java) to consume content. 17 | 18 | :[Getting started tutorial intro](../../_partials/getting-started-intro.md) 19 | 20 | ## Create a new Android project 21 | 22 | Create a new project in Android Studio using the 'Blank Activity' template, and name it whatever you wish. 23 | 24 | ## Dependencies and permissions 25 | 26 | This guide uses [RXAndroid](https://github.com/ReactiveX/RxAndroid) in the examples, which allows you to fetch results without tying up the main Android thread. 27 | 28 | To include the CDA SDK, add the following lines to the _build.gradle_ file: 29 | 30 | ~~~gradle 31 | dependencies { 32 | // [...] 33 | compile 'com.contentful.java:java-sdk:7.4.0' 34 | compile 'io.reactivex:rxandroid:0.23.0' 35 | } 36 | ~~~ 37 | 38 | Add the internet permission to the _AndroidManifest.xml_ file so your app can access the Contentful APIs: 39 | 40 | ~~~xml 41 | 43 | 44 | 45 | ... 46 | 47 | ~~~ 48 | 49 | ## Creating a client 50 | 51 | Add the following code to the `onCreate` method to create a `CDAClient` that communicates with the Contentful APIs: 52 | 53 | :[Create credentials](../../_partials/credentials.md) 54 | 55 | ~~~java 56 | CDAClient client = CDAClient.builder() 57 | .setSpace("") 58 | .setToken("") 59 | .build(); 60 | ~~~ 61 | 62 | Use the [Gson](https://github.com/google/gson) library to make JSON responses easier to read. 63 | 64 | ~~~java 65 | Gson gson = new GsonBuilder().setPrettyPrinting().create(); 66 | ~~~ 67 | 68 | ## Fetching specific items 69 | 70 | If you want to fetch a specific entry, use the `id` of the entry inside a `.one` method: 71 | 72 | ~~~java 73 | client.observe(CDAEntry.class) 74 | .one("") 75 | .observeOn(AndroidSchedulers.mainThread()) 76 | .subscribeOn(Schedulers.io()) 77 | .subscribe(new Subscriber() { 78 | CDAEntry result; 79 | 80 | @Override public void onCompleted() { 81 | Log.i("Contentful", gson.toJson(result)); 82 | } 83 | 84 | @Override public void onError(Throwable error) { 85 | Log.e("Contentful", "could not request entry", error); 86 | } 87 | 88 | @Override public void onNext(CDAEntry cdaEntry) { 89 | result = cdaEntry; 90 | } 91 | }); 92 | ~~~ 93 | 94 | :[Get entry output](../../_partials/get-entry-output-android.md) 95 | 96 | ## Fetching all data from a space 97 | 98 | To fetch all entries, create a new observable that watches for changes, in this case, fetching all entries from the specified space with the `all` method and content type with the `where` method: 99 | 100 | ~~~java 101 | client.observe(CDAEntry.class) 102 | .where("content_type", "") 103 | .all() 104 | .observeOn(AndroidSchedulers.mainThread()) 105 | .subscribeOn(Schedulers.io()) 106 | .subscribe(new Subscriber() { 107 | CDAArray result; 108 | 109 | @Override 110 | public void onCompleted() { 111 | for (CDAResource resource : result.items()) { 112 | CDAEntry entry = (CDAEntry) resource; 113 | Log.i("Contentful", entry.getField("productName").toString()); 114 | } 115 | } 116 | 117 | @Override 118 | public void onError(Throwable error) { 119 | Log.e("Contentful", "could not request entry", error); 120 | } 121 | 122 | @Override 123 | public void onNext(CDAArray cdaArray) { 124 | result = cdaArray; 125 | } 126 | }); 127 | ~~~ 128 | 129 | :[Get all entry output](../../_partials/get-all-entry-output-android.md) 130 | 131 | The `onNext` method saves the array of entries and the `onCompleted` method is called once all entries are fetched from the API. The `onError` method allows you to handle any problems. 132 | 133 | [1]: https://github.com/contentful/contentful.java 134 | 135 | [4]: /developers/docs/android/tutorials/getting-started-with-contentful-and-android/ 136 | -------------------------------------------------------------------------------- /raw_docs/android/tutorials/story-fields.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/raw_docs/android/tutorials/story-fields.png -------------------------------------------------------------------------------- /raw_docs/concepts/apis.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsApis 3 | name: API basics 4 | title: Four content APIs 5 | metainformation: 'Contentful is an API first content management system, offering four REST APIs for working with your content.' 6 | slug: null 7 | tags: 8 | - API 9 | - Basics 10 | nextsteps: null 11 | --- 12 | 13 | Contentful is an API first content management system, offering four REST APIs for working with your content. Each of these APIs serve a different purpose, so which one to use depends on what you want to do: 14 | 15 | - If you're retrieving content to display to users in an app or website, use the [Content Delivery API][cda-section]. 16 | - If you want to programmatically create or update content items, use the [Content Management API][cma-section]. 17 | - If you want to retrieve unpublished content to show in-context previews to content creators and editors, use the [Preview API][cpa-section]. This API behaves like the Content Delivery API, but includes content that has not yet been published. 18 | - If you want to retrieve and apply transformations to images stored in Contentful, use the [Images API][images-section]. 19 | 20 | ## Content Delivery API 21 | 22 | The Content Delivery API (CDA), available at cdn.contentful.com, is a read-only API for delivering content from Contentful to apps, websites and other media. Content is delivered as JSON data, and images, videos and other media as files. 23 | 24 | The API is available via a globally distributed content delivery network. The server closest to the user serves all content, both JSON and binary. This minimizes latency, which especially benefits mobile apps. Hosting content in multiple global data centers also greatly improves the availability of content. 25 | 26 | For more details [read the reference guide for the Content Delivery API][1]. 27 | 28 | ## Content Management API 29 | 30 | The Content Management API (CMA), available at api.contentful.com, is a read-write API for managing content. Unlike the Content Delivery API, the management API requires you to authenticate as a Contentful user. You could use the CMA for several use cases, such as: 31 | 32 | - Automatic imports from different CMSes like WordPress or Drupal. 33 | - Integration with other backend systems, such as an e-commerce shop. 34 | - Building custom editing experiences. We built the [Contentful web app](https://app.contentful.com) on top of this API. 35 | 36 | {: .note} 37 | **Note**: You can also use the Content Management API to retrieve content. But as it's used to manage content, it will retrieve **all** items (i.e. all localized and unpublished content). 38 | 39 | For more details [read the reference documentation for the Content Management API][2]. 40 | 41 | ## Preview API 42 | 43 | The Preview API, available at preview.contentful.com, is a variant of the CDA for previewing your content before delivering it to your customers. You use the Preview API in combination with a "preview" deployment of your website (or a "preview" build of your mobile app) that allows content managers and authors to view their work in-context, as if it were published, using a "preview" access token as though it were delivered by the CDA. 44 | 45 | For more details [read the reference documentation for the Preview API][3]. 46 | 47 | ## Images API 48 | 49 | The Images API, available at images.contentful.com, allows you to resize and crop images, change their background color and convert them to different formats. Using our API for these transformations lets you upload high-quality assets, deliver exactly what your app needs, and still get all the benefits of our caching CDN. 50 | 51 | For more details [read the reference documentation for the Images API][4]. 52 | 53 | [1]: /developers/docs/references/content-delivery-api/ 54 | [2]: /developers/docs/references/content-management-api/ 55 | [3]: /developers/docs/references/content-preview-api/ 56 | [4]: /developers/docs/references/images-api/ 57 | [cda-section]: #content-delivery-api 58 | [cma-section]: #content-management-api 59 | [cpa-section]: #content-preview-api 60 | [images-section]: #images-api 61 | -------------------------------------------------------------------------------- /raw_docs/concepts/sync.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsSync 3 | name: Synchronization 4 | title: Synchronization 5 | metainformation: 'The Sync API allows you to keep a local copy of all content in a space up-to-date via delta updates or content that has changed.' 6 | slug: null 7 | tags: 8 | - Basics 9 | - Content model 10 | nextsteps: 11 | - text: How to use the Sync API with a PHP project 12 | link: /developers/docs/php/tutorials/using-the-sync-api-with-php/ 13 | - text: Syncing offline content to an Android app 14 | link: /developers/docs/android/tutorials/offline-persistence-with-vault/ 15 | - text: Syncing offline content to an iOS app 16 | link: /developers/docs/ios/tutorials/offline-persistence-in-ios-sdk/ 17 | --- 18 | 19 | The Sync API allows you to keep a local copy of all content in a space up-to-date via [delta updates](https://en.wikipedia.org/wiki/Delta_update), or content that has changed. 20 | 21 | Mobile data connections can be slow with high latency compared to broadband internet connections. When apps sync content to the device and access it from a local database (e.g. Core Data, LocalStorage, SQLite) data access is faster and apps can provide a better user experience. 22 | 23 | Without a Sync API, applications require an ongoing internet connection and have to constantly download all data in each synchronization, including content they are already aware of. This wastes a lot of mobile data and time, especially when syncing on cellular data. 24 | 25 | Using the Sync API, applications sync periodically, syncing every few hours when opened or pending user interaction. To do this, it performs delta updates: 26 | 27 | - **Get** content added or changed since the last sync. 28 | - **Delete** local content deleted since the last sync. 29 | 30 | To enable delta updates, Contentful provides [a synchronization endpoint](/developers/docs/references/content-delivery-api/#/reference/synchronization) to the Content Delivery API. This endpoint delivers only new and changed content and notifies about deleted content. It will never transfer duplicate content the client has received before. 31 | 32 | If you are creating a mobile application, it's a good idea to package the initial data sync inside the app and update it with each new release. 33 | 34 | ## The upside 35 | 36 | Syncing with delta updates has the following advantages: 37 | 38 | - **Data usage reduction**: Most mobile data plans have limits on data transfers. By transferring only content that has changed, the amount of data used is small. Keeping the sync small also means an improved chance of success when a mobile connection is slow. 39 | - **Time saving**: Because individual syncs are small they will take less time than repeatedly loading data that hasn't changed. 40 | - **Less resource usage**: Less data to process also means less resources required for processing the data and less waiting time. 41 | - **Content entirety**: The initial sync will transfer all entries since the creation of the space alongside all available localizations, which doesn't happen in the Content Delivery API. 42 | 43 | ## The downside 44 | 45 | The synchronization endpoint will always return the content of a space or a specific content type, so it may not make sense to use it for every use case: 46 | 47 | - If users only want to see the newest content, it would be wasteful to download everything immediately. In this case, it might be better to only fetch selected content based on the date, using search. 48 | - Because the Sync API retrieves all localized content, it might be better to use the delivery API to retrieve results of a single locale. 49 | - Following the initial sync, the API will still transfer deleted entries, which lengthens each response. 50 | - The synchronization endpoint delivers a maximum of 100 items per page. You will need multiple requests to sync large data sets. 51 | 52 | ## Usage 53 | 54 | The first time you use the Sync API in your application, you need to specify the `initial` URL parameter: 55 | 56 | ~~~bash 57 | curl -X GET \ 58 | -H 'Authorization: Bearer b4c0n73n7fu1' \ 59 | 'https://cdn.contentful.com/spaces/cfexampleapi/sync?initial=true' 60 | ~~~ 61 | 62 | The response will contain a `nextPageUrl` value if your request returned more results than fit into a single page. When retrieving the last page, the response will contain a `nextSyncUrl` which contains a sync token you can use to receive delta updates of changes since your last request. 63 | 64 | In addition to the regular `Entry` and `Asset` item types, there can also be `DeletedEntry` and `DeletedAsset` items in the synchronization response. These show that a specific resource has been deleted as delta updates work at the resource level, if a resource has changed, its whole content will be part of the synchronization response. 65 | 66 | ## Localization 67 | 68 | Syncing entries or assets returns all available localizations instead of a single one. Usually resources returned from the delivery API have only a single value per field, the value of the locale you requested or the default locale, but the sync endpoint returns all locales per field. 69 | 70 | ## Further information 71 | 72 | - Using the Sync API for [offline persistence on iOS](/developers/docs/ios/tutorials/offline-persistence-in-ios-sdk/). 73 | - Using synchronization with the [Content Delivery API](/developers/docs/references/content-delivery-api/#/reference/synchronization). 74 | - Using synchronization with the [PHP SDK](/developers/docs/php/tutorials/using-the-sync-api-with-php/). 75 | - Using synchronization with the [JavaScript SDK](/developers/docs/javascript/tutorials/using-the-sync-api-with-js/). 76 | -------------------------------------------------------------------------------- /raw_docs/concepts/uiextensions.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsUiExtensions 3 | name: UI Extensions 4 | title: UI Extensions 5 | metainformation: 'The UI Extensions SDK allows you to customize and extend the functionality of the Contentful Web App entry editor.' 6 | slug: null 7 | tags: 8 | - Customization 9 | nextsteps: 10 | - text: Integrate Contentful with other services via Webhooks 11 | link: /developers/docs/concepts/webhooks/ 12 | - text: Tools and libraries to make your Contentful experience better 13 | link: /developers/docs/tools/extensions/ 14 | --- 15 | 16 | The [UI Extensions SDK](https://github.com/contentful/ui-extensions-sdk) allows you to customize and extend the functionality of the Contentful Web App's entry editor. The editor itself is a container for components that enable editors to manipulate the content stored in content fields. Extensions can be simple user interface controls, such as a dropdown, or more complex micro web applications such as our Markdown editor. Extensions are decoupled entities from field types, and you can reuse them, for example using a dropdown to edit number or text fields. Custom extensions that you create are rendered inside a secure iframe. 17 | 18 | ## Examples 19 | 20 | We have created some example extensions to help you understand how to create your own. 21 | 22 | ### Basic rating dropdown 23 | 24 | A dropdown component to change the value of a number field and make a Content Management API request. 25 | 26 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/rating-dropdown) 27 | 28 | {: .img} 29 | ![Basic rating dropdown extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/45NRCrYg8gwKW08kug8M2W/3050ef93c62eff65642dc29d0cb8821d/BBD4DC36-163A-43A4-B13F-8AE5F6993434.png_dl_1) 30 | 31 | ### Rich text editor 32 | 33 | This example integrates the Alloy rich text editor into text fields. 34 | 35 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/alloy-editor) 36 | 37 | {: .img} 38 | ![Rich text editor extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/3Rzmmj2fuEgwg6kwQ8kSmg/4e9dc78ee1fc95df3bd6063c73fd9bc6/9CDF5788-57FC-444C-8199-04408341F0D7.png_dl_1) 39 | 40 | ### Chessboard 41 | 42 | This extension displays a chessboard and stores the board position as a JSON object. You can drag pieces on the chessboard and the position data updates automatically. The extension also supports collaborative editing, so if two editors open the same entry, moves are synced between them. 43 | 44 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/chessboard) 45 | 46 | {: .img} 47 | ![Chessboard extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/1cSM1cmGUKIIMqcAI8KE4u/c740287f67d682ffbbc014665500efe0/B58EE807-A598-478E-A509-C7203A0C35A2.gif_dl_1) 48 | 49 | ### Slug generator 50 | 51 | This extension automatically generates its value from the title field of an entry. For example typing "Hello World" into the title field will set the extensions input field to "hello-world". It will also check the uniqueness of the slug across a customizable list of content types. 52 | 53 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/slug) 54 | 55 | {: .img} 56 | ![Slug generator extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/3JUTcNxs7eSkIMKgKeCA62/2f0bcb05d409436c322fb425f8838c78/D0B28EA2-9E86-4A23-ACE0-EED81A758A6D.png_dl_1) 57 | 58 | ### Translator 59 | 60 | This extension translates text from the default locale to other locales in a space using the Yandex translation API. 61 | 62 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/translate) 63 | 64 | {: .img} 65 | ![Translator extension screenshot](https://images.contentful.com/tz3n7fnw4ujc/4qrgjGbN7y0oMYSkS6cyko/ee50c251463c954ec875ee35775deefa/92CB0364-E3DA-4649-9D99-8458D7A6A6DD.png_dl_1) 66 | 67 | ### JSON editor 68 | 69 | This extension formats and validates JSON based on the CodeMirror library. You can use it with fields of type "Object". 70 | 71 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/json-editor) 72 | 73 | {: .img} 74 | ![Translator extension](https://images.contentful.com/tz3n7fnw4ujc/47FwXETOc0E4u8U62sImq4/b409b273b03a1ed897c88d576ad5e6af/C020349F-ECC0-49D8-A22F-B143F4233F2C.png_dl_1) 75 | 76 | ### JSON form editor 77 | 78 | This extension integrates the JSON editor library to display an edit form based on a predefined JSON schema. The form input gets stored as a JSON object. 79 | 80 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/json-form-editor) 81 | 82 | {: .img} 83 | ![Translator extension](https://images.contentful.com/tz3n7fnw4ujc/1M9qxfkvLqi4wI0GGASMwq/5da14e00202b17ae754aedcafe662c5a/E200B073-BC43-4B2E-A89B-6EC48D5AD722.png_dl_1) 84 | 85 | ### YouTube ID 86 | 87 | This extension extracts the video id from a valid YouTube URL for a simple way to integrate with 3rd party media services. 88 | 89 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/youtube-id) 90 | 91 | {: .img} 92 | ![YouTube ID extension](https://images.contentful.com/tz3n7fnw4ujc/4M2yCNPQTK8wmiSGmmKIaI/36ec7f8fc7990fff1b521da1dcb359b0/ACC6E270-9904-45F6-94E2-FE0ECEAEADD1.png_dl_1) 93 | 94 | ### Wistia Videos 95 | 96 | The extension loads videos from a project on [wistia](https://wistia.com/) into the Contentful Web Application. A video can be previewed, selected and then stored as part of your content. 97 | 98 | [View on GitHub](https://github.com/contentful/extensions/tree/master/samples/wistia) 99 | 100 | {: .img} 101 | ![Wistia Video extension](https://images.contentful.com/tz3n7fnw4ujc/4Olj3gwXIAEMCqscKIq0yC/68f37a3b6a5daf2664e0b2b3aad6063e/D1F4EE3E-D811-4C4C-BBA5-C990E5B1DD85.gif_dl_1) 102 | -------------------------------------------------------------------------------- /raw_docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsOverview 3 | name: Developer center 4 | title: Developer center 5 | subtitle: Learn how to build with Contentful 6 | metainformation: Everything you need to understand and use Contentful. Includes an overview of concepts, API reference, tutorials, SDKs and code samples. 7 | --- 8 | 9 | You're in the right place to find everything you need to deeper understand and use Contentful. This includes an overview of Contentful concepts, API references, tutorials, details of SDKs and libraries for major platforms, helpful tools and code samples. 10 | 11 | ## Concepts 12 | 13 | These concepts introduce the basics of Contentful. This is the best place to start if you haven't built anything with Contentful before. 14 | 15 | - [API basics](/developers/docs/concepts/apis/) 16 | - [Content model](/developers/docs/concepts/data-model/) 17 | - [Links](/developers/docs/concepts/links/) 18 | - [Images](/developers/docs/concepts/images/) 19 | - [Locales](/developers/docs/concepts/locales/) 20 | - [Synchronization](/developers/docs/concepts/sync/) 21 | - [Multiple environments](/developers/docs/concepts/multiple-environments/) 22 | - [Webhooks](/developers/docs/concepts/webhooks/) 23 | - [Editor interfaces](/developers/docs/concepts/editor-interfaces/) 24 | - [UI extensions](/developers/docs/concepts/uiextensions/) 25 | 26 | ## Reference 27 | 28 | Our four APIs are the core of Contentful, with each one serving a specific purpose: 29 | 30 | - [Content Delivery API](/developers/docs/references/content-delivery-api/) for retrieving content. 31 | - [Content Management API](/developers/docs/references/content-management-api/) for managing content (e.g. creating, updating and deleting content). 32 | - [Preview API](/developers/docs/references/content-preview-api/) for previewing the content before publishing it to production. 33 | - [Images API](/developers/docs/references/images-api/) for requesting images in specific sizes and formats. 34 | 35 | These guides will help you answer questions you have when using our APIs: 36 | 37 | - [Authentication](/developers/docs/references/authentication/) 38 | - [Errors](/developers/docs/references/errors/) 39 | - [HTTP response details](/developers/docs/references/http-details/) 40 | 41 | ## Platforms 42 | 43 | We provide libraries and SDKs for major programming languages and platforms so you don't have to write code for interacting with our APIs from scratch. 44 | 45 | - [Android](/developers/docs/android/) 46 | - [Java](/developers/docs/java/) 47 | - [Objective-C / Swift](/developers/docs/ios/) 48 | - [JavaScript](/developers/docs/javascript/) 49 | - [PHP](/developers/docs/php/) 50 | - [Ruby](/developers/docs/ruby/) 51 | - [Python](/developers/docs/python/) 52 | - [.NET](/developers/docs/net/) 53 | 54 | ## Tools 55 | 56 | We have content import/export tools, iOS and Android development plugins and more, all designed to help speed up development. 57 | 58 | - [Static site generators](/developers/docs/tools/staticsitegenerators/) 59 | - [Space management tools](/developers/docs/tools/spacemanagement/) 60 | - [Extensions](/developers/docs/tools/extensions/) 61 | - [Others and third party tools](/developers/docs/tools/applications/) 62 | 63 | ## More 64 | 65 | Looking for support or detail on our release schedule? 66 | 67 | - [Changelog](/developers/changelog/) 68 | - [Support](https://support.contentful.com/hc/en-us/requests/new) 69 | - [Stack Overflow](http://stackoverflow.com/questions/tagged/contentful?sort=newest) 70 | -------------------------------------------------------------------------------- /raw_docs/ios/tutorials/content-type-id.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/raw_docs/ios/tutorials/content-type-id.png -------------------------------------------------------------------------------- /raw_docs/ios/tutorials/using-contentful-xcode-plugin.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsContentfulXcode 3 | name: Using the Contentful Xcode Plugin 4 | title: Using the Contentful Xcode Plugin 5 | metainformation: 'Our plugin for Xcode generates a Core Data model directly from your content model.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - iOS 10 | - Mobile 11 | nextsteps: 12 | - text: Learn more about content modelling 13 | link: /developers/docs/concepts/data-model/ 14 | --- 15 | 16 | If you are using Contentful with Core Data in your iOS app, a painful manual step is recreating your content model inside Xcode. This is often both time consuming and prone to errors because mismatches between the two models can lead to bugs that are hard to spot. Today we are releasing a plugin for Xcode, which generates a Core Data model directly from your content model, making it easier than ever to use the Content Delivery API in your iOS and macOS projects. 17 | 18 | ## Installation 19 | 20 | You can either clone the [repository][1] and build the plugin yourself or install the [binary release][9]. Installing via [Alcatraz][2] is not supported right now. 21 | 22 | ## Usage 23 | 24 | The plugin adds a new "Generate Model from Contentful..." item to the "Product" menu. 25 | 26 | ![Screen Shot 2014-11-26 at 13.51.52](//images.contentful.com/256tjdsmm689/1Qyzs5KFkkyiIiky0ccYmk/9deb635fae91511e8ceaf9a9cdee858b/Screen_Shot_2014-11-26_at_13.51.52.png) 27 | 28 | This will bring up a dialog where, after providing your CMA access token, you will be able to select a space and a target from your Xcode project. 29 | 30 | ![Screen Shot 2014-11-26 at 13.52.04](//images.contentful.com/256tjdsmm689/6uNk5czVx6COwMy8oauyys/072bbb82082553dd8490262175473638/Screen_Shot_2014-11-26_at_13.52.04.png) 31 | 32 | Using this information, a Core Data model for use with our [CoreDataManager class][3] will be generated and added to the specified target. The file itself will reside in the *"Resources"* group or in the root if that doesn't exist. 33 | 34 | Keep in mind that your own `NSManagedObject` subclasses will still need to conform to the `CDAPersistedAsset`, `CDAPersistedEntry` and `CDAPersistedSpace` protocols as before. You will not need to provide a mapping between your content model and Core Data anymore, though, as this is [derived automatically][4] if field and property names match, which is always the case when using the plugin. 35 | 36 | It is also required that you add [content type validations][5] for any links in your content model, as links in Core Data are always typed. If you require one link field to refer to entries of different content types, your model cannot be represented by Core Data and therefore the model generation will fail and tell you which content type’s field was the culprit. 37 | 38 | You can also use the model generator from the commandline: 39 | 40 | ~~~ bash 41 | ContentfulModelGenerator generate \ 42 | --spaceKey=$CONTENTFUL_SPACE_KEY \ 43 | --accessToken=$CONTENTFUL_MANAGEMENT_API_ACCESS_TOKEN 44 | ~~~ 45 | 46 | As there are a lot of ways of building your content model, please report any issues with the generator so that we can continue to improve it in the future. 47 | 48 | ## Implementation 49 | 50 | As an introduction to writing Xcode plugins, you can check out the writing plugins post on the [Alcatraz][2] blog. 51 | 52 | This plugin is generally rather small, because the majority of the work does not involve Xcode. The class [XcodeProjectManipulation][6] demonstrates how to interact with the project file using the `PBXProject` class from the `DevToolsCore` framework. 53 | 54 | The Core Data model generation revolves around two parts and is encapsulated in a separate commandline utility. This allows its use in build scripts and also avoids problems regarding the use of Swift dependencies in a plugin written in Objective-C. 55 | 56 | The first part is converting from the content model to a `NSManagedObjectModel` instance, accomplished by the [ContentfulModelGenerator][7]. A managed object model consists of `NSEntityDescription` instances, which in turn are a container for `NSAttributeDescription` and `NSRelationshipDescription` objects. The latter is the most critical part, because we have to ensure that each relationship is typed and has an inverse to avoid any warnings when using the model. This is done by introspecting the validations on your content model and by creating missing inverse relations where needed. 57 | 58 | The second part is handled by the [ManagedObjectModelSerializer][8] framework we created, which generates the XML representation from an in-memory `NSManagedObjectModel` instance. This can be utilized to write other tools which need to generate Core Data models and it has a really simple API: 59 | 60 | ~~~ swift 61 | let bundleName = "MyModel" 62 | let model: NSManagedObjectModel 63 | let pathURL: NSURL 64 | 65 | let error = ModelSerializer(model: model!).generateBundle(bundleName, atPath:pathURL) 66 | ~~~ 67 | 68 | [1]: https://github.com/contentful/ContentfulXcodePlugin 69 | [2]: http://alcatraz.io 70 | [3]: /blog/2014/05/09/ios-content-synchronization/ 71 | [4]: https://github.com/contentful/contentful.objc/commit/b82c0f2a68095e28d0d127bd9d070b09daf9b9ed 72 | [5]: /r/knowledgebase/validations/ 73 | [6]: https://github.com/contentful/ContentfulXcodePlugin/blob/master/Code/XcodeProjectManipulation.m 74 | [7]: https://github.com/contentful/ContentfulXcodePlugin/blob/master/Code/ContentfulModelGenerator.m 75 | [8]: https://github.com/contentful/ManagedObjectModelSerializer 76 | [9]: https://github.com/contentful/ContentfulXcodePlugin/releases/tag/0.3 77 | -------------------------------------------------------------------------------- /raw_docs/ios/tutorials/using-management-api-on-ios.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsCmaIos 3 | name: Using the Management API on iOS 4 | title: Using the Management API on iOS 5 | metainformation: This post will walk you through implementing a simple iOS app for uploading images from the device Camera Roll to Contentful. 6 | slug: null 7 | tags: 8 | - CMA 9 | - iOS 10 | - Mobile 11 | nextsteps: 12 | - text: The Contentful Management API reference 13 | link: /developers/docs/references/content-management-api/ 14 | --- 15 | 16 | This post will walk you through implementing a simple iOS app for uploading images from the device's Camera Roll to Contentful. 17 | 18 | Like the [CDA SDK][1] before, you simply install the CMA SDK via [CocoaPods][2]: 19 | 20 | ~~~objc 21 | platform :ios, '7.0' 22 | pod 'ContentfulManagementAPI' 23 | ~~~ 24 | 25 | In the project's [README][3], you can also find explanations for other options, like Git submodules or a pre-built static framework. 26 | 27 | After you successfully installed the library you need to create a client object. For this you need to obtain a Content Management API token. A token can easily be obtained in the [developer center][4]. 28 | 29 | With it, you can instantiate a client object: 30 | 31 | ~~~objc 32 | CMAClient* client = [[CMAClient alloc] initWithAccessToken:@"your-token"]; 33 | ~~~ 34 | 35 | Next we need to fetch a space to use. Contrary to the Content Delivery API, we can just list all spaces the given account has access to: 36 | 37 | ~~~objc 38 | [client fetchAllSpacesWithSuccess:^(CDAResponse *response, CDAArray *array) { 39 | self.spaces = array.items; 40 | 41 | [self.tableView reloadData]; 42 | } failure:^(CDAResponse *response, NSError *error) { 43 | NSLog(@"Error: %@", error); 44 | }]; 45 | ~~~ 46 | 47 | ![In our app, they are displayed as a list of names in a table view](https://images.contentful.com/m5kgizmngfqu/2qSSJ4l0IYQq2WeoaAoUOc/b88666a983860c36385f3d0cccc10244/table-view.png?w=250) 48 | 49 | Once we have selected a specific space, we can create resources, in our case an asset. This can be done using the [`-createAssetWithTitle:description:fileToUpload:success:failure:`][5] method. For this, we need to specify an URL to a file, though and we just have a local image in the photo library at the moment. For a temporary upload, we use [this Pod][6], which just gives us a file URL back, as we need it: 50 | 51 | ~~~objc 52 | [[BBUUploadsImUploader sharedUploader] uploadImage:someImage 53 | completionHandler:^(NSURL *uploadURL, NSError *error) { 54 | if (!uploadURL) { 55 | NSLog(@"Error: %@", error); 56 | return; 57 | } 58 | 59 | NSLog(@"URL of uploaded image: %@", uploadURL); 60 | }]; 61 | ~~~ 62 | 63 | We can obtain the latest photo from the Camera Roll using the `AssetsLibrary` framework quite easily: 64 | 65 | ~~~objc 66 | -(void)fetchLatestPhotoWithCompletionHandler:(void (^)(UIImage* latestPhoto, NSError* error))handler { 67 | NSParameterAssert(handler); 68 | 69 | ALAssetsLibrary *library = [ALAssetsLibrary new]; 70 | 71 | [library enumerateGroupsWithTypes:ALAssetsGroupSavedPhotos usingBlock:^(ALAssetsGroup *group, 72 | BOOL *stop) { 73 | [group setAssetsFilter:[ALAssetsFilter allPhotos]]; 74 | 75 | [group enumerateAssetsWithOptions:NSEnumerationReverse usingBlock:^(ALAsset *alAsset, 76 | NSUInteger index, 77 | BOOL *innerStop) { 78 | if (alAsset) { 79 | ALAssetRepresentation *representation = [alAsset defaultRepresentation]; 80 | UIImage *latestPhoto = [UIImage imageWithCGImage:[representation fullScreenImage]]; 81 | 82 | *stop = YES; *innerStop = YES; 83 | 84 | handler(latestPhoto, nil); 85 | } 86 | }]; 87 | } failureBlock: ^(NSError *error) { 88 | handler(nil, error); 89 | }]; 90 | } 91 | ~~~ 92 | 93 | Using the upload URL, we can create our asset and start the processing of the image: 94 | 95 | ~~~objc 96 | [self.space createAssetWithTitle:@{ @"en-US": @"Some image caption" } 97 | description:@{ @"en-US": @"Upload from iOS" } 98 | fileToUpload:@{ @"en-US": uploadURL.absoluteString } 99 | success:^(CDAResponse *response, CMAAsset *asset) { 100 | [asset processWithSuccess:^{ 101 | NSLog(@"Upload successful."); 102 | } failure:^(CDAResponse *response, NSError *error) { 103 | NSLog(@"Error: %@", error); 104 | }]; 105 | } failure:^(CDAResponse *response, NSError *error) { 106 | NSLog(@"Error: %@", error); 107 | }]; 108 | ~~~ 109 | 110 | As you can see, the Content Management API allows us the specify values for different locales in just one API call. Keep in mind that [`-processWithSuccess:failure:`][7] is asynchronous and will not report errors of the actual image processing back. If it was successful, you can publish the resulting asset from the Contentful [web app][8] as you normally would. 111 | 112 | ![such content, very uploading, wow](https://images.contentful.com/m5kgizmngfqu/31PAoh4jVCqeEKYICEsSkA/0758f8b5bc927ac77a280fa52bf81060/uploading.png?w=250) 113 | 114 | When building the app, be aware that it will automatically upload the lastest image from your Camera Roll. Also, we have the SDK [on GitHub][10] and the API documentation [on CocoaDocs][11]. 115 | 116 | [1]: https://github.com/contentful/contentful.objc 117 | [10]: https://github.com/contentful/contentful-management.objc 118 | [11]: http://cocoadocs.org/docsets/ContentfulManagementAPI 119 | [2]: https://cocoapods.org/ 120 | [3]: https://github.com/contentful/contentful-management.objc#installation 121 | [4]: /developers/docs/references/authentication/ 122 | [5]: http://cocoadocs.org/docsets/ContentfulManagementAPI/0.5.1/Classes/CMASpace.html#//api/name/createAssetWithTitle:description:fileToUpload:success:failure: 123 | [6]: https://github.com/neonichu/IAmUpload 124 | [7]: http://cocoadocs.org/docsets/ContentfulManagementAPI/0.5.1/Classes/CMAAsset.html#//api/name/processWithSuccess:failure: 125 | [8]: https://app.contentful.com/ 126 | -------------------------------------------------------------------------------- /raw_docs/java/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsJava 3 | name: Java 4 | title: Using Contentful with Java 5 | metainformation: 'Our Java SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: null 8 | nextsteps: null 9 | --- 10 | 11 | - [SDKs](#sdks) 12 | - [Tutorials](#tutorials) 13 | - [Tools](#tools-and-integrations) 14 | - [Example apps](#example-apps) 15 | 16 | ## SDKs 17 | 18 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 19 | 20 | ### Content Delivery API SDK 21 | 22 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
23 | [View on GitHub](https://github.com/contentful/contentful.java)
24 | [API reference](https://contentful.github.io/contentful.java/) 25 | 26 | ### Content Management API SDK 27 | 28 | This SDK interacts with the Content Management API, and allows you to create, edit, manage, and publish content.
29 | [View on GitHub](https://github.com/contentful/contentful-management.java)
30 | [API reference](https://contentful.github.io/contentful-management.java/) 31 | 32 | ## Tutorials 33 | 34 | ### Create and deploy a Java application using Contentful 35 | 36 | [This guide](https://github.com/contentful/product-catalogue-java) shows you how to create and deploy a web application with Java and Spring Boot that uses Contentful. 37 | 38 | ### API demo 39 | 40 | [This guide](/developers/api-demo/java/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 41 | 42 | ## Tools and integrations 43 | 44 | ## Example apps 45 | 46 | These example apps are the best way to start building with Contentful. They show you how to start a project based on example spaces available in the Contentful web app. 47 | 48 | ### Product catalogue 49 | 50 | A generic product catalogue / e-commerce app connected to a Contentful example space.
51 | [View on GitHub](https://github.com/contentful/product-catalogue-java) 52 | -------------------------------------------------------------------------------- /raw_docs/javascript/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsJavascript 3 | name: JavaScript 4 | title: Using Contentful with JavaScript 5 | metainformation: 'Our JavaScript SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - Basics 9 | - SDKs 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | - [Tools](#tools-and-integrations) 16 | - [Example apps](#example-apps) 17 | 18 | ## SDKs 19 | 20 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 21 | 22 | ### Content Delivery API SDK 23 | 24 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
25 | [View on GitHub](https://github.com/contentful/contentful.js)
26 | [SDK reference](https://contentful.github.io/contentful.js)
27 | [Try out the browser SDK with JSFiddle](https://jsfiddle.net/contentful/kefaj4s8/)
28 | [Try out the Node.js package with Tonic](https://runkit.com/npm/contentful) 29 | 30 | ### Content Management API SDK 31 | 32 | This SDK interacts with the Content Management API, and allows you to create, edit, manage, and publish content. The API also offers tools for managing editorial teams and cooperation.
33 | [View on GitHub](https://github.com/contentful/contentful-management.js)
34 | [SDK reference](https://contentful.github.io/contentful-management.js/contentful-management/1.3.0) 35 | 36 | ## Tutorials 37 | 38 | ### Create and deploy a Node.js application using Contentful 39 | 40 | [This guide](/developers/docs/javascript/tutorials/create-expressjs-app-using-contentful/) shows you how to create and deploy an Express.js app that uses Contentful. 41 | 42 | ### API demo 43 | 44 | [This guide for JavaScript](/developers/api-demo/javascript/) and [this guide for Node.js](/developers/api-demo/nodejs/) are the perfect starting points to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 45 | 46 | ### Getting started with the Content Delivery API SDK and JavaScript 47 | 48 | [This tutorial](/developers/docs/javascript/tutorials/using-js-cda-sdk/) will walk you through the first steps using the Content Delivery API with a JavaScript application. 49 | 50 | ### Using the Sync API with JavaScript 51 | 52 | The Sync API allows you to keep a local copy of all content from a space up to date via delta updates. [This tutorial](/developers/docs/javascript/tutorials/using-the-sync-api-with-js/) will show you how to use the Sync API with the Contentful JavaScript SDK. 53 | 54 | ## Example apps 55 | 56 | ### Product catalogue 57 | 58 | This demo project shows how to build a frontend JavaScript based application with Contentful for a product catalogue, based on the Contentful starter product catalogue example space.
59 | [Try it out](https://contentful.github.io/product-catalogue-js/)
60 | [View on GitHub](https://github.com/contentful/product-catalogue-js) 61 | 62 | ### Photo gallery 63 | 64 | This single page application shows how to build a photo gallery app with [React](https://facebook.github.io/react/) connected to a Contentful space.
65 | [Try it out](https://contentful.github.io/gallery-app-react/)
66 | [View on GitHub](https://github.com/contentful/gallery-app-react) 67 | 68 | ### Discovery app 69 | 70 | The Discovery App allows you to browse and preview your Contentful content.
71 | [Try it out](https://contentful.github.io/discovery-app-react)
72 | [View on GitHub](https://github.com/contentful/discovery-app-react) 73 | 74 | ## Tools and integrations 75 | 76 | These third-party libraries are **not officially supported** by Contentful and may be incomplete. If you want to include your own libraries on this list open a pull request that matches our [contribution guidelines](https://github.com/contentful-labs/awesome-contentful/blob/master/CONTRIBUTING.md). 77 | 78 | ### Angular-Contentful 79 | 80 | An **unsupported** AngularJS library to access the Content Delivery API.
81 | [View on GitHub](https://github.com/jvandemo/angular-contentful) 82 | -------------------------------------------------------------------------------- /raw_docs/javascript/tutorials/create-expressjs-app-using-contentful.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsExpressjsApp 3 | name: Creating an Express JavaScript application with Contentful 4 | title: Creating an Express JavaScript application with Contentful 5 | metainformation: 'This guide will walk you through your first steps using Contentful with an Express Node.js application.' 6 | slug: null 7 | tags: 8 | - JavaScript 9 | - SDKs 10 | nextsteps: 11 | - text: Using the Contentful Delivery API in a JavaScript app 12 | link: /developers/docs/javascript/tutorials/using-js-cda-sdk/ 13 | - text: How to only update content that has changed 14 | link: /developers/docs/javascript/tutorials/using-the-sync-api-with-js/ 15 | --- 16 | 17 | This guide will walk you through your first steps using Contentful with an Express Node.js application. It will provide a step-by-step guide on how to get your first entries and start using the content you create on Contentful. 18 | 19 | ## Requirements 20 | 21 | - A [Heroku][1] account 22 | - [Heroku CLI][14] installed 23 | - [Node.js][2] 6.2.1 installed 24 | - Npm 3.10.7 which should be installed with `Node.js` 25 | - [Git][12] installed 26 | - Basic Command Line Interface knowledge 27 | 28 | ## Check out the final project 29 | 30 | You can deploy the final project to Heroku to see how it works by clicking the button below. 31 | 32 | [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/contentful/contentful_express_tutorial) 33 | 34 | ## Start from a demo application 35 | 36 | First we'll start with a [demo project][3], which is a simple Express.js application using Contentful's 'Product Catalogue' template, so that you can see it running for yourself. 37 | 38 | Run the following commands to get started. 39 | 40 | - Clone the example repository: 41 | 42 | ~~~bash 43 | git clone https://github.com/contentful/contentful_express_tutorial.git 44 | ~~~ 45 | 46 | - Navigate into the repository's directory: 47 | 48 | ~~~bash 49 | $ cd contentful_express_tutorial 50 | ~~~ 51 | 52 | - Install dependencies: 53 | 54 | ~~~bash 55 | $ npm install 56 | ~~~ 57 | 58 | - Run the server: 59 | 60 | ~~~bash 61 | $ npm run dev 62 | ~~~ 63 | 64 | Everything is now set up. You can view your new data by opening _http://localhost:3000_ in your browser. 65 | 66 | It should look something like this: 67 | 68 | ![Express js Demo Application](./default_website.png) 69 | 70 | ### Using your own content 71 | 72 | You can create your own custom data by following these steps: 73 | 74 | - Create an account with [Contentful][6] or [Log In][5]. 75 | - Create a new Space with the 'Product Catalogue' template, name it whatever you like. 76 | - Copy the space Id and API key as shown in the screenshot 77 | 78 | ![Keys Page](keys_and_ids.png) 79 | 80 | - In the Express js application: 81 | 82 | - navigate to the package.json file open it and change the values `accessToken` and `space` in the `config` section and save. 83 | - run `npm run dev` to start the server 84 | - Your space will be now displayed in your application 85 | 86 | Next in the [Contentful web app][6] > Content: 87 | 88 | - Open the product called 'Playsam Streamliner Classic Car, Espresso'. 89 | - Change the value of the _Product name_ field to a new value, 90 | - Click the _Publish changes_ button 91 | - Wait a few seconds for the changes to propagate to the CDN. 92 | - Reload your Express js application and you will see the new product name. 93 | 94 | You can continue to edit your content inside the [Contentful web app][13] and see the content change inside your application. 95 | 96 | ### Deploy the demo to Heroku 97 | 98 | To view the demo application live in your own production environment, follow these steps: 99 | 100 | - Having Heroku CLI Installed, Login to Heroku if you're not logged in already: 101 | 102 | ~~~bash 103 | heroku login 104 | ~~~ 105 | 106 | - Create a new instance: 107 | 108 | ~~~bash 109 | heroku create 110 | ~~~ 111 | 112 | - Commit your change: 113 | 114 | ~~~bash 115 | git add . 116 | git commit -m "Add Website" 117 | ~~~ 118 | 119 | - Deploy to Heroku: 120 | 121 | ~~~bash 122 | git push heroku master 123 | ~~~ 124 | 125 | - Open the application in your browser: 126 | 127 | ~~~bash 128 | heroku open 129 | ~~~ 130 | 131 | ## Next Steps 132 | 133 | After this guide, you should be able to start using Contentful with your Express js applications, but every project has different needs and we want to provide you with the best solutions we can. 134 | 135 | You can read about the Contentful CDA library in more detail on our [contentful.js GitHub][1] or our [Getting Started with CDA SDK tutorial][9]. We also suggest taking a look at our [Product Example Application][10]. 136 | 137 | Do you like building static sites? Check how to build static sites using Contentful with [Metalsmith][11] 138 | 139 | [1]: https://www.heroku.com 140 | [10]: https://github.com/contentful/product-catalogue-js 141 | [11]: https://github.com/contentful-labs/contentful-metalsmith-example 142 | [12]: https://git-scm.com/downloads 143 | [14]: https://devcenter.heroku.com/articles/heroku-cli#download-and-install 144 | [2]: https://nodejs.org 145 | [3]: https://github.com/contentful/contentful_express_tutorial 146 | [5]: /sign-up/#starter 147 | [6]: https://app.contentful.com 148 | [7]: /developers/docs/references/content-delivery-api/#/reference/search-parameters 149 | [8]: https://github.com/contentful/contentful.js 150 | [9]: /developers/docs/javascript/tutorials/using-js-cda-sdk/ 151 | -------------------------------------------------------------------------------- /raw_docs/javascript/tutorials/default_website.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/raw_docs/javascript/tutorials/default_website.png -------------------------------------------------------------------------------- /raw_docs/javascript/tutorials/keys_and_ids.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/contentful/slash-developers/ec9a447d137d47679359b5a6418bcf2ac84f7321/raw_docs/javascript/tutorials/keys_and_ids.png -------------------------------------------------------------------------------- /raw_docs/javascript/tutorials/using-the-sync-api-with-js.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsSyncApiWithJS 3 | name: Using the Sync API with JavaScript 4 | title: Using the Sync API with JavaScript 5 | metainformation: 'This tutorial will show you how to use the Sync API with the Contentful JavaScript SDK to keep a local copy of content up to date via delta updates.' 6 | slug: null 7 | tags: 8 | - Basics 9 | - Content model 10 | nextsteps: 11 | - text: Further details on our Syncronization endpoint 12 | link: /developers/docs/references/content-delivery-api/#/reference/synchronization/ 13 | --- 14 | 15 | The [sync](/developers/docs/concepts/sync/) API allows you to keep a local copy of all content of a space up to date via delta updates. This tutorial will show you how to use the Sync API with the Contentful JavaScript SDK. 16 | 17 | This tutorial shows some examples using the [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) API on a browser, but you can also use any other [storage](https://github.com/localForage/localForage) [wrapper](https://pouchdb.com/) or any [storage layer](https://github.com/Level/levelup) in Node.js. 18 | 19 | ## Getting started 20 | 21 | After you've [installed the SDK](/developers/docs/javascript/tutorials/using-js-cda-sdk/#setting-up-the-client) you'll need to setup the client with your credentials: 22 | 23 | ~~~javascript 24 | var client = contentful.createClient({ 25 | space: 'cfexampleapi', 26 | accessToken: 'b4c0n73n7fu1' 27 | }) 28 | ~~~ 29 | 30 | Now you can run your first sync: 31 | 32 | ~~~javascript 33 | client.sync({initial: true}) 34 | .then((response) => { 35 | console.log(response.entries) 36 | console.log(response.assets) 37 | }) 38 | ~~~ 39 | 40 | As this is the first sync, your response will contain all existing entries and assets. 41 | 42 | Any links from entries to other entries and assets will also be resolved. If you don't want that to happen, you can turn it off: 43 | 44 | ~~~javascript 45 | client.sync({ 46 | initial: true, 47 | resolveLinks: false 48 | }) 49 | .then((response) => { 50 | console.log(response.entries) 51 | console.log(response.assets) 52 | }) 53 | ~~~ 54 | 55 | If you'd like to store the retrieved content, you can use the convenient `toPlainObject` method or `stringifySafe` to prevent issues with circular links, for example: 56 | 57 | ~~~javascript 58 | client.sync({initial: true}) 59 | .then((response) => { 60 | const responseObj = JSON.parse(response.stringifySafe()); 61 | const entries = responseObj.entries; 62 | window.localStorage.setItem('contentfulEntries', JSON.stringify(entries)) 63 | }) 64 | ~~~ 65 | 66 | 67 | Your response will also contain a token, which you should store: 68 | 69 | ~~~javascript 70 | client.sync({initial: true}) 71 | .then((response) => { 72 | window.localStorage.setItem('contentfulSyncToken', response.nextSyncToken) 73 | }) 74 | ~~~ 75 | 76 | ### Continuing the sync 77 | 78 | The next time you want to get updated content, you can use the token you previously stored. This will give you only new, and updated content, as well as a list of what content has been deleted: 79 | 80 | ~~~javascript 81 | client.sync({nextSyncToken: window.localStorage.getItem('contentfulSyncToken')}) 82 | .then((response) => { 83 | console.log(response.entries) 84 | console.log(response.assets) 85 | console.log(response.deletedEntries) 86 | console.log(response.deletedAssets) 87 | // store the new token 88 | window.localStorage.setItem('contentfulSyncToken', response.nextSyncToken) 89 | }) 90 | ~~~ 91 | 92 | Every time you perform a sync you get a new token, which represents that point in time for your space, so don't forget to store it again. 93 | 94 | You can then loop through the content you have previously stored and removed any content that is now marked as deleted, but that is left as an exercise to the reader. 95 | 96 | ## Conclusion 97 | 98 | Using the Sync API, you can keep your users easily up to date with your latest content. 99 | 100 | You can find the JavaScript SDK on [Github](https://github.com/contentful/contentful.js). Don't forget to open an issue if you run into any trouble. 101 | -------------------------------------------------------------------------------- /raw_docs/net/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsNet 3 | name: .NET 4 | title: Using Contentful with .NET 5 | metainformation: 'Our .NET SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - .Net 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | 16 | ## SDKs 17 | 18 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 19 | 20 | ### Content Delivery API SDK 21 | 22 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
23 | [View on GitHub](https://github.com/contentful/contentful.net) 24 | 25 | ## Tutorials 26 | 27 | ### API demo 28 | 29 | [This guide](/developers/api-demo/dotnet/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 30 | 31 | ### Getting started with the Content Delivery API SDK and .Net 32 | 33 | [This tutorial](/developers/docs/net/tutorials/using-net-cda-sdk/) will walk you through the first steps using the Content Delivery API with a .Net application. 34 | 35 | ### Getting started with the Content Management API and .Net 36 | 37 | [This tutorial](/developers/docs/net/tutorials/management-api/) will guide you through most of the methods available in the Content Management API with a .Net application. 38 | 39 | [This tutorial](/developers/docs/net/tutorials/webhook-roles-snapshots/) will go in depth into managing webhooks, roles and space memberships and versioning entries with snapshots. 40 | 41 | ### Gettings started with Contentful and ASP.NET core 42 | 43 | [This tutorial](/developers/docs/net/tutorials/aspnet-core/) will walk you through the first steps using the .Net SDK with an ASP.NET core application. 44 | -------------------------------------------------------------------------------- /raw_docs/php/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsPhp 3 | name: PHP 4 | title: Using Contentful with PHP 5 | metainformation: 'Our PHP SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - PHP 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | - [Tools](#tools-and-integrations) 16 | - [Example apps](#example-apps) 17 | 18 | ## SDKs 19 | 20 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 21 | 22 | ### Content Delivery API SDK 23 | 24 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
25 | [View on GitHub](https://github.com/contentful/contentful.php)
26 | [API reference](https://contentful.github.io/contentful.php/api/) 27 | 28 | ## Tutorials 29 | 30 | ### API demo 31 | 32 | [This guide](/developers/api-demo/php/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 33 | 34 | ### Getting started with the Content Delivery API SDK and PHP 35 | 36 | [This tutorial](/developers/docs/php/tutorials/getting-started-with-contentful-and-php/) will walk you through the first steps using the Content Delivery API with a PHP application. 37 | 38 | ### Using the Sync API with PHP 39 | 40 | The Sync API allows you to keep a local copy of all the content in a space up-to-date via delta updates. [This tutorial](/developers/docs/php/tutorials/using-the-sync-api-with-php/) shows you how to use the Sync API with the Contentful PHP SDK. 41 | 42 | ### Getting started with Contentful and Symfony 43 | 44 | [This tutorial](/developers/docs/php/tutorials/getting-started-with-contentful-and-symfony/) shows you how to include and setup the `ContentfulBundle` in your [Symfony](https://symfony.com/) application. 45 | 46 | ### Getting started with Contentful and Laravel 47 | 48 | [This tutorial](/developers/docs/php/tutorials/getting-started-with-contentful-and-laravel/) shows you how to setup integration with Contentful and [Laravel](https://laravel.com/). 49 | 50 | ## Tools and integrations 51 | 52 | ### Symfony bundle 53 | 54 | This bundle helps you integrate Symfony with the Content Delivery API
55 | [View on GitHub](https://github.com/contentful/ContentfulBundle) 56 | 57 | ### Laravel integration 58 | 59 | This bundle helps you integrate Laravel with the Content Delivery API
60 | [View on GitHub](https://github.com/contentful/contentful-laravel) 61 | 62 | ## Example apps 63 | 64 | These example apps are the best way to start building with Contentful. They show you how to start a project based on example spaces available in the Contentful web app. 65 | 66 | ### Symfony 67 | 68 | A generic product catalogue / e-commerce app connected to an example space using Symfony.
69 | [View on GitHub](https://github.com/contentful/product-catalogue-app-symfony) 70 | 71 | ### Laravel 72 | 73 | A simple blog using Contentful and Laravel.
74 | [View on GitHub](https://github.com/contentful/blog-app-laravel) 75 | -------------------------------------------------------------------------------- /raw_docs/php/tutorials/getting-started-with-contentful-and-laravel.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsGettingStartedLaravel 3 | name: Getting Started with Contentful and Laravel 4 | title: Getting Started with Contentful and Laravel 5 | metainformation: 'This tutorial will walk you through your first steps in using Contentful with a PHP application.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - PHP 10 | nextsteps: null 11 | --- 12 | 13 | This tutorial will show you how to setup the Content Delivery API in your Laravel application and how to access your content 14 | inside the framework. 15 | 16 | {: .note} 17 | The ContentfulBundle and the PHP SDK are currently in beta and their APIs may change before a stable release. 18 | 19 | ## Requirements 20 | 21 | The Contentful Laravel integrations requires at least PHP 5.5.9 and Laravel 5. PHP 7 is supported. 22 | 23 | ## Installation 24 | 25 | The easiest way to install the Laravel integration is is to use [Composer][1]. If you've downloaded 26 | `composer.phar`, the integration can be installed by executing: 27 | 28 | ~~~ bash 29 | php composer.phar require contentful/contentful:@beta 30 | php composer.phar require contentful/laravel:@beta 31 | ~~~ 32 | 33 | {: .note} 34 | Currently the SDK and the integration both need to be added to your composer.json because both only have had beta quality releases. 35 | 36 | ### Enable the Service Provider 37 | 38 | Next you need to enable the Service Provider by adding it to `config/app.php`: 39 | 40 | ~~~ php 41 | [ 44 | // ... 45 | new Contentful\ContentfulBundle\ContentfulBundle(), 46 | // ... 47 | ] 48 | ]; 49 | ~~~ 50 | 51 | ### Configuration 52 | 53 | Before the Contentful SDK can be configured, the necessary config files have to be published. To do so execute the following command: 54 | 55 | ~~~ bash 56 | php artisan vendor:publish 57 | ~~~ 58 | 59 | This will add a file called `contentful.php` to your `/config` folder. 60 | 61 | Now open that file and fill in your space ID and API key. 62 | 63 | ~~~ php 64 | 'cfexampleapi', 67 | 'delivery.token' => 'b4c0n73n7fu1' 68 | ]; 69 | ~~~ 70 | 71 | To use the Preview API instead of the Content Delivery API, simply add `'delivery.preview' => true`: 72 | 73 | ~~~ php 74 | 'cfexampleapi', 77 | 'delivery.token' => 'e5e8d4c5c122cf28fc1af3ff77d28bef78a3952957f15067bbc29f2f0dde0b50', 78 | 'delivery.preview' => true 79 | ]; 80 | ~~~ 81 | 82 | ## Using Contentful 83 | 84 | You now have a service for the class `Contentful\Delivery\Client` available. A small controller displaying an entry 85 | based on an ID in the URL could look like this: 86 | 87 | ~~~ php 88 | client = $client; 103 | } 104 | 105 | public function entryAction($id) 106 | { 107 | $entry = $this->client->getEntry($id); 108 | 109 | if (!$entry) { 110 | abort(404); 111 | } 112 | 113 | return view('entry', [ 114 | 'entry' => $entry 115 | ]); 116 | } 117 | } 118 | ~~~ 119 | 120 | To discover how to use the Contentful client, check out the 121 | [getting started with Contentful and PHP](/developers/docs/php/tutorials/getting-started-with-contentful-and-php/) tutorial. 122 | 123 | ## Conclusion 124 | 125 | Now you should be familiar with the basics of how to use Contentful in a Laravel application. You can find the integration on 126 | [GitHub](https://github.com/contentful/contentful-laravel/) and [Packagist](https://packagist.org/packages/contentful/laravel). 127 | To get a deeper understanding, read some of our other [PHP tutorials](/developers/docs/php/#tutorials). If you find a bug, 128 | or have an idea how to further integrate with Laravel, please open an [issue on GitHub](https://github.com/contentful/contentful-laravel/issues). 129 | 130 | [1]: https://getcomposer.org 131 | -------------------------------------------------------------------------------- /raw_docs/php/tutorials/getting-started-with-contentful-and-php.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsGettingStartedPhp 3 | name: Getting Started with Contentful and PHP 4 | title: Getting Started with Contentful and PHP 5 | metainformation: This tutorial will walk you through your first steps in using Contentful with a PHP application. 6 | slug: null 7 | tags: 8 | - SDKs 9 | - PHP 10 | nextsteps: 11 | - text: How to only update content that has changed 12 | link: /developers/docs/php/tutorials/using-the-sync-api-with-php/ 13 | --- 14 | 15 | This guide will show you how to get started using our [PHP SDK](https://github.com/contentful/contentful.php) to consume content. 16 | 17 | {: .note} 18 | The Contentful PHP SDK is in beta and the API may change before a stable release. 19 | 20 | :[Getting started tutorial intro](../../_partials/getting-started-intro.md) 21 | 22 | ## Installation 23 | 24 | The easiest way to install the Contentful PHP SDK is to use [Composer][2] and run the following command: 25 | 26 | ~~~bash 27 | php composer.phar install contentful/contentful:@beta 28 | ~~~ 29 | 30 | Add the Composer autoloader to the top of your project: 31 | 32 | ~~~php 33 | require_once 'vendor/autoload.php'; 34 | ~~~ 35 | 36 | ## Setting up the Contentful client 37 | 38 | Once you have installed the SDK you need to create a `Client`. 39 | 40 | :[Create credentials](../../_partials/credentials.md) 41 | 42 | ~~~php 43 | $client = new \Contentful\Delivery\Client('', ''); 44 | ~~~ 45 | 46 | ## Getting your content 47 | 48 | Contentful separates content between entries, which contain your data and relationships with other content or images, and assets, which represent static content, like images, and are served as files. You can read more about this in our [data model concepts guide][3]. 49 | 50 | ### Entries 51 | 52 | With the client created, you can start consuming data from the API. 53 | 54 | The code below retrieves all entries in your space from the API, but don't print the output yet, as this will result in a lot of JSON, you will learn how to filter the output later: 55 | 56 | ~~~php 57 | $entries = $client->getEntries(); 58 | ~~~ 59 | 60 | Whereas this code retrieves a single entry specified by an ID. 61 | 62 | ~~~php 63 | $entryId = ''; 64 | $entry = $client->getEntry($entryId); 65 | echo $entry->getproductName(); 66 | ~~~ 67 | 68 | :[Get entry output](../../_partials/get-entry-output.md) 69 | 70 | To specify more [complex queries][4] you can use the query builder. The example below filters results to a specific content type (the product) and sorts them by price: 71 | 72 | ~~~php 73 | $query = new \Contentful\Delivery\Query; 74 | $query->setContentType('') 75 | ->orderBy('fields.price'); 76 | 77 | $productEntriesByPrice = $client->getEntries($query); 78 | ~~~ 79 | 80 | ### Using the entry 81 | 82 | Once you've got the entry, you can access its content through getter methods: 83 | 84 | ~~~php 85 | foreach ($productEntriesByPrice as $product) { 86 | echo $product->getproductName(), PHP_EOL; 87 | } 88 | ~~~ 89 | 90 | :[Get all entry output](../../_partials/get-all-entry-output.md) 91 | 92 | If an entry contains a [link][5] to an asset or another entry, the SDK will automatically load it. The example below shows the name of the brand linked to the product: 93 | 94 | ~~~php 95 | foreach ($productEntriesByPrice as $product) { 96 | echo $product->getproductName(), ', Brand: ', $product->getBrand()->getcompanyName(), PHP_EOL; 97 | } 98 | ~~~ 99 | 100 | ## Using assets 101 | 102 | Querying assets works similarly to querying entries. You can retrieve all assets from a space with the following: 103 | 104 | ~~~php 105 | $assets = $client->getAssets(); 106 | ~~~ 107 | 108 | Or to get a single asset: 109 | 110 | ~~~php 111 | $assetId = ''; 112 | $asset = $client->getAsset($assetId); 113 | ~~~ 114 | 115 | As with entries you can also use more [complex queries][6]: 116 | 117 | ~~~php 118 | $query = new \Contentful\Delivery\Query; 119 | $query->orderBy('sys.createdAt'); 120 | $assets = $client->getAssets($query); 121 | ~~~ 122 | 123 | Once you have an asset, you can access its metadata and an URL for the actual file: 124 | 125 | ~~~php 126 | echo $asset->getTitle(), PHP_EOL; 127 | echo $asset->getFile()->getUrl(); 128 | ~~~ 129 | 130 | :[Get single asset](../../_partials/get-asset-output.md) 131 | 132 | Using the [Images API][7] you can control how Contentful serves images. For example, to convert an image to a JPEG and resize it to a height of no more than 100 pixels: 133 | 134 | ~~~php 135 | $options = new \Contentful\Delivery\ImageOptions; 136 | $options->setFormat('jpg') 137 | ->setHeight(100); 138 | echo $asset->getFile()->getUrl($options); 139 | ~~~ 140 | 141 | :[Get single asset](../../_partials/get-asset-processed-output.md) 142 | 143 | [1]: https://github.com/contentful/contentful.php 144 | 145 | [2]: https://getcomposer.org 146 | 147 | [3]: /developers/docs/concepts/data-model/ 148 | 149 | [4]: /developers/docs/references/content-delivery-api/#/reference/search-parameters/ 150 | 151 | [5]: /developers/docs/concepts/links/ 152 | 153 | [6]: /developers/docs/references/content-delivery-api/#/reference/search-parameters/filtering-assets-by-mime-type/ 154 | 155 | [7]: /developers/docs/references/images-api/ 156 | -------------------------------------------------------------------------------- /raw_docs/php/tutorials/using-the-sync-api-with-php.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsSyncApiWithPhp 3 | name: Using the Sync API with PHP 4 | title: Using the Sync API with PHP 5 | metainformation: 'This tutorial will walk you how to use the Sync API with the Contentful PHP SDK to keep a local copy of content up-to-date via delta updates.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - PHP 10 | nextsteps: null 11 | --- 12 | 13 | The [sync](/developers/docs/concepts/sync/) API allows you to keep a local copy of all content of a space up-to-date via 14 | delta updates. This tutorial will walk you how to use the Sync API with the Contentful PHP SDK. 15 | 16 | {: .note} 17 | The Contentful PHP SDK is currently in beta and the API may change before a stable release. 18 | 19 | ## Getting started 20 | 21 | After you've [installed the SDK](/developers/docs/php/tutorials/getting-started-with-contentful-and-php/#installation) 22 | you need to set up the client and get an instance of the synchronization manager. For this tutorial we'll be using an example space. 23 | 24 | ~~~ php 25 | getSynchronizationManager(); 28 | ~~~ 29 | 30 | Now we're able to start the initial synchronization. 31 | 32 | ~~~ php 33 | startSync(); 35 | $items = $result->getItems(); 36 | ~~~ 37 | 38 | As this is the initial sync `$items` will contain the entries and assets of your space. Storing these objects to the 39 | filesystem or a database will be left to you. To make it somewhat easier, all objects can be serialized to JSON and 40 | later revived: 41 | 42 | ~~~ php 43 | reviveJson($json); 46 | ~~~ 47 | 48 | If you have a space that's bigger than the example space, the sync might involve 49 | more records that can't be handled with one API call. To get absolutely everything you have to check `$result->isDone()`: 50 | 51 | ~~~ php 52 | startSync(); 54 | 55 | while (!$result->isDone()) { 56 | $result = $syncManager->continueSync($result); 57 | } 58 | ~~~ 59 | 60 | ### Continuing the sync 61 | 62 | To be able to get new changes later, you need to save the last token after the initial synchronization is complete. Using 63 | this token you can then resume the synchronization at the last state you've saved. 64 | 65 | ~~~ php 66 | getToken(); 69 | 70 | // Whenever you want to sync again 71 | 72 | $result = $syncManager->continueSync($token); 73 | ~~~ 74 | 75 | When continuing the sync you might encounter instances of the classes `DeletedEntry` and `DeletedEntry`. These give you 76 | access to some metadata, most importantly the ID, to delete the resources from your local storage. 77 | 78 | ## Conclusion 79 | 80 | With this information you should be able to implement a solution syncing your content to local storage. If you run into 81 | any trouble please open an issue. 82 | 83 | You can find the Contentful PHP SDK on [GitHub][1]. 84 | 85 | [1]: https://github.com/contentful/contentful.php 86 | -------------------------------------------------------------------------------- /raw_docs/python/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsPython 3 | name: Python 4 | title: Using Contentful with Python 5 | metainformation: 'Our Python SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Python 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | 16 | ## SDKs 17 | 18 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 19 | 20 | ### CDA - Content Delivery API 21 | 22 | Contentful's Content Delivery API (CDA) is a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to an user's location by using our global CDN.
23 | [View on GitHub](https://github.com/contentful/contentful.py) 24 | [API reference](https://contentful.github.io/contentful.py) 25 | 26 | ## Tutorials 27 | 28 | ### Create and deploy a Django application using Contentful 29 | 30 | [This guide](/developers/docs/python/tutorials/full-stack-getting-started/) explains how to use Contentful with a Django application. 31 | 32 | ### Getting started with the Content Delivery API SDK and Python 33 | 34 | [This tutorial](/developers/docs/python/tutorials/getting-started-with-contentful-and-python/) will walk you through the first steps using the Content Delivery API with a Python application. 35 | 36 | ### API demo 37 | 38 | This guide shows how to make a call to the Contentful API, explains what the response looks like, and suggests some relevant next steps.
39 | View in [cURL](/developers/api-demo/curl/) 40 | -------------------------------------------------------------------------------- /raw_docs/python/tutorials/full-stack-getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPythonFullStack 3 | name: Getting Started with Contentful 4 | title: Getting Started with Contentful 5 | metainformation: 'This guide will walk you through your first steps using Contentful within a Rails application.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Python 10 | - Django 11 | nextsteps: 12 | - text: The Contentful Management API reference 13 | link: /developers/docs/references/content-management-api/ 14 | - text: The Contentful Delivery API reference 15 | link: /developers/docs/references/content-delivery-api/ 16 | --- 17 | 18 | This guide will walk you through your first steps using Contentful within a Django application. It will provide a step-by-step guide on how to get your first entries and start using the content you create on Contentful. 19 | 20 | ## Requirements 21 | 22 | - A [Heroku][7] account 23 | - Python 2.7+ or 3.3+ 24 | - [Git][5] installed 25 | - Basic Command Line Interface, Python and Django knowledge 26 | 27 | {: .note} 28 | **Note:** During this guide we'll assume that you're running inside a `virtualenv`. If not, append `sudo` when installing dependencies if you are using system-provided Python. 29 | 30 | Optionally: 31 | 32 | - Ruby 1.9+ for running `contentful-bootstrap` to create your own space with the provided template 33 | 34 | ## Start from a demo application 35 | 36 | First we'll start with a [demo project][2], which is a simple Django application using a basic Blog template, so that you can see it running for yourself. 37 | 38 | Run the following commands to get started. 39 | 40 | - Clone the example repository: 41 | 42 | ~~~bash 43 | git clone https://github.com/contentful/contentful_django_tutorial.git 44 | ~~~ 45 | 46 | - Navigate into the repository's directory: 47 | 48 | ~~~bash 49 | cd contentful_django_tutorial 50 | ~~~ 51 | 52 | - Install dependencies: 53 | 54 | ~~~bash 55 | pip install -r requirements.txt 56 | ~~~ 57 | 58 | - *Optional* Create your space using Contentful Bootstrap: 59 | 60 | {: .note} 61 | **Note**: If skipped, the example will use a read-only space that's already provided for you. 62 | 63 | ~~~bash 64 | bundle install 65 | bundle exec contentful_bootstrap create_space django_demo -j bootstrap/template.json 66 | ~~~ 67 | 68 | After following the steps, the tool will provide you with a Space ID and Access Token. Then run the following commands replacing the values where they correspond: 69 | 70 | ~~~bash 71 | export CTF_SPACE_ID=YOUR_SPACE_ID 72 | export CTF_DELIVERY_KEY=YOUR_ACCESS_TOKEN 73 | ~~~ 74 | 75 | It should look something like this: 76 | 77 | ![Bootstrap Tool Output](https://i.imgur.com/RkmNaes.png) 78 | 79 | This will allow the application to use your own space, allowing you to edit content and allowing you to see your application changing. You can edit content freely in our [Web App][3]. 80 | 81 | - Run the application: 82 | 83 | ~~~bash 84 | python manage.py runserver 85 | ~~~ 86 | 87 | Everything is now set up. You can view your space by opening _http://localhost:8000_ in your browser. 88 | 89 | It should look something like this: 90 | 91 | ![Django Demo Application](https://i.imgur.com/Zmum6k4.png) 92 | 93 | ### Deploy the demo to Heroku 94 | 95 | To view the demo application live in your own production environment, follow these steps: 96 | 97 | - Install the [Heroku toolbelt](https://devcenter.heroku.com/articles/heroku-cli#download-and-install) if you don't already have it. 98 | - Login to Heroku if you're not already: 99 | 100 | ~~~bash 101 | heroku login 102 | ~~~ 103 | 104 | - Create a new instance: 105 | 106 | ~~~bash 107 | heroku create 108 | ~~~ 109 | 110 | - Set Python Buildpack: 111 | 112 | ~~~bash 113 | heroku buildpacks:set heroku/python 114 | ~~~ 115 | 116 | - Deploy to Heroku: 117 | 118 | ~~~bash 119 | git push heroku master 120 | ~~~ 121 | 122 | - *Optional* Add your personalized credentials to your Heroku Instance: 123 | 124 | 1. Open [Heroku](https://dashboard.heroku.com) 125 | 2. Go to your application 126 | 3. Go to Settings 127 | 4. Press _Reveal Config Vars_ 128 | 5. Add `CTF_SPACE_ID` and `CTF_DELIVERY_KEY` with their respective values 129 | 6. Go to Resources and restart your application 130 | 131 | - Open the application in your browser: 132 | 133 | ~~~bash 134 | heroku open 135 | ~~~ 136 | 137 | ## Next Steps 138 | 139 | After this guide, you should be able to start using Contentful with your Django applications, but every project has different needs and we want to provide you with the best solutions we can. 140 | 141 | You can read about the Contentful CDA library in more detail on our [contentful.py GitHub][1] or our [Getting Started with CDA SDK tutorial][4], we also suggest taking a look at our [Contentful Django Example Application][2]. 142 | 143 | If you want to set up new spaces via the command line we also provide [Contentful Bootstrap][6]. 144 | 145 | [1]: https://github.com/contentful/contentful.py 146 | [2]: https://github.com/contentful/contentful_django_tutorial 147 | [3]: https://app.contentful.com 148 | [4]: /developers/docs/python/tutorials/getting-started-with-contentful-and-python/ 149 | [5]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git 150 | [6]: https://github.com/contentful/contentful-bootstrap.rb 151 | [7]: https://www.heroku.com 152 | -------------------------------------------------------------------------------- /raw_docs/python/tutorials/getting-started-with-contentful-and-python.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsGettingStartedPython 3 | name: Getting Started with Contentful and Python 4 | title: Getting Started with Contentful and Python 5 | metainformation: This article details how to retrieve entries using the Python CDA SDK. 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Python 10 | --- 11 | 12 | This guide will show you how to get started using our [Python SDK](https://github.com/contentful/contentful.py) to consume content. 13 | 14 | :[Getting started tutorial intro](../../_partials/getting-started-intro.md) 15 | 16 | ## Installation 17 | 18 | Install the 'contentful' client with [pip](https://pypi.python.org/pypi/pip): 19 | 20 | ~~~bash 21 | pip install contentful 22 | ~~~ 23 | 24 | {: .note} 25 | On some systems, particularly if you're not using `virtualenv` you may have to use `sudo` to install the SDK. 26 | 27 | Or add the SDK to your _requirements.txt_ file: 28 | 29 | ~~~python 30 | contentful 31 | ~~~ 32 | 33 | And run `pip install -r requirements.txt` to install the client and all dependencies. 34 | 35 | ## Setting up the Contentful client 36 | 37 | Once you have installed the package, you can use it inside your application. 38 | 39 | :[Create credentials](../../_partials/credentials.md) 40 | 41 | ~~~python 42 | import contentful 43 | 44 | client = contentful.Client('', '') 45 | ~~~ 46 | 47 | ## Getting your content 48 | 49 | Contentful separates content between entries, which contain your data and relationships with other content or images, and assets, which represent static content, like images, and are served as files. Read more in our [content model guide](/developers/docs/concepts/data-model/). 50 | 51 | ## Entries 52 | 53 | With the client created, you can now start consuming data from the CDA. 54 | 55 | For example, to request all entries in a space: 56 | 57 | ~~~python 58 | entries = client.entries() 59 | 60 | for entry in entries: 61 | print(getattr(entry, 'product_name', 'Not a product')) 62 | ~~~ 63 | 64 | :[Get all entry output](../../_partials/get-all-entry-output-python.md) 65 | 66 | Or to request a single entry: 67 | 68 | ~~~python 69 | entry_id = '' 70 | classic_car = client.entry(entry_id) 71 | ~~~ 72 | 73 | :[Get entry output](../../_partials/get-entry-output.md) 74 | 75 | You can specify any of the [query parameters accepted by the API](/developers/docs/references/content-delivery-api/#/reference/search-parameters), for example: 76 | 77 | ~~~python 78 | products_by_price = client.entries({'content_type': '', 'order': 'fields.price'}) 79 | 80 | for entry in products_by_price: 81 | print(entry.product_name) 82 | ~~~ 83 | 84 | :[Sorted entry output](../../_partials/sorted-entries-out.md) 85 | 86 | ### Using your entry as a Python object 87 | 88 | Once you have your entry, you can use it as a Python object that follows standard Python conventions: 89 | 90 | ~~~python 91 | print(product.product_name) 92 | print("it costs {0}".format(product.price)) 93 | print("I am tagged with {0}".format(' and '.join(product.tags))) 94 | ~~~ 95 | 96 | :[Python object output](../../_partials/ruby-python-object-output.md) 97 | 98 | You can form complicated queries and interaction with your entries: 99 | 100 | ~~~python 101 | products_with_many_tags = [ product for product in client.entries({'content_type': '', 'include': 2}) if product.tags.size > 2 ] 102 | for product in products_with_many_tags: 103 | print("I am tagged with {0}".format(' and '.join(product.tags))) 104 | print("My brand is: {0}".format(product.brand.company_name)) 105 | ~~~ 106 | 107 | :[Python object complex output](../../_partials/ruby-python-object-complex-output.md) 108 | 109 | In this example you added the `include: 2` parameter, which allows the API to resolve [links](/developers/docs/concepts/links/) to other related entries. 110 | 111 | ## Using assets 112 | 113 | You query assets in a similar way to entries, but the CDA offers more specific features, [such as filtering by the type of file](/developers/docs/references/content-delivery-api/#/reference/search-parameters/filtering-assets-by-mime-type/). You can also use our [Images API](/developers/docs/references/images-api/), that allows you to manipulate images as you retrieve them. 114 | 115 | To query a single asset: 116 | 117 | ~~~python 118 | client.asset('').url() 119 | ~~~ 120 | 121 | :[Get single asset](../../_partials/get-asset-output.md) 122 | 123 | To query all assets in a space: 124 | 125 | ~~~python 126 | assets = client.assets() 127 | 128 | for asset in assets: 129 | print(asset.url()) 130 | ~~~ 131 | 132 | :[Get all assets](../../_partials/get-all-asset-output.md) 133 | -------------------------------------------------------------------------------- /raw_docs/references/content-delivery-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: api_reference 3 | page: :docsContentfulCda 4 | --- 5 | -------------------------------------------------------------------------------- /raw_docs/references/content-management-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: api_reference 3 | page: :docsContentfulCma 4 | --- 5 | -------------------------------------------------------------------------------- /raw_docs/references/content-preview-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: api_reference 3 | page: :docsContentPreviewApi 4 | --- 5 | -------------------------------------------------------------------------------- /raw_docs/references/errors.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsErrors 3 | name: Errors 4 | title: Errors 5 | metainformation: 'When something goes wrong with an API request, our server generates an error. The error message contains an appropriate HTTP status code in the header and a JSON response in the body.' 6 | slug: null 7 | tags: 8 | - Reference 9 | - Errors 10 | nextsteps: 11 | - text: Details of our HTTP transport 12 | link: /developers/docs/references/http-details/ 13 | --- 14 | 15 | When something goes wrong with an API request, our server generates an error. The error message contains an appropriate HTTP status code in the header and a JSON response in the body. 16 | 17 | Errors share the same common attributes as other API resources. They have a `sys` property, where `sys.type` is always `"Error"` and a `sys.id` that identifies the exact error code (see table below) that occurred. They always have a `message` property which will be a short description of what went wrong. 18 | 19 | Errors resulting from bad input (such as `ValidationFailed` errors) contain a `details` property. This property is structured data that indicates more precisely what was wrong with the input. 20 | 21 | ## Error types 22 | 23 | {:.table} 24 | HTTP status code |Error code |Description 25 | -------------------|-----------------|-------------------------------------- 26 | `400 Bad Request` |`BadRequestError`|The request was malformed or missing a required parameter. 27 | `400 Invalid query`|`InvalidQueryError`|The request contained invalid or unknown query parameters. 28 | `401 Unauthorized` |`AccessTokenInvalidError`|The authorization token was invalid. 29 | `403 Access Denied`|`AccessDeniedError`|The user tried to access a resource they do not have access to. This could include a missing role. 30 | `404 Not Found`|`NotFoundError`|The requested resource or endpoint could not be found. 31 | `409 Version Mismatch`|`VersionMismatchError`|This error occurs when you're trying to update an existing asset, entry or content type, and you didn't specify the current version of the object or specify an outdated version. 32 | `422 Validation Error`|`ValidationFailedError`|The request payload was valid JSON, but something was wrong with the data. The error details should provide more specific information about the error. 33 | `422 Unknown Field`|`ValidationFailedError`|The triggered query references an invalid field. 34 | `422 Invalid Entry`| `InvalidEntryError`|The entered value is invalid. 35 | `429 Rate Limit Exceeded Error`|`RateLimitExceededError`|The user sent too many requests per second. 36 | `500 Server Error`|`ServerError`|Something went wrong on the Contentful servers. 37 | `502 Hibernated`|`AccessDeniedError`|The space has not been used for a long time and was hibernated. It will become active again if the user begins using it. 38 | -------------------------------------------------------------------------------- /raw_docs/references/http-details.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsHttpDetails 3 | name: HTTP details 4 | title: HTTP details 5 | metainformation: 'The Content Delivery API and Preview API are fully available via SSL. You should request JSON data and assets through a secure transport.' 6 | slug: null 7 | tags: 8 | - Reference 9 | - Network 10 | nextsteps: 11 | - text: Details of our error messages 12 | link: /developers/docs/references/errors/ 13 | --- 14 | 15 | ## Security 16 | 17 | The Content Delivery API and Preview API are fully available via SSL. You should request JSON data and assets through a secure transport. 18 | 19 | Our client libraries enable SSL by default. Unless there is a reason to disable SSL you should leave it enabled to ensure maximum privacy for clients. 20 | 21 | The Content Management API is only available via SSL, and you must make all requests using the _https_ protocol. 22 | 23 | Using SSL ensures that the content and access tokens of a space remain secure and that potential eavesdroppers cannot intercept your data. 24 | 25 | ## Cross-origin resource sharing 26 | 27 | [CORS (Cross-origin resource sharing)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) allows JavaScript web apps to make HTTP requests to other domains. This is important for third party web apps using Contentful, as without CORS, a JavaScript app hosted on _example.com_ couldn't access our APIs because they're hosted on _contentful.com_ which is a different domain. 28 | 29 | CORS is [supported by all modern browsers](http://caniuse.com/cors). Read more about using CORS in this [tutorial](https://www.html5rocks.com/en/tutorials/cors/). 30 | 31 | To allow JavaScript applications running inside browsers to interact with our APIs, we set the following HTTP response headers: 32 | 33 | - `Access-Control-Allow-Origin`: `*`, or all. 34 | - `Access-Control-Allow-Headers`: A long list of common headers, if you want to know more, [read the reference below](#allow-headers). 35 | - `Access-Control-Allow-Methods`: HTTP verbs. Typically the request type, plus `OPTIONS` and `HEAD`. 36 | - `Access-Control-Max-Age`: This varies depending on endpoint, but is a high value to avoid preflight requests. 37 | 38 | {: .note} 39 | **Note:** Allowing all origins is safe because all requests must include an access token in the query string or as header. The token will never be sent implicitly by a cookie. You can only issue destructive requests against the HTTPS endpoint. 40 | 41 | ## ETag/If-None-Match 42 | 43 | Our APIs support conditional `GET` requests via [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) and `If-None-Match` headers. 44 | 45 | Every API response (both single resources and searches) includes an `ETag` header. The `ETag` header changes depending on the content of the response. If a resource is updated or a search result changes, the ETag also changes. 46 | 47 | To avoid unnecessary transfers you can set the `If-None-Match` header of an API request to the `ETag` previously received for the same API request. 48 | 49 | If the content hasn't changed in the meantime the API will respond with a 304 Not Modified response. This makes a difference for large responses and especially binary files. 50 | 51 | ## GZip compression 52 | 53 | All API endpoints support GZip compression to save bandwidth. Please take into account that enabling compression will put more load on your clients' processors. 54 | 55 | ## JSON format details 56 | 57 | Contentful represents resources as [JSON](http://json.org), encoded in UTF-8. Contentful represents dates and times as [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)-encoded string, with system-generated dates represented as UTC. 58 | 59 | ### Allow headers reference 60 | 61 | Contentful sets the following headers: 62 | 63 | `Accept`, `Accept-Language`, `Authorization`, `Cache-Control`, `Content-Length`, `Content-Range`, `Content-Type`, `DNT`, `Destination`, `Expires`, `If-Match`, `If-Modified-Since`, `If-None-Match`, `Keep-Alive`, `Last-Modified`, `Origin`, `Pragma`, `Range`, `User-Agent`, `X-Http-Method-Override`, `X-Mx-ReqToken`, `X-Requested-With`, `X-Contentful-Version`, `X-Contentful-Content-Type`, `X-Contentful-Organization`, `X-Contentful-Skip-Transformation`, `X-Contentful-User-Agent` 64 | -------------------------------------------------------------------------------- /raw_docs/references/images-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: api_reference 3 | page: :docsContentfulImagesApi 4 | --- 5 | 6 | -------------------------------------------------------------------------------- /raw_docs/ruby/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsPlatformsRuby 3 | name: Ruby 4 | title: Using Contentful with Ruby 5 | metainformation: 'Our Ruby SDK gives you access to the Contentful APIs and their features.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Ruby 10 | nextsteps: null 11 | --- 12 | 13 | - [SDKs](#sdks) 14 | - [Tutorials](#tutorials) 15 | - [Tools](#tools-and-integrations) 16 | - [Example apps](#example-apps) 17 | 18 | ## SDKs 19 | 20 | Our SDKs give you access to our [APIs](/developers/docs/concepts/apis/) and their features. 21 | 22 | ### Content Delivery API SDK 23 | 24 | This SDK interacts with the Content Delivery API, a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location using our global CDN.
25 | [View on GitHub](https://github.com/contentful/contentful.rb)
26 | [API reference](http://www.rubydoc.info/gems/contentful/) 27 | 28 | ### Content Management API SDK 29 | 30 | This SDK interacts with the Content Management API, and allows you to create, edit, manage, and publish content. The API also offers tools for managing editorial teams and cooperation.
31 | [View on GitHub](https://github.com/contentful/contentful-management.rb)
32 | [API reference](http://www.rubydoc.info/gems/contentful-management/) 33 | 34 | ## Tutorials 35 | 36 | ### Create and deploy a Rails application using Contentful 37 | 38 | [This guide](/developers/docs/ruby/tutorials/full-stack-getting-started/) explains how to use Contentful with a Ruby on Rails application. 39 | 40 | ### API demo 41 | 42 | [This guide](/developers/api-demo/ruby/) is the perfect starting point to learn how to make calls to Contentful APIs, explains what responses look like, and suggest next steps. 43 | 44 | ### Getting started with the Content Delivery API SDK and Ruby 45 | 46 | [This tutorial](/developers/docs/ruby/tutorials/getting-started-with-contentful-and-ruby/) will walk you through the first steps using the Content Delivery API with a Ruby application. 47 | 48 | ### Create your own Rails application using Contentful 49 | 50 | [This guide](/developers/docs/ruby/tutorials/create-your-own-rails-app/) shows you how to create a Ruby on Rails application from scratch and integrate it with Contentful. 51 | 52 | ### Getting started with the Content Management API SDK and Ruby 53 | 54 | [This tutorial](/developers/docs/ruby/tutorials/getting-started-with-contentful-cma-and-ruby/) will walk you through the first steps using the Contentful Management API with a Ruby application. 55 | 56 | ## Tools and integrations 57 | 58 | ### Contentful bootstrap command line tool 59 | 60 | [This tool](https://github.com/contentful/contentful-bootstrap.rb) will help you create, populate and manage your Contentful spaces from the command line. [Read this tutorial](/developers/docs/ruby/tutorials/using-contentful-bootstrap-for-keeping-up-with-your-spaces/) to learn more about how to use the tool. 61 | 62 | ### Contentful webhook listener 63 | 64 | A simple HTTP webserver for listening to API webhooks that you can override to suit your own behaviors.
65 | [View on GitHub](https://github.com/contentful/contentful-webhook-listener.rb) 66 | 67 | ### Rails integration 68 | 69 | A collection of useful gems that make it easier to integrate Contentful into a Rails app. [Read this blog post](/blog/2016/07/21/contentful-on-rails/) to find out how to use them in your applications.
70 | [View Contentful Rails on GitHub](https://github.com/contentful/contentful_rails)
71 | [View Contentful Model on GitHub](https://github.com/contentful/contentful_model) 72 | 73 | ## Example apps 74 | 75 | ### Rails product demo 76 | 77 | A Rails application that connects to a Contentful product catalogue example space.
78 | [View on GitHub](https://github.com/contentful/contentful_rails_tutorial) 79 | 80 | ### Sinatra product demo 81 | 82 | A Sinatra application that connects to a Contentful product catalogue example space.
83 | [View on GitHub](https://github.com/contentful/contentful_sinatra_tutorial) 84 | -------------------------------------------------------------------------------- /raw_docs/ruby/tutorials/automated-rebuild-and-deploy-with-circleci-and-webhooks.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsRubyAutomatedRebuild 3 | name: Automated rebuild and deploy with CircleCI and Webhooks 4 | title: Automated rebuild and deploy with CircleCI and Webhooks 5 | metainformation: 'This guide will show you how you can automate Contentful deployments using Webhooks and CircleCI.' 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Ruby 10 | - Workflow 11 | nextsteps: null 12 | --- 13 | 14 | If you're running our [Jekyll](https://github.com/contentful/jekyll-contentful-data-import) or [Middleman](https://github.com/contentful/contentful_middleman) integrations, 15 | you might be wondering how to automate your site building and publishing process. 16 | 17 | Here we'll discuss how you can automate this process using [Contentful Webhooks](/developers/docs/concepts/webhooks/) 18 | and CircleCI API. 19 | 20 | > Everything we'll discuss here is for the case of using a public [GitHub](https://github.com) repository, 21 | > using [CircleCI.com](https://circleci.com) and deploying on [GitHub Pages](https://pages.github.com/). 22 | > This setup can be replicated on a private repository with CircleCI.com integration 23 | > enabled. Just make sure to change the URLs in the examples appropriately. 24 | 25 | ## Requirements 26 | 27 | * A Contentful Space and API Key 28 | * Your Jekyll or Middleman application with Contentful hosted on GitHub 29 | * CircleCI integration enabled on your repository 30 | * GitHub Pages repository for deploying your site 31 | 32 | We'll assume that you know how to set up your Jekyll or Middleman projects. 33 | If not, you can check the basic example applications here: 34 | 35 | * [Middleman Examples](https://github.com/contentful/contentful_middleman_examples) 36 | * [Jekyll Examples](https://github.com/contentful/contentful_jekyll_examples) 37 | 38 | ## Setup your Contentful webhooks to trigger Circle builds 39 | 40 | * Generate your CircleCI Token [here](https://circleci.com/docs/api/#getting-started). 41 | * On the Contentful webhook admin page, create a webhook with (replacing the upper-cased values): 42 | 43 | ~~~ 44 | Name: CircleCI 45 | URL: https://circleci.com/api/v1/project/YOUR_COMPANY/YOUR_PROJECT/tree/YOUR_BRANCH?circle-token=YOUR_CIRCLECI_TOKEN 46 | On: Entry -> publish, unpublish 47 | ~~~ 48 | 49 | ## Create automated build script 50 | 51 | Here the setups differ a bit, but the structure is pretty similar. 52 | 53 | Create a file called `automated_build.sh` and include the following: 54 | 55 | * Middleman: 56 | 57 | ~~~bash 58 | # Copy static site 59 | CWD=`pwd` 60 | 61 | # Clone Pages repository 62 | cd /tmp 63 | git clone YOUR_PAGES_REPO build 64 | 65 | # cd build && git checkout -b YOUR_BRANCH origin/YOUR_BRANCH # If not using master 66 | 67 | # Trigger Middleman rebuild 68 | cd $CWD 69 | bundle exec middleman contentful --rebuild 70 | 71 | # Push newly built repository 72 | cp -r $CWD/build/* /tmp/build 73 | 74 | cd /tmp/build 75 | 76 | git config --global user.email "YOUR_EMAIL@example.com" 77 | git config --global user.name "YOUR NAME" 78 | 79 | git add . 80 | git commit -m "Automated Rebuild" 81 | git push -f origin YOUR_PAGES_BRANCH 82 | ~~~ 83 | 84 | * Jekyll: 85 | 86 | ~~~bash 87 | # Copy static site 88 | CWD=`pwd` 89 | 90 | # Clone Pages repository 91 | cd /tmp 92 | git clone YOUR_PAGES_REPO build 93 | # cd build && git checkout -b YOUR_BRANCH origin/YOUR_BRANCH # If not using master 94 | 95 | # Trigger Jekyll rebuild 96 | cd $CWD 97 | bundle exec jekyll contentful 98 | bundle exec jekyll build 99 | 100 | # Push newly built repository 101 | cp -r $CWD/_build/* /tmp/build # or $CWD/_site 102 | 103 | cd /tmp/build 104 | 105 | git config --global user.email "YOUR_EMAIL@example.com" 106 | git config --global user.name "YOUR NAME" 107 | 108 | git add . 109 | git commit -m "Automated Rebuild" 110 | git push -f origin YOUR_PAGES_BRANCH 111 | ~~~ 112 | 113 | > Make sure your CircleCI machine has access to your Pages repository. 114 | > This requires adding SSH Keys to the CircleCI machine and configuring them on GitHub. 115 | 116 | ## Setup Circle build steps 117 | 118 | Now we have everything we need to create our automated builds, only thing missing 119 | is to add a build step in Circle to run our build. 120 | 121 | In `circle.yml`, add the following: 122 | 123 | ~~~yml 124 | machine: 125 | ruby: 126 | version: 2.3.1 127 | dependencies: 128 | pre: 129 | - gem install bundler 130 | checkout: 131 | post: 132 | - bundle install 133 | - bash automated_build.sh 134 | ~~~ 135 | 136 | ## We're done! Automation! 137 | 138 | You can now start testing your automatically rebuilt site. With this setup, any change 139 | pushed on your repository or any publish/unpublish action on Contentful will trigger 140 | an automated rebuild of your site. 141 | -------------------------------------------------------------------------------- /raw_docs/ruby/tutorials/getting-started-with-contentful-and-ruby.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsGettingStartedRuby 3 | name: Getting Started with Contentful and Ruby 4 | title: Getting Started with Contentful and Ruby 5 | metainformation: This article details how to retrieve entries using the Ruby CDA SDK. 6 | slug: null 7 | tags: 8 | - SDKs 9 | - Ruby 10 | nextsteps: 11 | - text: Using the Contentful Management API with Ruby 12 | link: /developers/docs/ruby/tutorials/getting-started-with-contentful-cma-and-ruby/ 13 | - text: Create and deploy a Ruby application with Contentful 14 | link: /developers/docs/ruby/tutorials/full-stack-getting-started/ 15 | --- 16 | 17 | This guide will show you how to get started using our [Ruby SDK](https://github.com/contentful/contentful.rb) to consume content. 18 | 19 | :[Getting started tutorial intro](../../_partials/getting-started-intro.md) 20 | 21 | ## Installation 22 | 23 | First, install the 'contentful' gem, with the terminal: 24 | 25 | ~~~bash 26 | gem install contentful 27 | ~~~ 28 | 29 | Or you can add it to your _Gemfile_: 30 | 31 | ~~~ruby 32 | gem 'contentful' 33 | ~~~ 34 | 35 | And run `bundle install` to install the gem and all its dependencies. 36 | 37 | ## Setting up the Contentful client 38 | 39 | Once you have installed the gem, you can start using it inside your application. 40 | 41 | :[Create credentials](../../_partials/credentials.md) 42 | 43 | ~~~ruby 44 | require 'contentful' 45 | 46 | client = Contentful::Client.new( 47 | space: '', 48 | access_token: '', 49 | dynamic_entries: :auto 50 | ) 51 | ~~~ 52 | 53 | {: .note} 54 | **Note**: The `dynamic_entries: :auto` attribute will automatically map the fields in your entries to methods, so that you can use them directly as objects. 55 | 56 | ## Getting your content 57 | 58 | Contentful separates content between entries, which contain your data and relationships with other content or images, and assets, which represent static content, like images, and are served as files. Read more in our [content model guide](/developers/docs/concepts/data-model/). 59 | 60 | ### Entries 61 | 62 | With the client created, you can now start consuming data from the API. 63 | 64 | For example, to request all entries in a space from the API: 65 | 66 | ~~~ruby 67 | entries = client.entries 68 | 69 | entries.each do |entry| 70 | if entry.fields[:productName] 71 | puts entry.fields[:productName] 72 | end 73 | end 74 | ~~~ 75 | 76 | :[Get all entry output](../../_partials/get-all-entry-output.md) 77 | 78 | Or to request a single entry: 79 | 80 | ~~~ruby 81 | entry_id = '' 82 | classic_car = client.entry(entry_id) 83 | 84 | puts classic_car.fields[:productName] 85 | ~~~ 86 | 87 | :[Get entry output](../../_partials/get-entry-output.md) 88 | 89 | You can specify any of the [query parameters accepted by the API](/developers/docs/references/content-delivery-api/#/reference/search-parameters), for example: 90 | 91 | ~~~ruby 92 | products_by_price = client.entries(content_type: '', order: 'fields.price') 93 | 94 | products_by_price.each do |entry| 95 | if entry.fields[:productName] 96 | puts entry.fields[:productName] 97 | end 98 | end 99 | ~~~ 100 | 101 | :[Sorted entry output](../../_partials/sorted-entries-out.md) 102 | 103 | ### Using your entry as a Ruby object 104 | 105 | Once you have your entry, you can use it as a Ruby object that follows standard Ruby conventions: 106 | 107 | ~~~ruby 108 | puts product.product_name 109 | puts "it costs #{product.price}" 110 | puts "I am tagged with #{product.tags.join(' and ')}" 111 | ~~~ 112 | 113 | :[Ruby object output](../../_partials/ruby-python-object-output.md) 114 | 115 | You can form complicated queries and interactions with your entries: 116 | 117 | ~~~ruby 118 | products_with_many_tags = client.entries(content_type: '', include: 2).select { |product| product.tags.size > 2 } 119 | products_with_many_tags.each do |product| 120 | puts "I am tagged with #{product.tags.join(' and ')}" 121 | puts "My brand is #{product.brand.company_name}" 122 | end 123 | ~~~ 124 | 125 | :[Ruby object complex output](../../_partials/ruby-python-object-complex-output.md) 126 | 127 | In this example you added the `include: 2` parameter, which allows the API to resolve [links](/developers/docs/concepts/links/) to other related entries. 128 | 129 | ## Using assets 130 | 131 | You query assets in a similar way to entries, but the CDA offers more specific features, [such as filtering by the type of file](/developers/docs/references/content-delivery-api/#/reference/search-parameters/filtering-assets-by-mime-type/). You can also use our [Images API](/developers/docs/references/images-api/), that allows you to manipulate images as you retrieve them. 132 | 133 | To query for a single asset: 134 | 135 | ~~~ruby 136 | asset_file = client.asset('').image_url 137 | puts asset_file 138 | ~~~ 139 | 140 | :[Get single asset](../../_partials/get-asset-output.md) 141 | 142 | To query all assets in a space: 143 | 144 | ~~~ruby 145 | assets = client.assets 146 | 147 | assets.each do |asset| 148 | puts asset.image_url 149 | end 150 | ~~~ 151 | 152 | :[Get all assets](../../_partials/get-all-asset-output.md) 153 | -------------------------------------------------------------------------------- /raw_docs/tools/applications.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsToolsApplications 3 | name: Applications 4 | title: Applications 5 | metainformation: 'These applications help you use Contentful.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - Extending 10 | nextsteps: null 11 | --- 12 | 13 | ## macOS media uploader 14 | 15 | Upload images to Contentful with this macOS tool. 16 | 17 | ![macOS media uploader](https://images.contentful.com/tz3n7fnw4ujc/4kQwOdAZksQi8s6yuM8aq2/d3c99346b5ffc5b586f324ead59dd3e9/macos-media-uploader.png) 18 | 19 | [View on GitHub](https://github.com/contentful/image-uploader-app) 20 | 21 | ## Third party tools 22 | 23 | Apart from official tools and libraries, there are others developed by our community, which you can find at [awesome-contentful](https://github.com/contentful-labs/awesome-contentful). These include languages and platforms such as Python and .NET. 24 | -------------------------------------------------------------------------------- /raw_docs/tools/extensions.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsToolsExtensions 3 | name: Extensions 4 | title: Extensions 5 | metainformation: 'These extensions add extra functionality to Contentful, you can find detailed instructions in each individual GitHub repository.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - Extending 10 | nextsteps: null 11 | --- 12 | 13 | These extensions add extra functionality to Contentful, you can find detailed instructions in each individual GitHub repository. 14 | 15 | ## Contentful Scheduler 16 | 17 | This Ruby gem provides automated scheduled entry publishing using our [webhooks API](/developers/docs/references/content-management-api/#/reference/webhooks). 18 | 19 | [View on GitHub](https://github.com/contentful/contentful-scheduler.rb) 20 | 21 | ## Contentful Moderator 22 | 23 | This Ruby gem provides moderated authoring workflows for your entries. 24 | 25 | [View on GitHub](https://github.com/contentful/contentful-moderator.rb) 26 | 27 | ## Contentful Social 28 | 29 | This Ruby gem provides the ability to post directly to social networks when publishing your entries. 30 | 31 | [View on GitHub](https://github.com/contentful/contentful-social.rb) 32 | -------------------------------------------------------------------------------- /raw_docs/tools/spacemanagement.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsToolsSpaceManagement 3 | name: Space management 4 | title: Space management tools 5 | metainformation: 'These tools will help you import and manage entries in your spaces.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - Extending 10 | nextsteps: null 11 | --- 12 | 13 | These tools will help you import and manage entries in your spaces. 14 | 15 | ## Import and Export Tools 16 | 17 | The export tool allows you to export all content, including content types, assets and webhooks from a space. The import tool allows you import all the content into a new space. _These tools replace the space sync tool if you previously used that_. 18 | 19 | Import Tool - [View on GitHub](https://github.com/contentful/contentful-import) 20 | Export Tool - [View on GitHub](https://github.com/contentful/contentful-export) 21 | 22 | For further information on recommended steps for using these tools, read [our guide to maintaining multiple environments with Contentful](/developers/docs/concepts/multiple-environments/). 23 | 24 | ## Data import / Bootstrap 25 | 26 | You can import data from other systems into Contentful using our [contentful-importer.rb](https://github.com/contentful/contentful-importer.rb) gem. 27 | 28 | The importer uses a flexible input format that you can write your own exporters for, we provide exporters for: 29 | 30 | - [Drupal](https://github.com/contentful/drupal-exporter.rb) 31 | - [SQL databases](https://github.com/contentful/database-exporter.rb) 32 | - [WordPress](https://github.com/contentful/wordpress-exporter.rb) 33 | 34 | [Read this tutorial](/developers/docs/tutorials/general/import-and-export/) to learn how to export content from the systems listed above and import it into your Contentful spaces. 35 | 36 | ## Contentful link cleaner 37 | 38 | If you delete an entry linked to another entry, then you will have loose references to non-existent entries. This tool cleans up these links. 39 | 40 | [View on GitHub](https://github.com/contentful/contentful-link-cleaner) 41 | 42 | ## Contentful bootstrap 43 | 44 | This Ruby gem gets you started using Contentful with one command, creating the spaces, entries and more with one command. [Read this tutorial](/developers/docs/ruby/tutorials/using-contentful-bootstrap-for-keeping-up-with-your-spaces/) for more details. 45 | 46 | [View on GitHub](https://github.com/contentful/contentful-bootstrap.rb) 47 | -------------------------------------------------------------------------------- /raw_docs/tools/staticsitegenerators.md: -------------------------------------------------------------------------------- 1 | --- 2 | page: :docsToolsStaticSiteGenerators 3 | name: Static site generators 4 | title: Static site generators 5 | metainformation: 'We love static sites and have plugins to support three of our favorites.' 6 | slug: null 7 | tags: 8 | - Tools 9 | - Extending 10 | nextsteps: null 11 | --- 12 | 13 | We love static sites and have plugins to support three of our favorites. 14 | 15 | ## Middleman 16 | 17 | [Middleman](https://middlemanapp.com/) is a Ruby based static site generator, and this plugin will help you manage your Contentful content. 18 | 19 | [View on GitHub](https://github.com/contentful/contentful_middleman) 20 | 21 | [View examples](https://github.com/contentful/contentful_middleman_examples) 22 | 23 | ## Jekyll 24 | 25 | [Jekyll](https://jekyllrb.com/) is a Ruby based static site generator, and this plugin pulls content from Contentful. 26 | 27 | [View on GitHub](https://github.com/contentful/jekyll-contentful-data-import) 28 | 29 | [View examples](https://github.com/contentful/contentful_jekyll_examples) 30 | 31 | ## Metalsmith 32 | 33 | [Metalsmith](http://www.metalsmith.io/) is a JavaScript based static site generator, and this plugin fetches and renders data from Contentful. 34 | 35 | [View on GitHub](https://github.com/contentful-labs/contentful-metalsmith) 36 | 37 | [View examples](https://github.com/contentful-labs/contentful-metalsmith-example) 38 | 39 | ## Tutorials 40 | 41 | ### Automated rebuild and deployment with CircleCI and Webhooks 42 | 43 | [This tutorial](/developers/docs/ruby/tutorials/automated-rebuild-and-deploy-with-circleci-and-webhooks/) shows you how to setup and automatically deploy static sites using Jekyll or Middleman with CircleCI. 44 | 45 | ## Other tools 46 | 47 | We have more tools available to extend the functionality of Contentful. We have tested these tools, but they are not officially supported by Contentful. 48 | 49 | ### Roots 50 | 51 | [Roots](https://roots.cx/) is a JavaScript based static site generator, and this plugin helps you manage content from Contentful. 52 | 53 | [View on GitHub](https://github.com/carrot/roots-contentful) 54 | 55 | [View examples](/blog/2015/04/28/webinar-contentful-roots-static-sites/) 56 | 57 | ### Simple static site generator 58 | 59 | A CLI tool to generate a site from templates and data in a Contentful space. 60 | 61 | [View on GitHub](https://github.com/Textalk/contentful-static) 62 | 63 | ### AWS Lambda 64 | 65 | An example project for building a static site using AWS Lambda. 66 | 67 | [View example](https://github.com/contentful-labs/contentful-aws-lambda-static) 68 | --------------------------------------------------------------------------------