Class H5PEditor

constructor

• new H5PEditor(
      cache: IKeyValueStorage,
      config: IH5PConfig,
      libraryStorage: ILibraryStorage,
      contentStorage: IContentStorage,
      temporaryStorage: ITemporaryFileStorage,
      translationCallback?: ITranslationFunction,
      urlGenerator?: IUrlGenerator,
      options?: IH5PEditorOptions,
      contentUserDataStorage?: IContentUserDataStorage,
  ): H5PEditor

  Parameters

  • cache: IKeyValueStorage

    the cache is used to store key - value pairs that must be accessed often; values stored in it must be accessible by ALL instances of the editor (across machines)
  • config: IH5PConfig

    the configuration values for the editor; note that the editor can also change these values and save them!
  • libraryStorage: ILibraryStorage

    the storage object for libraries
  • contentStorage: IContentStorage

    the storage object for content
  • temporaryStorage: ITemporaryFileStorage

    the storage object for temporary files
  • translationCallback: ITranslationFunction = ...

    a function that is called to retrieve translations of keys in a certain language; the keys use the i18next format (e.g. namespace:key). See the ITranslationFunction documentation for more details.
  • urlGenerator: IUrlGenerator = ...

    creates url strings for files, can be used to customize the paths in an implementation application
  • Optionaloptions: IH5PEditorOptions

    more options to customize the behavior of the editor; see IH5PEditorOptions documentation for more details
  • OptionalcontentUserDataStorage: IContentUserDataStorage

  Returns H5PEditor

config

contentHub

contentManager

contentStorage

contentTypeCache

contentTypeRepository

contentUserDataManager

OptionalcontentUserDataStorage

libraryManager

libraryStorage

packageImporter

temporaryFileManager

temporaryStorage

cacheBusterGenerator

• cacheBusterGenerator(): string

  Generates cache buster strings that are used by the JavaScript client in the browser when generating URLs of core JavaScript files (only rarely used).

  If you want to customize cache busting, you can override this generator. The default generator creates strings like '?version=1.24.0', which are simply added to the URL.

  Returns string

deleteContent

• deleteContent(contentId: string, user: IUser): Promise<void>

  Deletes a piece of content and all files dependent on it.

  Parameters

  • contentId: string

    the piece of content to delete
  • user: IUser

    the user who wants to delete it

  Returns Promise<void>

exportContent

• exportContent(
      contentId: string,
      outputWritable: Writable,
      user: IUser,
  ): Promise<void>

  Creates a .h5p-package for the specified content file and pipes it to the stream. Throws H5pErrors if something goes wrong. The contents of the stream should be disregarded then.

  IMPORTANT: This method's returned promise will resolve BEFORE piping to the writeable has been finished. If you outputStream is directly piped to a download that's not an issue, but if you do something else with this stream, you have to wait for the piping to finish by subscribing to the 'finish' event of the stream!

  Parameters

  • contentId: string

    The contentId for which the package should be created.
  • outputWritable: Writable

    The writable that the package is written to (e.g. the response stream fo Express)
  • user: IUser

  Returns Promise<void>

getContent

• getContent(
      contentId: string,
      user?: IUser,
  ): Promise<
      {
          h5p: IContentMetadata;
          library: string;
          params: { metadata: IContentMetadata; params: any };
      },
  >

  Returns all the data needed to editor or display content

  Parameters

  • contentId: string

    the content id
  • Optionaluser: IUser

    (optional) the user who wants to access the content; if undefined, access will be granted

  Returns Promise<
      {
          h5p: IContentMetadata;
          library: string;
          params: { metadata: IContentMetadata; params: any };
      },
  >

  all relevant information for the content (you can send it back to the GET request for content)

getContentFileStream

• getContentFileStream(
      contentId: string,
      filename: string,
      user: IUser,
      rangeStart?: number,
      rangeEnd?: number,
  ): Promise<Readable>

  Returns a readable for a file that was uploaded for a content object. The requested content file can be a temporary file uploaded for unsaved content or a file in permanent content storage.

  Parameters

  • contentId: string

    the content id (undefined if retrieved for unsaved content)
  • filename: string

    the file to get (without 'content/' prefix!)
  • user: IUser

    the user who wants to retrieve the file
  • OptionalrangeStart: number

    (optional) the position in bytes at which the stream should start
  • OptionalrangeEnd: number

    (optional) the position in bytes at which the stream should end

  Returns Promise<Readable>

  a readable of the content file

getContentHubContent

