Show notice in Course Editor to focus on Course Outline block or Insert one if block does not exist for first time users

assets/admin/editor-wizard/steps/patterns-step.js

@@ -37,7 +37,7 @@
 			? replacePlaceholders( blocks, replaces )
 			: blocks;
 
-		resetEditorBlocks( newBlocks );
+		resetEditorBlocks( newBlocks, { patternName: name } );
 		onCompletion();
 
 		//Auto select a template if the pattern specifies an available one.

assets/js/admin/first-course-creation-notice.js

@@ -0,0 +1,125 @@
+/**
+ * WordPress dependencies
+ */
+import { createBlock } from '@wordpress/blocks';
+import { select, subscribe, dispatch } from '@wordpress/data';
+import domReady from '@wordpress/dom-ready';
+import { __ } from '@wordpress/i18n';
+/**
+ * Internal dependencies
+ */
+import { getFirstBlockByName } from '../../blocks/course-outline/data';
+
+export const getOutlineBlock = () =>
+	getFirstBlockByName(
+		'sensei-lms/course-outline',
+		select( 'core/block-editor' ).getBlocks()
+	);
+
+export const handleCourseOutlineBlockIncomplete = () => {
+	const courseOutlineBlock = getOutlineBlock();
+
+	// If the course outline block exists, just select it.
+	if ( courseOutlineBlock ) {
+		dispatch( 'core/editor' ).selectBlock( courseOutlineBlock.clientId );
+		return;
+	}
+
+	const { insertBlock } = dispatch( 'core/block-editor' );
+
+	insertBlock( createBlock( 'sensei-lms/course-outline' ) );
+};
+
+// If the function isn't globally available, the link button doesn't find the reference.
+window.handleCourseOutlineBlockIncomplete = handleCourseOutlineBlockIncomplete;
+
+export const hasLessonInOutline = ( blocks ) => {
+	return blocks.some( ( block ) => {
+		if ( block.name === 'sensei-lms/course-outline-lesson' ) {
+			return true;
+		}
+
+		if ( block.innerBlocks?.length ) {
+			return hasLessonInOutline( block.innerBlocks );
+		}
+
+		return false;
+	} );
+};
+
+export const handleFirstCourseCreationHelperNotice = () => {
+	const { createInfoNotice, removeNotice } = dispatch( 'core/notices' );
+	const userId = select( 'core' ).getCurrentUser()?.id;
+	const { getEditedPostAttribute } = select( 'core/editor' );
+	const { editPost } = dispatch( 'core/editor' );
+	const firstCourseNoticeDismissedKey =
+		'sensei-lms-first-course-notice-dismissed-' + userId;
+	const isFirstCourseNoticeDismissed = !! window.localStorage.getItem(
+		firstCourseNoticeDismissedKey
+	);
+	const noticeId = 'course-outline-block-setup-incomplete';
+	const isNewCourse = window?.sensei?.isNewCourse;
+
+	let noticeCreated = false;
+	let noticeRemoved = false;
+
+	const notice = __(
+		'Nice! Now you can <a href="javascript:;" onclick="window?.handleCourseOutlineBlockIncomplete();">add some lessons</a> to your course.',
+		'sensei-lms'
+	);
+
+	let isNewPostMetaSet = false;
+
+	subscribe( () => {
+		if ( isNewCourse && ! isNewPostMetaSet ) {
+			if ( getOutlineBlock() ) {
+				isNewPostMetaSet = true;
+				editPost( {
+					meta: { _new_post: true },
+				} );
+			}
+		}
+		const patternSelected =
+			! isNewCourse ||
+			( isNewPostMetaSet &&
+				false === getEditedPostAttribute( 'meta' )?._new_post );
+		if (
+			noticeCreated &&
+			! noticeRemoved &&
+			getOutlineBlock() &&
+			hasLessonInOutline( [ getOutlineBlock() ] )
+		) {
+			noticeRemoved = true;
+			noticeCreated = false;
+			removeNotice( noticeId );
+		}
+
+		// If the user selects a Sensei pattern or editing an existing Course, and the notice hasn't been created, and notice hasn't been dismissed, and either the course outline block hasn't been created OR there are no published lessons in the outline, create the notice.
+		if (
+			patternSelected &&
+			! noticeCreated &&
+			! isFirstCourseNoticeDismissed &&
+			! (
+				getOutlineBlock() && hasLessonInOutline( [ getOutlineBlock() ] )
+			)
+		) {
+			noticeCreated = true;
+			noticeRemoved = false;
+
+			createInfoNotice( notice, {
+				id: noticeId,
+				isDismissible: true,
+				__unstableHTML: true, // Necessary to render the link in the middle of the notice message.
+				onDismiss: () => {
+					window.localStorage.setItem(
+						firstCourseNoticeDismissedKey,
+						'1'
+					);
+				},
+			} );
+		}
+	} );
+};
+
+// Call function on dom ready.
+domReady( handleFirstCourseCreationHelperNotice );

