Merge "[FEATURE] Demo Kit: Added FAQ section in ApiRef"

grunt/config/aliases.js

@@ -299,6 +299,7 @@ module.exports = function(grunt, config) {
 					return;
 				}
 				aTasks.push('jsdoc:library-' + library.name);
+				aTasks.push('copy:faq-target-' + library.name);
 				if (!useDefaultTemplate) {
 					aTasks.push('ui5docs-preprocess:library-' + library.name);
 				}
@@ -332,10 +333,10 @@ module.exports = function(grunt, config) {
 				downloadFolder = path.join(baseFolder, "tmp/cldr"),
 				pacote = require('pacote'),
 				done = this.async();
-			
+
 			Promise.all(aPakets.map(function(sName) {
 				return pacote.extract(sName + "@" + CLDR_VERSION, path.join(downloadFolder, sName));
-					
+
 			})).then(function() {
 				grunt.log.ok("DONE", "Files downloaded and extracted to", downloadFolder);
 				done();

grunt/config/copy.js

@@ -100,6 +100,16 @@ module.exports = function(grunt, config) {
 			};
 		}
 
+		copy['faq-target-' + library.name] = {
+			files: [ {
+				expand: true,
+				dot: true,
+				cwd: library.test,
+				src: '**/faq/*.md',
+				dest: 'target/openui5-sdk/test-resources'
+			} ]
+		};
+
 		if (library.bower !== false && grunt.option('publish')) {
 			copy['bower-' + library.name] = {
 				files: [

grunt/config/ui5docs-preprocess.js

@@ -18,13 +18,15 @@ module.exports = function(grunt, config) {
 		const libraryFile = path.join(targetPathSDK, 'resources', libraryPath, '.library');
 		const apiJsonFile = path.join(targetPathSDK, 'test-resources', libraryPath, 'designtime/api.json');
 		const transformedApiJsonFile = path.join(targetPathSDK, 'test-resources', libraryPath, 'designtime/apiref/api.json');
+		const faqDirectory = path.join(targetPathSDK, 'test-resources', libraryPath, 'demokit/faq');
 
 		// create target configuration
 		tasks['library-' + library.name] = {
 			options: {
 				source: apiJsonFile,
 				dest: transformedApiJsonFile,
-				lib: libraryFile
+				lib: libraryFile,
+				faqDirectory: faqDirectory
 			}
 		};
 

grunt/tasks/ui5docs-preprocess.js

@@ -43,7 +43,7 @@ module.exports = function(grunt) {
 		}
 		collectFromDir('target');
 
-		transformer(options.source,options.dest,options.lib, dependencyLibs)
+		transformer(options.source,options.dest,options.lib, dependencyLibs, options.faqDirectory)
 		.then(done, (err) => {
 			grunt.fail.warn(err);
 		});

lib/jsdoc/transformApiJson.js

@@ -35,9 +35,10 @@ const log = (function() {
  * @param {string} sLibraryFile Path to the .library file of the library, used to extract further documentation information
  * @param {string|string[]} vDependencyAPIFiles Path of folder that contains api.json files of predecessor libs or
  *                 an array of paths of those files
+ * @param {string} sFAQDir Path to the directory containing the sources for the FAQ section in APiRef
  * @returns {Promise} A Promise that resolves after the transformation has been completed
  */
-function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles, options) {
+function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles, sFAQDir, options) {
 	const fs = options && options.fs || require("fs");
 	const returnOutputFiles = options && !!options.returnOutputFiles;
 
@@ -46,6 +47,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	log.info("  output file: " + sOutputFile);
 	log.info("  library file: " + sLibraryFile);
 	log.info("  dependency dir: " + vDependencyAPIFiles);
+	log.info("  FAQ src dir: " + sFAQDir);
 	if (options && options.fs) {
 		log.info("Using custom fs.");
 	}
@@ -785,6 +787,25 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		})
 	}
 
+	/**
+	 * Check for existence of FAQ data
+	 * (FAQ data must be defined as *.md files in the <code>sFAQDir</code>)
+	 * and add a boolean flag in case it exists
+	 *
+	 * @param oChainObject chain object
+	 */
+	function addFlagsForFAQData(oChainObject) {
+		if (!sFAQDir) {
+			return oChainObject;
+		}
+		oChainObject.fileData.symbols.forEach(function(symbol) {
+			if (fs.existsSync(path.join(sFAQDir, symbol.basename + ".md"))) {
+				symbol.hasFAQ = true;
+			}
+		});
+		return oChainObject;
+	}
+
 	/**
 	 * Create api.json from parsed data
 	 * @param oChainObject chain object
@@ -946,7 +967,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		_sTopicId: "",
 		_oTopicData: {},
 		_baseTypes: [
-			// TODO this list URGENTLY needs to be replaced by the Type parser and a much smaller list 
+			// TODO this list URGENTLY needs to be replaced by the Type parser and a much smaller list
 			"sap.ui.core.any",
 			"sap.ui.core.object",
 			"sap.ui.core.function",
@@ -2019,6 +2040,7 @@ title="Information published on ${bSAPHosted ? '' : 'non '}SAP site" class="sapU
 		.then(getAPIJSONPromise)
 		.then(loadDependencyLibraryFiles)
 		.then(transformApiJson)
+		.then(addFlagsForFAQData)
 		.then(createApiRefApiJson);
 	return p;
 

src/sap.ui.documentation/src/sap/ui/documentation/sdk/controller/SubApiDetail.controller.js

@@ -103,6 +103,17 @@ sap.ui.define([
 					this._oModel.setProperty("/ui5-metadata/associations", bHasSelfAssoc ? this._selfAssociations : this._allAssociations);
 				}
 
+				if (this._oModel.getProperty("/hasFAQ")) {
+					jQuery.ajax({
+						type: "GET",
+						url: './docs/api/' + this._oEntityData.lib.replace(/\./g, '/') +
+						'/demokit/faq/' + this._oEntityData.displayName + '.html',
+						success: function (data) {
+							this._oModel.setProperty("/faqContent", data);
+						}.bind(this)
+					});
+				}
+
 				// Attach the model to the view
 				this.setModel(this._oModel);
 

src/sap.ui.documentation/src/sap/ui/documentation/sdk/view/SubApiDetail.view.xml

@@ -759,6 +759,18 @@
 						</ObjectPageSection>
 					</template:if>
 
+					<template:if test="{data>/hasFAQ}">
+						<ObjectPageSection id="faq" title="FAQ">
+							<subSections>
+								<custom:ObjectPageSubSection>
+									<custom:blocks>
+										<core:HTML id="parserId" content="{/faqContent}"/>
+									</custom:blocks>
+								</custom:ObjectPageSubSection>
+							</subSections>
+						</ObjectPageSection>
+					</template:if>
+
 					<core:ExtensionPoint name="customSections" />
 
 				</sections>