About the Media editor

The Media editor allows the content administrator to select and link to media assets stored in a content repository.

The media editor consists of an Experience Manager editor and a lightweight Web application that enables the content administrator to browse and navigate across a set of media assets in order to more easily find specific files.

The default Discover Electronics reference application stores media directly in the Endeca Configuration Repository and uses a built-in asset browser to present these assets to the content administrator. You may also initialize an MDEX Engine to index media asset metadata and URIs as records, making them available for Guided Navigation in an enhanced Media Browser.

Note

The configuration repository provides an acceptable store for media files when used for preview purposes in an authoring environment, but Oracle recommends serving media assets from a media or content delivery server for production environments.

The default asset browser for the Media editor can only be configured to browse media assets in the Endeca Configuration Repository. If you are using another system for managing media assets, you must stand up a corresponding media MDEX Engine and enable the Media Browser in the editor configuration file.

A Media editor allows a content administrator to link media into a cartridge. It can be combined with the Link Builder in order to create images that link to destinations in your application, such as those used in site banners.

To add a Media editor to a template:

  1. In typeInfo, insert an Item property named media as in the following example: 

    "typeInfo": {
        "media": {"@propertyType": "Item"}
    }

  2. In defaultContentItem, insert a media element with a of class com.endeca.infront.cartridge.model.MediaObject, as in the following example: 

    "defaultContentItem": {
        "media": {"@class": "com.endeca.infront.cartridge.model.MediaObject"}
    },

  3. Insert a corresponding editors/MediaEditor element within editors/DefaultEditorPanel.

  4. Specify the propertyName attribute and any additional label attributes for the editor: 

    {
                "editor": "editors/MediaEditor",
                "propertyName": "media",
                "label": "${property.media.label}",
                "enabled": true
            },

The following shows an example of a template that includes a media editor as part of a media banner cartridge: 

{
    "@description": "${template.description}",
    "@group": "MainContent",
    "ecr:createDate": "2016-09-12T17:33:57.427+05:30",
    "@thumbnailUrl": "thumbnail.png",
    "ecr:type": "template",
    "defaultContentItem": {
        "@name": "Media Banner",
        "imageAlt": "",
        "link": {"@class": "com.endeca.infront.cartridge.model.LinkBuilder"},
        "media": {"@class": "com.endeca.infront.cartridge.model.MediaObject"}
    },
    "editorPanel": {
        "editor": "editors/DefaultEditorPanel",
        "children": [
            {
                "editor": "GroupLabel",
                "label": "${group.media.label}"
            },
            {
                "editor": "editors/MediaEditor",
                "propertyName": "media",
                "label": "${property.media.label}",
                "enabled": true
            },
           <!-- additional elements omitted from this example -->
        ]
    },
    "typeInfo": {
        "imageAlt": {"@propertyType": "String"},
        "link": {"@propertyType": "Item"},
        "media": {"@propertyType": "Item"}
    }
}

In order to use the Media editor, if you are using the Endeca Configuration Repository as your media store, you must upload any media files to the repository. If you are using an external digital asset management system with a corresponding MDEX Engine, the matching application must be configured and running and the Media Browser must be enabled.

Related links

You can specify allowable media formats in the editor JSON file. You can also enable or disable the Media Browser, and specify the MDEX Engine that it should query for media records.

The Discover Electronics reference application uses the Endeca Configuration Repository to store media and accesses these resources through a default asset browser, rather than relying on the Media Browser and an accompanying media MDEX Engine.

Below is the configuration for the Media editor in the editor JSON file, located at <app dir>\config\import\editors\MediaEditor\_.json: 

{
   "ecr:type":"editor",
   "config":{
      "useMediaBrowser":"false",
      "mediaRoots":{
         "default":"http://EXAMPLE:8006/ifcr/sites/Discover/media/",
         "MediaSource":"http://EXAMPLE:8006/discover-authoring/images/"
      },
      "mdexPort":"17000",
      "mdexHost":"EXAMPLE",
      "videoFormats":"mp4|ogg|ogv|webm",
      "imageFormats":"jpg|png|gif",
      "mediaURI":"/ifcr/sites/Discover/media/"
   }
}

This sets the following properties across all instances of the media editor in the application:

Property

Description

useMediaBrowser

This property enables or disables the media browser. By default, it is set to false.