assets/js/admin/first-course-creation-notice.test.js

@@ -0,0 +1,125 @@
+/**
+ * WordPress dependencies
+ */
+import { createBlock } from '@wordpress/blocks';
+import { dispatch, select, subscribe } from '@wordpress/data';
+/**
+ * Internal dependencies
+ */
+import {
+	getOutlineBlock,
+	handleCourseOutlineBlockIncomplete,
+	handleFirstCourseCreationHelperNotice,
+	hasLessonInOutline,
+} from './first-course-creation-notice';
+import { getFirstBlockByName } from '../../blocks/course-outline/data';
+
+// Initial mocks.
+jest.mock( '@wordpress/blocks', () => ( {
+	createBlock: jest.fn().mockImplementation( () => ( {
+		attributes: {},
+		clientId: 'new-block-id',
+	} ) ),
+} ) );
+
+jest.mock( '@wordpress/data', () => ( {
+	dispatch: jest.fn().mockImplementation( () => ( {
+		createInfoNotice: jest.fn(),
+		removeNotice: jest.fn(),
+		insertBlock: jest.fn(),
+		selectBlock: jest.fn(),
+	} ) ),
+	select: jest.fn().mockImplementation( () => ( {
+		getCurrentUser: jest.fn(),
+		getBlocks: jest.fn(),
+	} ) ),
+	subscribe: jest.fn(),
+	use: jest.fn(),
+} ) );
+
+jest.mock( '@wordpress/i18n', () => ( {
+	...jest.requireActual( '@wordpress/i18n' ),
+	__: jest.fn(),
+} ) );
+
+jest.mock( './first-course-creation-notice' );
+jest.mock( '../../blocks/course-outline/data' );
+
+describe( 'hasPublishedLessonInOutline', () => {
+	beforeEach( () => {
+		hasLessonInOutline.mockImplementation(
+			jest.requireActual( './first-course-creation-notice' )
+				.hasLessonInOutline
+		);
+	} );
+
+	it( 'should return true when there is a lesson in the outline', () => {
+		const blocks = [
+			{
+				name: 'sensei-lms/course-outline-lesson',
+			},
+		];
+
+		const result = hasLessonInOutline( blocks );
+
+		expect( result ).toBe( true );
+	} );
+
+	it( 'should return false when there is no lesson in the outline', () => {
+		const blocks = [ { name: 'some-other-block' } ];
+
+		const result = hasLessonInOutline( blocks );
+
+		expect( result ).toBe( false );
+	} );
+} );
+
+describe( 'handleCourseOutlineBlockIncomplete', () => {
+	beforeEach( () => {
+		handleCourseOutlineBlockIncomplete.mockImplementation(
+			jest.requireActual( './first-course-creation-notice' )
+				.handleCourseOutlineBlockIncomplete
+		);
+		getFirstBlockByName.mockClear();
+		getOutlineBlock.mockClear();
+		createBlock.mockClear();
+	} );
+	it( 'should create and insert a block when no course outline block exists', () => {
+		// Mock hasOutlineBlock to return falsy.
+		getFirstBlockByName.mockImplementation( () => null );
+		const mockInsertBlock = jest.fn();
+		dispatch.mockImplementation( () => ( {
+			insertBlock: mockInsertBlock,
+			selectBlock: jest.fn(),
+		} ) );
+
+		handleCourseOutlineBlockIncomplete();
+
+		// Ensure createBlock and insertBlock were called with the correct parameters.
+		expect( createBlock ).toHaveBeenCalledWith(
+			'sensei-lms/course-outline'
+		);
+		expect( mockInsertBlock ).toHaveBeenCalled();
+	} );
+
+	it( 'should focus on the existing course outline block when it exists', () => {
+		// Mock hasOutlineBlock to return a truthy value.
+		getFirstBlockByName.mockImplementation( () => ( {
+			clientId: 'existing-block-id',
+		} ) );
+		const mockInsertBlock = jest.fn();
+		const mockSelectBlock = jest.fn();
+		dispatch.mockImplementation( () => ( {
+			insertBlock: mockInsertBlock,
+			selectBlock: mockSelectBlock,
+		} ) );
+
+		handleCourseOutlineBlockIncomplete();
+
+		// Ensure selectBlock was called with the correct parameters.
+		expect( mockSelectBlock ).toHaveBeenCalledWith( 'existing-block-id' );
+		// Ensure createBlock and insertBlock were not called.
+		expect( createBlock ).not.toHaveBeenCalled();
+		expect( mockInsertBlock ).not.toHaveBeenCalled();
+	} );
+} );

