Permalink
Browse files

MINOR oEmbed documentation

  • Loading branch information...
1 parent c0b3512 commit 86bdd167ccb9636da80a1ff9e0be84790005cd69 @chillu chillu committed Jun 8, 2012
Showing with 32 additions and 5 deletions.
  1. +11 −5 docs/en/reference/image.md
  2. +21 −0 docs/en/topics/rich-text-editing.md
View
@@ -2,15 +2,21 @@
## Introduction
-Represents an image object, inheriting all base functionality from the [file](api:file) class with extra functionality
-including resizing.
+Represents an image object through the `[api:Image]` class, inheriting all base functionality from the `[api:File]` class with extra functionality including resizing.
## Usage
-### Form Fields
+### Managing images through form fields
-* `[api:Image]`. Designed to provide a complex image uploader for the CMS.
-* `[api:FileField]` and `[api:UploadField]`. Allows upload of images (through limiting file extensions with `setAllowedExtensions()`).
+Images can be uploaded like any other file, through `[api:FileField]`.
+More advanced usage is possible through `[api:UploadField]`,
+which provides thumbnails, a detail view of the image properties,
+and management of relationships to other DataObject instances.
+Allows upload of images through limiting file extensions with `setAllowedExtensions()`.
+
+### Inserting images into the WYSIWYG editor
+
+See [Topics: Rich Text Editing](/topics/rich-text-editing).
### Resizing Images in PHP
@@ -43,6 +43,27 @@ Example: Remove some buttons for more advanced formatting
// File: mysite/_config.php
HtmlEditorConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr');
+## Image and Media Insertion
+
+The `[api:HtmlEditorField]` API also handles inserting images and media
+files into the managed HTML content. It can be used both for referencing
+files on the webserver filesystem (through the `[api:File]` and `[api:Image]` APIs),
+as well as hotlinking files from the web.
+
+## oEmbed: Embedding media through external services
+
+The ["oEmbed" standard](http://www.oembed.com/) is implemented by many media services
+around the web, allowing easy representation of files just by referencing a website URL.
+For example, a content author can insert a playable youtube video just by knowing
+its URL, as opposed to dealing with manual HTML code.
+
+oEmbed powers the "Insert from web" feature available through `[api:HtmlEditorField]`.
+Internally, it makes HTTP queries to a list of external services
+if it finds a matching URL. These services are described in the `Oembed.providers` configuration.
+Since these requests are performed on page rendering, they typically have a long cache time (multiple days). To refresh a cache, append `?flush=1` to a URL.
+
+To disable oEmbed usage, set the `Oembed.enabled` configuration property to "false".
+
## Recipes
### Customizing the "Insert" panels

0 comments on commit 86bdd16

Please sign in to comment.