mediaRoots

This property specifies the absolute URLs to available media repositories. It includes a nested default property that points to the Endeca Configuration Repository, and an additional property for each repository indexed by the media MDEX Engine. For more information, see "About resolving media paths in content items."

default

The absolute URL to the Endeca Configuration Repository, used by the default asset browser. The specified host and port should match those used by Workbench.

content source (mediaSource)

An absolute URL to a media content source. In the reference data application, records are assigned a media.repository_id property with a value of mediaSource.

Your own data ingest process may assign different values for media served from varying locations. In this case, each media.repository_id value should have a corresponding element in the editor JSON file that identifies the URL for that content source.

mdexPort

For applications using the Media Browser, this is the hostname or IP address of the media MDEX Engine server.

mdexHost

For applications using the Media Browser, this is the port on which the specified media MDEX Engine server listens.

videoFormats

A pipe-delineated list of valid video formats. Videos do not display in either the default asset browser or Media Browser. The Discover Electronics reference application is configured to use mp4, ogg, ogv, and webm, formats.

Note that Internet Explorer only supports the mp4 format. If you attempt to view an ogg, ogv, or webm format video in the Media Editor using Internet Explorer, an invalid source error message appears.

imageFormats

A pipe-delineated list of valid image formats. Any images not matching a listed format do not display in either the default asset browser or Media Browser. The Discover Electronics reference application is configured to use jpg, png, and gif formats.

mediaURI

The location of the media node within the Endeca Configuration Repository. This is only used by the default asset browser.

Note the following:

The JSON examples of video and image formats in this guide include only those that are supported by the renderers for the Discover Electronics reference application. If you wish to extend this list for your own application, ensure that your cartridge renderers can handle additional formats, and that your application includes logic for displaying them. If you want to display a video on your site, the renderer needs to let the browser determine the size.

The ability to store media in the Endeca Configuration Repository has been deprecated in Oracle Commerce 11.3. The Endeca Configuration Repository is not intended for serving any media in a production environment. If you store media in the Endeca Configuration Repository, the Media browser might have problems displaying videos. For example the video might display without controls or as a static image. The appearance of videos is affected by many factors, such as the browser that you are using and the operating system.

The Media MDEX browser only lists media with formats listed in the <app dir>\config\cas\media-crawl.xml file for the Media MDEX. You can add other formats to this file. 

<regex>^(?i:.*\.(?:gif|avi|flv|mpe?g?|fla|flr|sol|m4v|mov|wmv|ogg|ogv|webm|bmp|ico|tiff?|png|jpg|jpe?g|bmp|mp4|mp3))$</regex>

Use the cas-cmd createCrawls command to set that crawl. For more information on creating crawls, see the Oracle Commerce Content Acquisition System Developer's Guide.

The ability to store media in the Endeca Configuration Repository has been deprecated in Oracle Commerce 11.3. Oracle Commerce Strongly recommends against storing any media in the Endeca Configuration Repository.

If you wish to use the Endeca Configuration Repository as your media content source, you can upload assets directly to Experience Manager. It might be useful in a development environment, where a separate media server may not be worth the effort of maintaining.

All applications created using the Deployment Template include a set_media script in the <app dir>\control directory. This script uploads media content from the <app dir>\config\media directory to the Endeca Configuration Repository. After uploading content, it becomes available for use in Experience Manager.

In general, you can store moderate amounts of media content in the Endeca Configuration Repository. Very roughly speaking, a moderate amount of media content is approximately thousands of media files but not tens of thousands of media files. This storage mechanism is intended as a convenience when you build an application in a development environment.

If you have larger amounts of media content, Oracle recommends employing a digital asset management system rather than uploading the media content into the Endeca Configuration Repository.

Here are a few specific guidelines to keep in mind before you upload media content to the Endeca Configuration Repository:

To upload media content for use in Experience Manager:

  1. Ensure any new media content is stored locally in <app dir>\config\media.

    This may include image files, video files, and so on.

  2. In a command prompt, navigate to the <app dir>\control directory of your deployed application.

    This is located under your application directory. For example: C:\Endeca\apps\Discover\control.

  3. Run the set_media script.

  4. To verify that your media assets are available:

    1. Log in to Workbench.

    2. Open Experience Manager.

    3. Select a cartridge that includes the Media editor.

    4. Click the Select button to launch the Media editor and confirm that your media assets display.

