Skip to content

Commit bf95916

Browse files
jacobo-dominguez-wgujacobo-dominguez-wgu
authored
docs: add comprehensive readme documentation for plugin slots (#1770)
1 parent 48270c3 commit bf95916

File tree

10 files changed

+374
-14
lines changed

10 files changed

+374
-14
lines changed

‎src/plugin-slots/ContentIFrameLoaderSlot/README.md

Lines changed: 49 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,56 @@
1-
# Content iframe Loader Slot
1+
# Content IFrame Loader Slot
22

33
### Slot ID: `org.openedx.frontend.learning.content_iframe_loader.v1`
44

55
### Slot ID Aliases
66
* `content_iframe_loader_slot`
77

88
### Props:
9-
* `courseId`
10-
* `defaultLoaderComponent`
9+
* `courseId` - String identifier for the current course
10+
* `defaultLoaderComponent` - React component used as the default loading indicator
11+
12+
## Description
13+
14+
This slot is used to customize the loading indicator displayed while course content is being loaded in an iframe. It appears when content is loading but hasn't fully rendered yet, providing a customizable loading experience for learners.
15+
16+
The default implementation shows a `PageLoading` component with a screen reader message.
17+
18+
## Example
19+
20+
The following `env.config.jsx` will replace the default loading spinner with a custom loading component that shows the course ID and a custom message.
21+
22+
![Content Iframe Loader Example](./images/loader-example.png)
23+
24+
25+
```js
26+
import { DIRECT_PLUGIN, PLUGIN_OPERATIONS } from '@openedx/frontend-plugin-framework';
27+
28+
const config = {
29+
pluginSlots: {
30+
'org.openedx.frontend.learning.content_iframe_loader.v1': {
31+
plugins: [
32+
{
33+
op: PLUGIN_OPERATIONS.Insert,
34+
widgetId: 'default_contents',
35+
widget: {
36+
id: 'custom_iframe_loader',
37+
type: DIRECT_PLUGIN,
38+
RenderWidget: ({ courseId, defaultLoaderComponent }) => (
39+
<div style={{ textAlign: 'center', padding: '2rem' }}>
40+
<h3>Loading course content...</h3>
41+
<p>Course: {courseId}</p>
42+
<div style={{ margin: '1rem 0' }}>
43+
{defaultLoaderComponent}
44+
</div>
45+
<p>Please wait while we prepare your learning experience</p>
46+
</div>
47+
),
48+
},
49+
},
50+
]
51+
}
52+
},
53+
}
54+
55+
export default config;
56+
```

‎src/plugin-slots/ContentIFrameLoaderSlot/images/loader-example.png

79.9 KB
Loading

‎src/plugin-slots/CourseOutlineTabNotificationsSlot/README.md

Lines changed: 52 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,55 @@
66
* `outline_tab_notifications_slot`
77

88
### Props:
9-
* `courseId`
10-
* `model`
9+
* `courseId` - String identifier for the current course
10+
* `model` - String indicating the context model (set to 'outline')
11+
12+
## Description
13+
14+
This slot is used to add custom notification components to the course outline tab sidebar. It appears in the right sidebar of the course outline/home tab, positioned between the Course Tools widget and the Course Dates widget.
15+
16+
The slot provides a flexible way to inject custom notifications, announcements, or informational components that are contextually relevant to the course outline view.
17+
18+
## Example
19+
20+
The following `env.config.jsx` will add a custom notification component to the course outline tab sidebar.
21+
22+
![Course notification example](./images/course-outline-notification-example.png)
23+
24+
```js
25+
import { DIRECT_PLUGIN, PLUGIN_OPERATIONS } from '@openedx/frontend-plugin-framework';
26+
27+
const config = {
28+
pluginSlots: {
29+
'org.openedx.frontend.learning.course_outline_tab_notifications.v1': {
30+
plugins: [
31+
{
32+
op: PLUGIN_OPERATIONS.Insert,
33+
widget: {
34+
id: 'custom_outline_notification',
35+
type: DIRECT_PLUGIN,
36+
RenderWidget: ({ courseId, model }) => (
37+
<div className="card mb-3">
38+
<div className="card-body">
39+
<h5 className="card-title">📢 Course Announcement</h5>
40+
<p className="card-text">
41+
Important updates for course {courseId}
42+
</p>
43+
<p className="text-muted small">
44+
Context: {model}
45+
</p>
46+
<button className="btn btn-primary btn-sm">
47+
View Details
48+
</button>
49+
</div>
50+
</div>
51+
),
52+
},
53+
},
54+
]
55+
}
56+
},
57+
}
58+
59+
export default config;
60+
```

‎src/plugin-slots/CourseOutlineTabNotificationsSlot/images/course-outline-notification-example.png

135 KB
Loading

‎src/plugin-slots/GatedUnitContentMessageSlot/README.md

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,65 @@
66
* `gated_unit_content_message_slot`
77

88
### Props:
9-
* `courseId`
9+
* `courseId` - String identifier for the current course
10+
11+
## Description
12+
13+
This slot is used to customize the message displayed when course content is gated or locked for learners who haven't upgraded to a verified track. It appears when a unit contains content that requires a paid enrollment (such as graded assignments) and the learner is on the audit track.
14+
15+
The default implementation shows a `LockPaywall` component that displays an upgrade message with benefits of upgrading, including access to graded assignments, certificates, and full course features.
16+
17+
This slot is conditionally rendered only when `contentTypeGatingEnabled` is true and the unit `containsContentTypeGatedContent`.
18+
19+
## Example
20+
21+
The following `env.config.jsx` will replace the default paywall message with a custom gated content component.
22+
23+
![Gated unit message example](./images/gated-unit-message-example.png)
24+
25+
```js
26+
import { DIRECT_PLUGIN, PLUGIN_OPERATIONS } from '@openedx/frontend-plugin-framework';
27+
28+
const config = {
29+
pluginSlots: {
30+
'org.openedx.frontend.learning.gated_unit_content_message.v1': {
31+
plugins: [
32+
{
33+
op: PLUGIN_OPERATIONS.Insert,
34+
widgetId: 'default_contents',
35+
widget: {
36+
id: 'custom_gated_message',
37+
type: DIRECT_PLUGIN,
38+
RenderWidget: ({ courseId }) => (
39+
<div className="alert alert-warning" role="alert">
40+
<div className="d-flex align-items-center mb-3">
41+
<i className="fa fa-lock fa-2x me-3" aria-hidden="true"></i>
42+
<div>
43+
<h4 className="alert-heading mb-1">Premium Content</h4>
44+
<p className="mb-0">This content is available to verified learners only.</p>
45+
</div>
46+
</div>
47+
<hr />
48+
<p className="mb-3">
49+
Upgrade your enrollment for course {courseId} to access:
50+
</p>
51+
<ul className="mb-3">
52+
<li>✅ Graded assignments and quizzes</li>
53+
<li>🏆 Verified certificate upon completion</li>
54+
<li>💬 Full discussion forum access</li>
55+
<li>📱 Mobile app offline access</li>
56+
</ul>
57+
<button className="btn btn-success">
58+
Upgrade Now
59+
</button>
60+
</div>
61+
),
62+
},
63+
},
64+
]
65+
}
66+
},
67+
}
68+
69+
export default config;
70+
```

‎src/plugin-slots/GatedUnitContentMessageSlot/images/gated-unit-message-example.png

74.3 KB
Loading

‎src/plugin-slots/NotificationTraySlot/README.md

Lines changed: 89 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,92 @@
66
* `notification_tray_slot`
77

88
### Props:
9-
* `courseId`
10-
* `notificationCurrentState`
11-
* `setNotificationCurrentState`
9+
* `courseId` - String identifier for the current course
10+
* `model` - String indicating the context model (set to 'coursewareMeta')
11+
* `notificationCurrentState` - Current state of upgrade notifications (UpgradeNotificationState)
12+
* `setNotificationCurrentState` - Function to update the notification state
13+
14+
## Description
15+
16+
This slot is used to customize the notification tray that appears in the courseware sidebar. The notification tray displays upgrade-related notifications and alerts for learners in verified mode courses. It provides a way to show contextual notifications about course access, deadlines, and upgrade opportunities.
17+
18+
The slot is conditionally rendered only for learners in verified mode courses. For non-verified courses, a simple "no notifications" message is displayed instead.
19+
20+
The `notificationCurrentState` can be one of: `'accessLastHour'`, `'accessHoursLeft'`, `'accessDaysLeft'`, `'FPDdaysLeft'`, `'FPDLastHour'`, `'accessDateView'`, or `'PastExpirationDate'`.
21+
22+
## Example
23+
24+
The following `env.config.jsx` will customize the notification tray with additional notification types and styling.
25+
26+
![Notification tray slot example](./images/notification-tray-slot-example.png)
27+
```js
28+
import { DIRECT_PLUGIN, PLUGIN_OPERATIONS } from '@openedx/frontend-plugin-framework';
29+
30+
const config = {
31+
pluginSlots: {
32+
'org.openedx.frontend.learning.notification_tray.v1': {
33+
plugins: [
34+
{
35+
// Insert custom notification content
36+
op: PLUGIN_OPERATIONS.Replace,
37+
widget: {
38+
id: 'custom_notifications',
39+
type: DIRECT_PLUGIN,
40+
RenderWidget: ({
41+
courseId,
42+
model,
43+
notificationCurrentState,
44+
setNotificationCurrentState
45+
}) => (
46+
<div className="p-3">
47+
<h5 className="mb-3">📬 Course Notifications</h5>
48+
49+
{notificationCurrentState === 'accessLastHour' && (
50+
<div className="alert alert-warning mb-3">
51+
<strong>⏰ Last Chance!</strong>
52+
<p className="mb-0">Your access expires in less than an hour.</p>
53+
</div>
54+
)}
55+
56+
{notificationCurrentState === 'accessDaysLeft' && (
57+
<div className="alert alert-info mb-3">
58+
<strong>📅 Access Reminder</strong>
59+
<p className="mb-0">Your course access expires in a few days.</p>
60+
</div>
61+
)}
62+
63+
<div className="notification-item p-2 mb-2 border rounded">
64+
<div className="d-flex justify-content-between align-items-center">
65+
<span>📚 New course material available</span>
66+
<button
67+
className="btn btn-sm btn-outline-primary"
68+
onClick={() => setNotificationCurrentState('accessDateView')}
69+
>
70+
View
71+
</button>
72+
</div>
73+
</div>
74+
75+
<div className="notification-item p-2 mb-2 border rounded">
76+
<div className="d-flex justify-content-between align-items-center">
77+
<span>🎯 Assignment due tomorrow</span>
78+
<span className="badge bg-warning">Due Soon</span>
79+
</div>
80+
</div>
81+
82+
<div className="text-center mt-3">
83+
<small className="text-muted">
84+
Course: {courseId} | Model: {model}
85+
</small>
86+
</div>
87+
</div>
88+
),
89+
},
90+
},
91+
]
92+
}
93+
},
94+
}
95+
96+
export default config;
97+
```

‎src/plugin-slots/NotificationTraySlot/images/notification-tray-slot-example.png

118 KB
Loading

0 commit comments

Comments
 (0)