changelog/add-notice-to-create-course-outline-block-first-time

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Notice on Course editor for first course of a user guiding them to use Course Outline block properly

includes/class-sensei-course.php

@@ -448,10 +448,12 @@
 	/**
 	 * Register and enqueue scripts and styles that are needed in the backend.
 	 *
+	 * @param string $hook_suffix The current admin page.
+	 *
 	 * @access private
 	 * @since 2.1.0
 	 */
-	public function register_admin_scripts() {
+	public function register_admin_scripts( $hook_suffix ) {
 		$screen = get_current_screen();
 		if ( ! $screen ) {
 			return;
@@ -474,6 +476,38 @@
 				sprintf( 'window.sensei = window.sensei || {}; window.sensei.courseSettingsSidebar = %s;', $settings_sidebar ),
 				'before'
 			);
+
+			$lessons_by_user_args = array(
+				'author'         => get_current_user_id(),
+				'fields'         => 'all',
+				'meta_query'     => array( // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query -- Runs only once during Course editor loading.
+					array(
+						'key'     => '_lesson_course',
+						'value'   => 0,
+						'compare' => '>',
+					),
+				),
+				'posts_per_page' => 1,
+				'post_status'    => 'any',
+				'post_type'      => 'lesson',
+			);
+
+			$user_lessons_query       = new WP_Query( $lessons_by_user_args );
+			$has_lessons_with_courses = count( $user_lessons_query->posts ) > 0;
+
+			if ( ! $has_lessons_with_courses ) {
+				$post_id     = get_the_ID();
+				$new_post    = $post_id && get_post_meta( $post_id, '_new_post', true );
+				$is_new_post = 'post-new.php' === $hook_suffix || $new_post;
+
+				wp_add_inline_script(
+					'sensei-admin-course-edit',
+					sprintf( 'window.sensei = window.sensei || {}; window.sensei.isNewCourse = %s;', ( $is_new_post ? 'true' : 'false' ) ),
+					'before'
+				);
+
+				Sensei()->assets->enqueue( 'sensei-admin-first-course-creation-notice', 'js/admin/first-course-creation-notice.js', [ 'sensei-admin-course-edit' ], true );
+			}
 		}
 
 		if ( 'edit-course' === $screen->id ) {
@@ -694,6 +728,17 @@
 				'auth_callback' => [ $this, 'post_meta_auth_callback' ],
 			]
 		);
+		register_post_meta(
+			'course',
+			'_new_post',
+			[
+				'show_in_rest'  => true,
+				'single'        => true,
+				'type'          => 'boolean',
+				'default'       => false,
+				'auth_callback' => [ $this, 'post_meta_auth_callback' ],
+			]
+		);
 		/**
 		 * Sets up the meta fields saved on course save in WP admin.
 		 *

webpack.config.js

@@ -30,6 +30,7 @@ const files = [
 	'js/admin/course-edit.js',
 	'js/admin/course-index.js',
 	'js/admin/event-logging.js',
+	'js/admin/first-course-creation-notice.js',
 	'js/admin/lesson-bulk-edit.js',
 	'js/admin/lesson-quick-edit.js',
 	'js/admin/message-menu-fix.js',