Links to media assets are resolved in the Media editor by combining configuration in the editor configuration file with the media.path property on the selected record. At runtime, these links are resolved against the media sources specified in the Assembler context file.

You identify authoring content sources as nested elements within the <mediaRoots> element in the editor configuration file. The name of each such element corresponds to the value of the media.repository_id property assigned to each record in your media MDEX Engine. The value of each element identifies the root location of the authoring content source.

When a content administrator opens the Media Browser in Experience Manager, media assets are retrieved for preview by appending the value of the media.path property on the record to the corresponding content source element within <mediaRoots>. The media.path is then saved to the content item when the content administrator saves the cartridge configuration.

By keeping the relative location of your media assets consistent across environments, you can maintain separate content sources for authoring and live environments without requiring content administrators to reconfigure content items.

For example, assume the following element within <mediaRoots> in the editor configuration file: 

<myMediaSource>http://myhost.mydomain.com:8006/myCMS/Discover/media/</myMediaSource>

A media record with a media.repository_id value of "myMediaSource" and a media.path value of "images/foo.jpg" would resolve to: 

http://myhost.mydomain.com:8006/myCMS/Discover/media/images/foo.jpg

At runtime, the value of the media.path property is instead appended to the appropriate media source configured in assembler-context.xml: 

<!--
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    ~ Media Sources
-->

<bean id="authoringMediaSources" class="java.util.ArrayList" lazy-init="true">
    <constructor-arg>
        <list>
            <bean class="com.endeca.infront.cartridge.model.MediaSourceConfig">
                <property name="sourceName" value="MyMediaSource" />
                <property name="sourceValue" value="http://${workbench.host}:${workbench.port}/ifcr/sites/
${workbench.app.name}/media/" />
            </bean>
            <bean class="com.endeca.infront.cartridge.model.MediaSourceConfig">
                <property name="sourceName" value="default" />
                <property name="sourceValue" value="http://${workbench.host}:${workbench.port}/ifcr/sites/
${workbench.app.name}/media/" />
            </bean>
        </list>
    </constructor-arg>
</bean>

<bean id="liveMediaSources" class="java.util.ArrayList" lazy-init="true">
    <constructor-arg>
        <list>
            <bean class="com.endeca.infront.cartridge.model.MediaSourceConfig">
                <property name="sourceName" value="MyMediaSource" />
                <property name="sourceValue" value="/images/" />
            </bean>
            <bean class="com.endeca.infront.cartridge.model.MediaSourceConfig">
                <property name="sourceName" value="default" />
                <property name="sourceValue" value="/images/" />
            </bean>
        </list>
    </constructor-arg>
</bean>

In a live environment, the aforementioned media record would resolve to: 

http://myhost.mydomain.com:8006/myBiggerFasterCMS/Discover/media/assets/images/foo.jpg

Note

While the tooling, authoring, and live content sources can all differ, Oracle recommends configuring the Media Browser to use the authoring content source.

The default browser for the Media editor can only be configured to browse media assets in the Endeca Configuration Repository. If you are serving media assets from an external content source, you must enable the Media Browser and configure it to use your media MDEX Engine.

Follow these steps to configure the Media Browser in the MediaEditor JSON file for the Discover Electronics reference application, located at <app dir>\config\import\editors\MediaEditor\_.json:

  1. Change the value of the useMediaBrowser to true. 

     "useMediaBrowser": "true",

  2. Include a content source element under mediaRootsthat points to your media host.

    The element name is a unique key that identifies a media host. Each record has a corresponding media.repository_id property that identifies its content source. The relevant content source property maps that source to a URL.

    For example, in the CAS crawl configuration for the reference data application, each record is assigned a media.repository_id property with a value of mediaSource. The mediaSource property in the editor configuration file specifies the URL: 

    "mediaRoots": {
        "default": "http://Example-LAP:8006/ifcr/sites/Discover/media/",
        "mediaSource": "http://Example-LAP:8006/ifcr/sites/Discover/media/"
      },

    Note

    The default value is only used by the default asset browser. For more information, see "About Media editor configuration" and "Media MDEX Engine schema definition."

  3. Modify the mdexPort and mdexHost elements to point to the host and port of the MDEX Engine backing your media host. 

    "mdexPort": "17000",
      "mdexHost": "Example-LAP",

  4. Save and close the file. 

    {
    "ecr:type":"editor",
    "config": {
      "useMediaBrowser": "true",
      "mediaRoots": {
        "default": "http://Example-LAP:8006/ifcr/sites/Discover/media/",
        "mediaSource": "http://Example-LAP:8006/ifcr/sites/Discover/media/"
      },
      "mdexPort": "17000",
      "mdexHost": "Example-LAP",
      "videoFormats":"mp4|ogg|ogv|webm",
      "imageFormats": "jpg|png|gif",
      "mediaURI": "/ifcr/sites/Discover/media/"
     }  
}

  5. Navigate to the <app dir>\control directory.

  6. Run the set_editors_config script to publish your changes to the Endeca Configuration Repository.