• getContentHubContent(
      contentHubId: string,
      user: IUser,
  ): Promise<
      {
          installedLibraries: ILibraryInstallResult[];
          metadata?: IContentMetadata;
          parameters?: any;
      },
  >

  Downloads a .h5p file from the content hub. Then "uploads" the file as if the user uploaded the file manually.

  Parameters

  • contentHubId: string

    the content hub id; this is a id of the external service and not related to local contentId
  • user: IUser

    the user who is using the content hub; relevant for temporary file access rights

  Returns Promise<
      {
          installedLibraries: ILibraryInstallResult[];
          metadata?: IContentMetadata;
          parameters?: any;
      },
  >

  the content information extracted from the package.

getContentTypeCache

• getContentTypeCache(user: IUser, language?: string): Promise<IHubInfo>

  Returns the content type cache for a specific user. This includes all available content types for the user (some might be restricted) and what the user can do with them (update, install from Hub).

  Parameters

  • user: IUser
  • Optionallanguage: string

  Returns Promise<IHubInfo>

getLibraryData

• getLibraryData(
      machineName: string,
      majorVersion: string,
      minorVersion: string,
      language?: string,
  ): Promise<ILibraryDetailedDataForClient>

  Returns detailed information about an installed library.

  Parameters

  • machineName: string
  • majorVersion: string
  • minorVersion: string
  • language: string = 'en'

  Returns Promise<ILibraryDetailedDataForClient>

getLibraryFileStream

• getLibraryFileStream(library: ILibraryName, filename: string): Promise<Readable>

  Returns a readable stream of a library file's contents. Throws an exception if the file does not exist.

  Parameters

  • library: ILibraryName

    library
  • filename: string

    the relative path inside the library

  Returns Promise<Readable>

  a readable stream of the file's contents

getLibraryOverview

• getLibraryOverview(
      ubernames: string[],
      language?: string,
  ): Promise<ILibraryOverviewForClient[]>

  Gets a rough overview of information about the requested libraries.

  Parameters

  • ubernames: string[]
  • Optionallanguage: string

    (optional) if set, the system will try to localize the title of the library (the namespace 'library-metadata' must be loaded in the i18n system)

  Returns Promise<ILibraryOverviewForClient[]>

installLibraryFromHub

• installLibraryFromHub(
      machineName: string,
      user: IUser,
  ): Promise<ILibraryInstallResult[]>

  Installs a content type from the H5P Hub.

  Parameters

  • machineName: string

    The name of the content type to install (e.g. H5P.Test) Note that this is not a full ubername!
  • user: IUser

  Returns Promise<ILibraryInstallResult[]>

  a list of installed libraries if successful. Will throw errors if something goes wrong.

listLibraryLanguageFiles

• listLibraryLanguageFiles(
      libraryUbernames: string[],
      language: string,
  ): Promise<{ [key: string]: string }>

  Retrieves the installed languages for libraries

  Parameters

  • libraryUbernames: string[]

    A list of libraries for which the language files should be retrieved. In this list the names of the libraries don't use hyphens to separate machine name and version.
  • language: string

    the language code to get the files for

  Returns Promise<{ [key: string]: string }>

  The strings of the language files

render

• render(contentId: string, language?: string, user: IUser): Promise<any>

  Renders the content. This means that a frame in which the editor is displayed is generated and returned. You can override the default frame by calling setRenderer(...).

  Parameters

  • contentId: string
  • language: string = 'en'

    the language to use; defaults to English
  • user: IUser

    the user who uses the editor

  Returns Promise<any>

  the rendered frame that you can include in your website. Normally a string, but can be anything you want it to be if you override the renderer.

saveContentFile

• saveContentFile(
      contentId: string,
      field: ISemanticsEntry,
      file: {
          data?: Buffer;
          mimetype: string;
          name: string;
          size: number;
          tempFilePath?: string;
      },
      user: IUser,
  ): Promise<{ height?: number; mime: string; path: string; width?: number }>

  Stores an uploaded file in temporary storage.

  Parameters

  • contentId: string

    the id of the piece of content the file is attached to; Set to null/undefined if the content hasn't been saved before.
  • field: ISemanticsEntry

    the semantic structure of the field the file is attached to.
  • file: {
        data?: Buffer;
        mimetype: string;
        name: string;
        size: number;
        tempFilePath?: string;
    }

    information about the uploaded file; either data or tempFilePath must be used!
  • user: IUser

  Returns Promise<{ height?: number; mime: string; path: string; width?: number }>

  information about the uploaded file

saveOrUpdateContent

