Download the PHP package dynamic/silverstripe-salsify without Composer

SilverStripe Salsify

Salsify integration for SilverStripe websites.

Requirements

• SilverStripe ^4.0

Installation

License

See License

Table of Contents

• Running the task
• Example configuration
  • Extensions
    • SalsifyIDExtension
    • SalsifyFetchExtension
  • Importer
  • Fetcher
  • Mapper
    • Unique Fields
    • Field Types
    • Raw
    • SalsifyID, SalsifyUpdatedAt, and SalsifyRelationsUpdatedAt
    • Boolean
      • isTrue
    • Literal
    • Files and Images
      • Image Transformation
    • HasOne and HasMany
      • HasOne Example
      • ManyRelation Example
    • Salsify Relations
    • Field Fallback
    • Keeping Field Values Without a Salsify Field
    • Extending onBeforeMap
    • Extending onAfterMap
    • Extending beforeObjectWrite
    • Extending afterObjectWrite
    • Advanced
      • Custom Field Types
      • Skipping Objects
      • Modify Field Data
      • Using a Property To Assign a Parent
      • Creating Virtual Pages with Pages
      • Redirects
      • Attributes in Group as DataObjects
  • Single Object Import
• Troubleshooting
• Maintainers
• Bugtracker
• Development and contribution

Running the task

The task can be run from a browser window or the command line. To run the task in the browser go to dev/tasks and find Import products from salsify or visit dev/tasks/SalsifyImportTask.

It is recommended to use the command line, because the task can easily time out in a browser. To run the task in the command line sake must be installed and the command sake dev/tasks/SalsifyImportTask must be run.

Example configuration

Extensions

SalsifyIDExtension

It is recommended to add Dynamic\Salsify\ORM\SalsifyIDExtension as an extension of any object being mapped to. It will add a SalsifyID and SalsifyUpdatedAt field that can be mapped to. The SalsifyID field is used in single object updates.

The SalsifyID and SalsifyUpdatedAt fields will still need to be explicitly mapped in the mapper config.

SalsifyFetchExtension

The SalsifyFetchExtension is automatically added to left and main. It will provide a button on data objects that have a salsify mapping to refetch.

To have the button force update refetch_force_update and refetch_force_update_relations can be set to true on the data object being mapped to. When set to true refetch_force_update will force update any non-relation field in salsify. When set to true refetch_force_update_relations will force update any relation field in salsify.

See the Single Object Import section for more setup information.

Importer

Importers will run fetchers and mappers. Each importer needs to be passed an importerKey to its constructor. For the rest of the readme example will be used for the services.

Fetcher

To set up a fetcher an api key and a channel id need to be provided. The apiKey can be in the root Fetcher config, but can also be overridden in a specific service config. The channel id can be found by visiting the channel in Salsify and copying the last section of the url. https://app.salsify.com/app/orgs/<org_id>/channels/<channel_id> To find the api key follow this

or

An organization ID can also be included to avoid an account having access to multiple organizations.

or

https://developers.salsify.com/docs/organization-id

The fetcher can also have the timeout changed for http requests. This is not a timeout for Salsify to generate an export. Timeout is in milliseconds and defaults to 2000 ms or 2 seconds. Like an apiKey the timeout can be set in the root fetcher config and be overridden by a service config.

or

Mapper

To set up a mapper, which will map fields from Salsify to SilverStripe, some configuration is needed.

Each mapper instance will need a service config. Under the mapping config one or more classes can be specified for import. Each class can have one or more fields to map, and must have at least one that is unique. All fields have the key of the SilverStripe field to map to. Title: Product Title will map Product Title from Salsify to Title in SilverStripe.

Unique Fields

Like non-unique fields, the key is the SilverStripe field to map to. salsifyField is the field from Salsify to map. unique is either true or false and will be used as a filter to check against existing records.

The unique fields will be added to an array, with the values for each product and will be used as a filter to find existing. This allows for multiple compound unique fields.

Field Types

The built in field types are Raw, Literal, File, Image, HasOne, HasMany. There are some specialized field types that are SalsifyID, SalsifyUpdatedAt, SalsifyRelationsUpdatedAt that are meant for mapping to specific fields without modifications. More types can also be added.

Raw

By default the Raw type is used. It will write the salsify property value into the object field.