Related links

If you are storing media resources in an independent content store, you can set up an MDEX Engine where records represent media assets and include asset metadata and URIs. Storing this information as records allows content administrators to navigate assets based on image size, modification date, or other attributes when selecting media assets for a content item.

Tools and Frameworks includes a reference media MDEX application, including a CAS pipeline and Deployment Template configuration.

The interactions between a media MDEX Engine, Experience Manager, and an Assembler application are summarized below.

Experience Manager retrieves media asset information as follows:

Assuming that an MDEX Engine exists with media records that adhere to the required data schema:

  1. In Experience Manager, the Media Browser queries the media MDEX Engine for media records. This allows the content administrator to select media assets by navigating across them with Guided Navigation.

  2. The content administrator's configuration changes are published to the application each time a content item is saved.

In a production environment, the Assembler application can be configured to retrieve media assets from a content delivery network or another media delivery server:

  1. Media assets are uploaded from the media content source to the runtime content delivery network.

  2. The application retrieves media from this content delivery network.

Note

The server hosting media assets can differ between authoring and live environments, as long as the media path relative to the media root is consistent. In the case of the reference pipeline, the authoring Discover Electronics Web application serves as the content source. For more information on configuring content sources, see About Media editor configuration.

The Tools and Frameworks package includes a reference implementation of a media MDEX Engine that includes a CAS crawl and Forge pipeline for crawling resources on the file system and indexing the corresponding metadata and URIs. The Experience Manager can then query the MDEX Engine for record information.

The reference media application illustrates the schema requirements and configuration that you should use when building your own media pipeline.

In addition to the hardware and software required for Oracle Tools and Frameworks, the data ingest process for the reference data application requires the Oracle Content Acquisition System. You must have CAS installed on the machine on which you are running the ITL process for the data application.

The crawl uses the following manipulators:

  1. Directory Filter: Filters out directory records, so that only media files are output to the MDEX Engine.

  2. Image Property Generator: Analyzes image binaries to determine their width and height. It adds corresponding image.width and image.height properties to each record.

  3. Application Property Generator: Assigns a media.application property based on the application specified when running the Deployment Template. This allows the Media Browser to display only those media assets that are relevant to the application that the content administrator is currently modifying in Workbench.

  4. Path Manipulator: Creates a media.path property that contains the path to given asset with respect to the media root.

The Forge pipeline for the reference data application reads data from the Record Store populated by the CAS crawl and runs manipulators against the data to generate the required MDEX Engine schema.

The reference media MDEX Engine data application assumes an environment where all required Oracle components are running on the same machine.

You must have the Oracle Content Acquisition System and Oracle Tools and Frameworks installed on the machine onto which you wish to deploy the media MDEX Engine.

The reference data application runs an MDEX Engine with indexed media resources, and integrates with the Discover Electronics reference application to expose the media records to a business user in the Media editor in Experience Manager. The records include properties for metadata, such as image dimensions, making it easier to narrow down a large quantity of media assets to those that fit the requirements for a cartridge in the front-end application.

