Skip to content
This repository was archived by the owner on Jul 16, 2024. It is now read-only.

Commit 54b5cb2

Browse files
kmacdonaOkmacdonaO
authored
Create README.md
0 parents  commit 54b5cb2

File tree

1 file changed

+152
-0
lines changed

1 file changed

+152
-0
lines changed

‎README.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# About gatsby-source-oce
2+
3+
A Gatsby source plugin for importing data from an [Oracle Content and Experience](https://docs.oracle.com/en/cloud/paas/content-cloud/headless-cms.html) (OCE) service into a [Gatsby](https://www.gatsbyjs.com) application.
4+
5+
## Installation
6+
7+
Run the following to add this plugin to your package.json:
8+
9+
```shell
10+
npm install @oracle/gatsby-source-oce
11+
```
12+
13+
## Documentation
14+
15+
### Setup
16+
17+
To use gatsby-source-oce in your Gatsby site, add it to the plugins list in your gatsby-config.js file:
18+
19+
```javascript
20+
module.exports = {
21+
plugins: [
22+
{
23+
resolve: 'gatsby-source-oce',
24+
options: {
25+
name: 'oce',
26+
contentServer: 'https://<service-name>-<account-name>.cec.ocp.oraclecloud.com',
27+
channelToken: '...',
28+
proxyUrl: 'http://proxy.example.com:3128',
29+
items: {
30+
limit: 100,
31+
query: '',
32+
},
33+
renditions: 'none',
34+
},
35+
},
36+
],
37+
}
38+
```
39+
40+
### Configuration Options
41+
42+
**`contentServer`** (required)
43+
This should be set to the base url for your Oracle Content service. The URL uses the pattern `https://<service-name>-<account-name>.cec.ocp.oraclecloud.com` and can be given to you by your OCE service administrator.
44+
45+
**`channelToken`** (required)
46+
This should be set to the publishing channel holding your site's content.
47+
48+
**`proxyUrl`** [optional] *Defaults to empty which uses a direct connection*
49+
This can be used if there is a network proxy between the machine building your Gatsby project and the OCE server. If a proxy is not being used then omit this field or set it to '' (empty string).
50+
51+
**`limit`** [optional] *Defaults to 100*
52+
This can be used to limit how many assets will be queried from the channel at one time.
53+
54+
**`query`** [optional] *Defaults to empty which selects everything*
55+
This 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:
56+
57+
- Query a specific type of asset:
58+
`'(type eq "productReview")'`
59+
- Query based on a field value:
60+
`'(name eq "John")'`
61+
62+
Query 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).
63+
64+
> 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.
65+
66+
**`renditions`** [optional]
67+
This setting controls which renditions of digital assets will be downloaded. This can have one of three values:
68+
69+
- `custom` (default) means that only custom renditions will be downloaded.
70+
- `none` means that only the original data will be downloaded.
71+
- `all` means that all of the OCE-generated renditions (*thumbnail*, *small*, etc.) will be downloaded as well as any custom renditions.
72+
73+
> 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 OCE 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 OCE renditions.
74+
75+
### Content Model
76+
77+
The data model used for OCE data in Gatsby closely models the JSON data provided by the OCE REST interface. There are a few small exceptions though that are needed to avoid conflicts between Gatsby node reserved fields and OCE data. These include:
78+
79+
- All assets are typed as `oceAsset` so that they can be distinguished from other assets in GraphQL queries.
80+
- Some OCE asset fields are renamed to avoid conflicts with reserved Gatsby node field names. `id` becomes `oceId`, `fields` becomes `oceFields`, and `type` becomes `oceType`.
81+
- In traditional OCE 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`.
82+
83+
### Examples
84+
85+
The OCE 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:
86+
87+
- `OceAsset` nodes. These contain the JSON data for both digital assets and content items.
88+
- `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.
89+
90+
You can query `OceAsset` nodes in the following manner:
91+
(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 OCE name for each definition )
92+
93+
```graphql
94+
{
95+
allOceAsset {
96+
nodes {
97+
name
98+
oceType
99+
}
100+
}
101+
}
102+
```
103+
104+
A similar query where we filter out all assets that are not of type `DigitalAsset`:
105+
106+
```graphql
107+
{
108+
allOceAsset(filter: {oceType: {ne: "DigitalAsset"}}) {
109+
nodes {
110+
name
111+
}
112+
}
113+
}
114+
```
115+
116+
Load 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.
117+
118+
```graphql
119+
{
120+
oceAsset(name: {eq: "Banner1.jpg"}) {
121+
childrenFile {
122+
name
123+
fields {
124+
rendition
125+
}
126+
childImageSharp {
127+
fluid(quality: 100) {
128+
129+
...GatsbyImageSharpFluid_withWebp
130+
}
131+
}
132+
}
133+
}
134+
}
135+
```
136+
137+
## Contributing
138+
139+
This project welcomes contributions from the community. Before submitting a pull
140+
request, please [review our contribution guide](./CONTRIBUTING.md).
141+
142+
## Security
143+
144+
Please consult the [security guide](./SECURITY.md) for our responsible security
145+
vulnerability disclosure process.
146+
147+
## License
148+
149+
Copyright (c) 2021 Oracle and/or its affiliates.
150+
151+
Released under the Universal Permissive License v1.0 as shown at
152+
<https://oss.oracle.com/licenses/upl/>.

0 commit comments

Comments
 (0)