• saveOrUpdateContent(
      contentId: string,
      parameters: any,
      metadata: IContentMetadata,
      mainLibraryUbername: string,
      user: IUser,
  ): Promise<string>

  Stores new content or updates existing content. Copies over files from temporary storage if necessary.

  Parameters

  • contentId: string

    the contentId of existing content (undefined or previously unsaved content)
  • parameters: any

    the content parameters (=content.json)
  • metadata: IContentMetadata

    the content metadata (~h5p.json)
  • mainLibraryUbername: string

    the ubername with whitespace as separator (no hyphen!)
  • user: IUser

    the user who wants to save the piece of content

  Returns Promise<string>

  the existing contentId or the newly assigned one

saveOrUpdateContentReturnMetaData

• saveOrUpdateContentReturnMetaData(
      contentId: string,
      parameters: any,
      metadata: IContentMetadata,
      mainLibraryUbername: string,
      user: IUser,
  ): Promise<{ id: string; metadata: IContentMetadata }>

  Stores new content or updates existing content. Copies over files from temporary storage if necessary.

  Parameters

  • contentId: string

    the contentId of existing content (undefined or previously unsaved content)
  • parameters: any

    the content parameters (=content.json)
  • metadata: IContentMetadata

    the content metadata (~h5p.json)
  • mainLibraryUbername: string

    the ubername with whitespace as separator (no hyphen!)
  • user: IUser

    the user who wants to save the piece of content

  Returns Promise<{ id: string; metadata: IContentMetadata }>

  the existing contentId or the newly assigned one and the metatdata

setCopyrightSemantics

• setCopyrightSemantics(copyrightSemantics: ISemanticsEntry): H5PEditor

  By setting custom copyright semantics, you can customize what licenses are displayed when editing metadata of files.

  NOTE: It is unclear if copyrightSemantics is deprecated in the H5P client. Use setMetadataSemantics instead, which certainly works.

  NOTE: The semantic structure is localized before delivered to the H5P client. If you change it, you must either make sure there is a appropriate language file loaded in your translation library (and set one in the first place).

  Parameters

  • copyrightSemantics: ISemanticsEntry

    a semantic structure similar to the one used in semantics.json of regular H5P libraries. See https://h5p.org/semantics for more documentation. However, you can only add one entry (which can be nested). See the file assets/defaultCopyrightSemantics.json for the default version which you can build on.

  Returns H5PEditor

  the H5PEditor object that you can use to chain method calls

setMetadataSemantics

• setMetadataSemantics(metadataSemantics: ISemanticsEntry[]): H5PEditor

  By setting custom metadata semantics, you can customize what licenses are displayed when editing metadata of content object and files.

  NOTE: It is only trivial to change the license offered as a a selection to the editors. All other semantic entries CANNOT be changed, as the form displayed in the editor is hard-coded in h5peditor-metadata.js in the client. You'll have to replace this file with a custom implementation if you want to change more metadata.

  NOTE: The semantic structure is localized before delivered to the H5P client. If you change it, you must either make sure there is a appropriate language file loaded in your translation library (and set one in the first place).

  Parameters

  • metadataSemantics: ISemanticsEntry[]

    a semantic structure similar to the one used in semantics.json of regular H5P libraries. See https://h5p.org/semantics for more documentation. See the file assets/defaultMetadataSemantics.json for the default version which you can build on

  Returns H5PEditor

  the H5PEditor object that you can use to chain method calls

setRenderer

• setRenderer(renderer: (model: IEditorModel) => any): H5PEditor

  By setting a custom renderer you can change the way the editor produces HTML output

  Parameters

  • renderer: (model: IEditorModel) => any

  Returns H5PEditor

  the H5PEditor object that you can use to chain method calls

uploadPackage

• uploadPackage(
      dataOrPath: string | Buffer<ArrayBufferLike>,
      user?: IUser,
      options?: { onlyInstallLibraries?: boolean },
  ): Promise<
      {
          installedLibraries: ILibraryInstallResult[];
          metadata?: IContentMetadata;
          parameters?: any;
      },
  >

  Adds the contents of a package to the system: Installs required libraries (if the user has the permissions for this), adds files to temporary storage and returns the actual content information for the editor to process. Throws errors if something goes wrong.

  Parameters

  • dataOrPath: string | Buffer<ArrayBufferLike>

    the raw data of the h5p package as a buffer or the path of the file in the local filesystem
  • Optionaluser: IUser

    the user who is uploading the package; optional if onlyInstallLibraries is set to true
  • Optionaloptions: { onlyInstallLibraries?: boolean }

    (optional) further options:

  Returns Promise<
      {
          installedLibraries: ILibraryInstallResult[];
          metadata?: IContentMetadata;
          parameters?: any;
      },
  >

  the content information extracted from the package. The metadata and parameters property will be undefined if onlyInstallLibraries was set to true.