To deploy the reference data application:

  1. Include the CAS manipulators for the reference data application as server plugins:

    1. Navigate to the %CAS_ROOT%\lib\cas-server-plugins.

    2. Create a directory named mediaMDEX.

    3. Navigate to the %ENDECA_TOOLS_ROOT%\reference\media-mdex-cas\cas\media-mdex-manipulators directory.

    4. Copy the following JAR files to the %CAS_ROOT%\lib\cas-server-plugins\mediaMDEX directory you created in step 1b:

    5. Navigate to the %ENDECA_TOOLS_ROOT%\reference\media-mdex-cas\lib directory.

    6. Copy the commons-io-1.4.jarfile to the %CAS_ROOT%\lib\cas-server-plugins\mediaMDEX directory you created in step 1b.

  2. Restart the CAS Service.

  3. Deploy the reference data application:

    1. Open a command prompt or command shell.

      Note

      If you are running the Tools and Frameworks from the included batch files, you must run ToolsAndFrameworks/<version>/server/bin/setenv.bat to set the environment variables for the current command window.

    2. Navigate to the ToolsAndFrameworks\<version>\deployment_template\bin directory.

    3. Run deploy.bat or deploy.sh with the following options: 

      deploy --app <Endeca Directory>/ToolsAndFrameworks/<version>/reference/media-mdex-cas/deploy.xml

    4. Confirm the Platform Services installation directory.

    5. Enter n to skip installation of a base application.

    6. Specify media as the application name.

    7. Specify the application directory.

      Typically, this is C:\Endeca\apps on Windows, or /usr/local/endeca/apps on UNIX.

    8. Specify the EAC port previously used for the Discover Electronics reference application.

      By default, this is port 8888.

    9. Specify the port that Workbench runs on.

      By default, this is port 8006.

    10. Specify a Dgraph port.

      Note

      This must be a different port from any other Dgraphs used for other applications.

      By default, this is port 17000. If you change this value, you must also update the configuration for the MediaEditor in the \config\import\editors\MediaEditor\_.json file after deploying the application.

    11. Specify the CAS installation directory.

    12. Specify the CAS version.

    13. Enter the port that CAS runs on.

      By default, this is port 8500.

    14. Enter the name of the application in which you wish to enable media browsing.

      For the Discover Electronics reference application this should be Discover.

    15. Enter the absolute path to the location on disk where media assets are stored.

      This is the file path that the Content Acquisition System crawls to index the files. In a default Discover Electronics deployment it is C:\Endeca\apps\Discover\config\media on Windows, or usr/local/endeca/apps/Discover/config/media on Unix.

  4. Provision the application with the EAC and run a baseline update:

    1. Navigate to the control directory of the deployed media application.

    2. Run the initialize_services script to provision the application in the EAC.

    3. Run the baseline_update script to crawl the directory specified in Step 4 and index the assets in the MDEX Engine.

In order for the Media Browser in Experience Manager to have sufficient information for forming content XML, any pipeline that you configure for a media MDEX Engine must define specific properties and dimensions.

The following properties are required for the Media Browser to function correctly:

Field

Description

record.id

A unique identifier for each of the media items.

media.name

The filename of the media asset.

media.path

The file path, relative to the root of the content source.

media.repository_id

The logical host of the content source. The value of this property is mapped to configuration elements for the Media editor in the editor configuration file, which in turn contain the path to the content source. For additional information, see "About Media editor configuration."

media.application

The EAC application that the specified media asset is associated with. The Media editor in Experience Manager filters entries in the Media Browser based on which application the content administrator is currently editing.

media.size

The binary size of the media asset, in bytes.

image.height

The height of the media asset, if it is an image. The renderer for the Media editor uses this information to scale images appropriately.

image.width

The width of the media asset, if it is an image. The renderer for the Media editor uses this information to scale images appropriately.

Optionally, additional properties and dimensions can be displayed in the Media Browser. The reference implementation of a media MDEX Engine includes the following such fields:

Field

Type

Description

media.file_type

Property

The MIME type of the media asset. This enables filtering by media type and file extension in the Media Browser.

media.last_modification_date

Property

The date and time that the file was last modified prior to being crawled by the Content Acquisition System.

fileType

Dimension

A searchable dimension based on media.file_type values.

height, width

Dimension

Searchable dimensions based on image.height and image.width values.

application

Dimension

A searchable dimension based on media.application values.

If you configure your own media MDEX Engine that includes properties or dimensions not listed above, they become available for Guided Navigation in the Media Browser. However, any such properties are not saved to content XML once a media asset has been selected.

The Media Browser requires a defined search interface named "All" that includes all searchable properties and dimensions in the data set. Additionally, the Media Browser in the reference application uses the "MatchAllPartial" search mode.

Copyright © Legal Notices