{"id":18554467,"url":"https://github.com/oracle/gatsby-source-oce","last_synced_at":"2025-04-09T23:31:26.708Z","repository":{"id":57134104,"uuid":"343993394","full_name":"oracle/gatsby-source-oce","owner":"oracle","description":"A Gatsby source plugin for importing content from an Oracle Content and Experience (OCE) service into a Gatsby application.","archived":true,"fork":false,"pushed_at":"2023-06-13T14:09:14.000Z","size":117,"stargazers_count":0,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-03T11:43:39.512Z","etag":null,"topics":["cms","gatsby","gatsby-plugin","graphql","headless-cms","oracle-cloud","oracle-content-experience","oracle-content-management"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"upl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oracle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-03T03:46:41.000Z","updated_at":"2024-07-16T07:21:21.000Z","dependencies_parsed_at":"2024-11-06T21:24:27.668Z","dependency_job_id":"20686b9f-4972-4514-8bf9-c9b488d35270","html_url":"https://github.com/oracle/gatsby-source-oce","commit_stats":{"total_commits":14,"total_committers":2,"mean_commits":7.0,"dds":0.1428571428571429,"last_synced_commit":"eb2f8df58ad920fd2eed192c29086f1c5968825b"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fgatsby-source-oce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fgatsby-source-oce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fgatsby-source-oce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fgatsby-source-oce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oracle","download_url":"https://codeload.github.com/oracle/gatsby-source-oce/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248129731,"owners_count":21052631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cms","gatsby","gatsby-plugin","graphql","headless-cms","oracle-cloud","oracle-content-experience","oracle-content-management"],"created_at":"2024-11-06T21:22:07.524Z","updated_at":"2025-04-09T23:31:25.613Z","avatar_url":"https://github.com/oracle.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About gatsby-source-oce\n\nA Gatsby source plugin for importing data from an [Oracle Content Management](https://docs.oracle.com/en/cloud/paas/content-cloud/headless-cms.html) service into a [Gatsby](https://www.gatsbyjs.com) application.\n\n## Installation\n\nRun the following to add this plugin to your package.json:\n\n```shell\nnpm install @oracle/gatsby-source-oce\n```\n\n## Documentation\n\nThis Gatsby plugin doesn't have any user-accessible APIs exposed. When configured properly, it will be invoked at either build or develop time by Gatsby and will download your assets and convert them into nodes that you can query with GraphQL.  Two types of nodes are created:\n\n- `OceAsset` nodes. These contain the JSON data for both digital assets and content items.\n- `File` nodes. All digital assets have a metadata section that includes URLs that can be used to access the associated binary data (the original file and any applicable renditions). Gatsby downloads these binaries and stores them as file nodes.\n\n### Set Up\n\nTo use gatsby-source-oce in your Gatsby site, add it to the plugins list in your gatsby-config.js file:  \n\n```javascript\nmodule.exports = {\n  plugins: [\n    {\n      resolve: 'gatsby-source-oce',\n      options: {\n        name: 'oce',\n        contentServer: 'https://\u003cservice-name\u003e-\u003caccount-name\u003e.cec.ocp.oraclecloud.com',\n        channelToken: '...',\n        proxyUrl: 'http://proxy.example.com:3128',\n        items: {\n          limit: 100,\n          query: '',\n        },\n        renditions: 'none',\n        preview: false,\n        auth: '',\n        oAuthSettings: null,\n        staticAssetDownload: 'false'.\n        staticAssetRootDir: 'asset'\n\n      },\n    },\n  ],\n}\n```\n\n### Configuration Options\n\n**`contentServer`** (required)  \nThis should be set to the base url for your Oracle Content Management service. The URL uses the pattern `https://\u003cservice-name\u003e-\u003caccount-name\u003e.cec.ocp.oraclecloud.com` and can be given to you by your Content service administrator.  \n\n**`channelToken`** (required)  \nThis should be set to the publishing channel holding your site's content.  \n\n**`proxyUrl`** [optional] *Defaults to empty which uses a direct connection*  \nThis can be used if there is a network proxy between the machine building your Gatsby project and the Content server. If a proxy is not being used then omit this field or set it to '' (empty string).  \n\n**`limit`** [optional] *Defaults to 100*  \nThis can be used to limit how many assets will be queried from the channel at one time.  \n\n**`query`** [optional] *Defaults to empty which selects everything*  \nThis can be used to reduce the set of assets to be downloaded from the channel.  With the empty default value all assets published to the specified channel will downloaded. Here are some sample queries:\n\n- Query a specific type of asset:  \n`'(type eq \"productReview\")'`\n- Query based on a field value:  \n`'(name eq \"John\")'`\n\nQuery strings are described in more detail [here](https://docs.oracle.com/en/cloud/paas/content-cloud/rest-api-content-delivery/op-published-api-v1.1-items-get.html).\n\n\u003e NOTE: Overly restrictive queries may result in an incomplete data set if content items reference other assets that are excluded by the query.  For example if you select only items of type `productReview` and these items reference items of type `Author`, then the items of type `Author` will *not* be downloaded to the Gatsby store. Unless there is a huge volume of content published on a channel that you do not need in your application, the safest option is to leave this query option empty.  \n\n**`renditions`** [optional]  \nThis setting controls which renditions of digital assets will be downloaded. This can have one of three values:  \n\n- `custom` (default) means that only custom renditions will be downloaded.\n- `none` means that only the original data will be downloaded.  \n- `all` means that all of the system generated renditions (*thumbnail*, *small*, etc.) will be downloaded as well as any custom renditions.\n\n\u003e NOTE: For each image downloaded, Gatsby will generate multiple renditions of its own to use for responsive display. This means that if you use the `all` value for renditions, Gatsby will generate resized copies of both the original image and for each of the system renditions (*thumbnail*, *small*, etc.). This can add a lot of processing time and network load to the build process for support that you may not need. It is recommended that you use the `none` or `custom` option unless you wish to explicitly use the system renditions.  \n\n**`preview`** [optional]  \nThis setting controls whether the client will be retrieving preview (unpublished) data or not. If true, it must be used with the auth parameter.  It defaults to false.\n\n**`auth`** [optional]  \nThis setting is used to set authentication tokens required when downloading from a secure publishing channel (preview=false) or preview items. It may use basic auth or\nan OAuth bearer token. It defaults to an empty string. Note that using this setting with a bearer token will not refresh the token when it is no longer valid. For that\nbehavior you need to use the oAuthSettings parameter documented below.\n\n**`oAuthSettings`** [optional]\nThis setting is used when using OAUTH to authenticate a secure publishing channel or using preview support. Using this will ensure that a valid OAUTH bearer token will\nbe available to the application. The setting takes the form of an object with the following fields:  \n{\n   clientId: 'xxxxx',  \n   clientSecret: 'xxxxx',  \n   clientScopeUrl: 'xxxxx',  \n   idpUrl: 'https://identity.server.com'  \n}  \n  \n**`staticAssetDownload`** [optional]  \nThis setting is used to make the plugin download binary assets into the public directory of the site as opposed to storing them in the internal Gatsby cache. This allows items such as image files to be referenced as direct URLs rather than using GraphQL to access them. It is used in combination with the staticAssetRootDir (described below). The default value is false which means all data will be in the cache instead. \n\n**`staticAssetRootDir`** [optional]  \nThis setting is ignored unless staticAssetDownload is set to true. This allows a developer to define a directory in the website that will contain all the downloaded assets. This can help to segregate the items coming from the server from other static data.  The default value is \"asset\", but it can be set to any string that is a valid directory name. \n\n**`staticUrlPrefix`** [optional]  \nThis setting is ignored unless staticAssetDownload is set to true. This needs to be set if the application has a pathPrefix defined in its gatsby-config.js file. In static mode all downloaded files are given a URL relative to the build root (/public) of the application by default. If there is a pathPrefix specified though, then the URLs need to be prefixed with that value as well.  \nFor example: If there is a file \"logo.png\" it might be given a default URL of /server/logo.png . If however, the app uses a pathPrefix of /myApplication, this URL should be changed to /myApplication/server/logo.png.  \nSetting staticUrlPrefix equal to the pathPrefix will cause the plugin to make this adjustment in the Gatsby cache.   \n\n\n**`How to use static download:`**  \n  Assume there is a digital asset on the server called Logo.jpg that contains an image to be used in a site.  \nIf staticAssetDownload is false then the binary image will be stored in the cache as well as any selected renditions. (See 'renditions' flag above)   These binary files can then be queried and traversed via GraphQL  \n  \nIf staticAssetDownload is true and staticAssetRootDir is set to 'server' then the file will be available in the website as: /server/Logo.jpg and could be displayed\nin an \\\u003cimg\\\u003e tag as \\\u003cimg src=\"/server/Logo.jpg\"\\/\u003e  . If the user has chosen to download all the renditions of the digital assets in their site then the following urls\nwill be available:   \n/server/Logo.jpg     (the original)  \n/server/Large/Logo.jpg     (the large rendition)  \n/server/Medium/Logo.jpg     (the medium rendition)  \n/server/Small/Logo.jpg     (the small rendition)  \n/server/Thumbnail/Logo.jpg     (the thumbnail rendition)  \n\nIf there are any custom renditions, then they will also appear as\n/server/*custom rendition name*/Logo.jpg\n \n\n\n\n\n### Content Model\n\nThe data model used for content data in Gatsby closely models the JSON data provided by the Oracle Content Management REST interface. There are a few small exceptions though that are needed to avoid conflicts between Gatsby node reserved fields and Oracle Content Management data. These include:\n\n- All assets are typed as `oceAsset` so that they can be distinguished from other assets in GraphQL queries.\n- Some Oracle Content Management asset fields are renamed to avoid conflicts with reserved Gatsby node field names. `id` becomes `oceId`,  `fields` becomes `oceFields`, and `type` becomes `oceType`.\n- In traditional Oracle Content Management usage, a digital asset provides a URL that can be used to retrieve the binary form(s) of the asset from the server. As Gatsby builds static sites, these binary values must be stored locally and are placed in file nodes in the GraphQL store.  To allow these binary forms to be retrieved easily in a site, a link is established between the file nodes and the digital asset nodes. What this means is that it is possible to traverse an `oceAsset` and find the internal Gatsby representations of its binary data without having to load the file nodes as well. All of an `oceAsset`'s  file data can be found under the field `childrenFile`.\n\n## Examples\n\nYou can query `OceAsset` nodes in the following manner:  \n(This returns the names and types of all assets. Note that the `type` field is internal to Gatsby, so we use the `oceType` field to get the Oracle Content Management name for each definition )  \n\n```graphql\n{\n  allOceAsset {\n    nodes {\n      name\n      oceType\n    }\n  }\n}\n```\n\nA similar query where we filter out all assets that are not of type `DigitalAsset`:  \n\n```graphql\n{\n  allOceAsset(filter: {oceType: {ne: \"DigitalAsset\"}}) {\n    nodes {\n      name\n    }\n  }\n}\n```\n\nLoad the information needed to display the image `Banner1.jpg` as a fluid (responsive) image in Gatsby. What we are doing is to first load the asset by name and then look in the `childrenFile` field to get the data stored in the linked Gatsby file node.  \n\n```graphql\n{\n  oceAsset(name: {eq: \"Banner1.jpg\"}) {\n    childrenFile {\n      name\n      fields {\n        rendition\n      }\n      childImageSharp {\n        gatsbyImageData(quality: 100, layout: FULL_WIDTH)\n      }\n    }\n  }\n}\n```\n\n## Contributing\n\nThis project welcomes contributions from the community. Before submitting a pull\nrequest, please [review our contribution guide](./CONTRIBUTING.md).\n\n## Security\n\nPlease consult the [security guide](./SECURITY.md) for our responsible security\nvulnerability disclosure process.\n\n## License\n\nCopyright (c) 2021, 2022, Oracle and/or its affiliates.\n\nReleased under the Universal Permissive License v1.0 as shown at\n\u003chttps://oss.oracle.com/licenses/upl/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fgatsby-source-oce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foracle%2Fgatsby-source-oce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fgatsby-source-oce/lists"}