SalsifyID, SalsifyUpdatedAt, and SalsifyRelationsUpdatedAt

Fields that have these types cannot be modified, but will be handled like a raw type.

Boolean

Useful for mapping Yes/No value fields from salsify to the boolean database type.

isTrue

The boolean handler also comes with a handy isTrue helper method. This is helpful when modifications or skipping has to be done on a Yes/No formatted property.

Literal

To set a field that doesn't have a salsify field a literal field can be used.

The above example will set the Author field to Chris P. Bacon for all mapped pages.

Files and Images

To get an image or file from salsify to map to an object a type needs to be specified.

Images and files can also be mapped by ID.

If the mapping is specified as an image and it is not a valid image extension, salsify will be used to try and convert the file into a png.

Image Transformation

To cut down on 500 errors caused by trying to resize images when visiting a page images can be transformed by salsify. When an image transformation is updated in the config it will also re-download the image with the new transformations.

The above will download http://a1.images.salsify.com/image/upload/c_fit,w_1000,h_1000,dn_300,cs_srgb/sample.jpg instead of http://a1.images.salsify.com/image/upload/sample.jpg.

To see what transformations salsify supports please visit https://getstarted.salsify.com/help/transforming-image-files.

It is recommended to do this to all large files.

HasOne and HasMany

has_one and has_many relations can be done just about the same. The HasOne's salsifyField doesn't matter. The ManyRelation type requires a salsify field that is an array. ManyRelation can also have a sort column specified. All modifications to the data will be passed through to the mapping relation.

HasOne example:

ManyRelation example:

Salsify Relations

Relationships between products can also be created in salsify. By default it will map to a has_many and many_many relation. The salsifyField is the name of the relation type.

To map to a has_one relation a single object can be returned.

Field Fallback

A fallback field can be specified for salsify. The fallback will be used when the normal salsifyField is not in the data from salsify for the object being mapped. The fallback can be a string or array.

or

Keeping Field Values Without a Salsify Field

By default all values that are to be mapped will wipe values if there is no salsify field in the data for an object. This can be changed so it keeps values for a field.

This will keep the previous value of the title, even if the field is no longer in the data.

Extending onBeforeMap

onBeforeMap is run after the fetcher runs, but before the mapper starts to map. It is passed the file url from the channel export and if the map is of multiple or a single product.

Extending onAfterMap

onAfterMap is run after the fetcher runs, but before the mapper starts to map. It is passed the file url from the channel export and if the map is of multiple or a single product. This extension point is good for cleaning up products that are not in the channel export.

Extending beforeObjectWrite

This extension point is good for detecting which fields were changed. This is helpful to create redirects for pages if a parent has changed during mapping.

Extending afterObjectWrite

To publish an object after mapping the afterObjectWrite method can be extended. It is passed the DataObject that was written, if the object was in the database, and if the object was published. If the object does not have the versioned extension applied $wasPublished will be false.

Advanced

Custom Field Types

Skipping Objects

Modify Field Data

Using a Property To Assign a Parent

Creating Virtual Pages with Pages

Redirects

Attributes in Group as DataObjects

Single Object Import

Adding a re-fetch button in the cms requires some configuration. An organization is required to fetch a single product. A SalsifyID field is also required for single object imports. Only a mapping service with the name of single is required and will act just like a normal mapper config; however, a fetcher service config can also be defined to specify the organization.

To use the single object mapper as a normal importer, when running the task, an Importer service.

For more configuration options see SalsifyFetchExtension

Troubleshooting

Some fields are not importing

If some fields are not importing please make sure they show up in the data. Occasionally properties will have a different id and name, in this case the data will show up under the property id.

Maintainers

• Dynamic [email protected]

Bugtracker

Bugs are tracked in the issues section of this repository. Before submitting an issue please read over existing issues to ensure yours is unique.

If the issue does look like a new bug:

• Create a new issue
• Describe the steps required to reproduce your issue, and the expected outcome. Unit tests, screenshots and screencasts can help here.
• Describe your environment as detailed as possible: SilverStripe version, Browser, PHP version, Operating System, any installed SilverStripe modules.

Please report security issues to the module maintainers directly. Please don't file security issues in the bugtracker.

Development and contribution

If you would like to make contributions to the module please ensure you raise a pull request and discuss with the module maintainers.