@davidlj95/ngx-meta
Version:
Set your Angular site's metadata: standard meta tags, Open Graph, Twitter Cards, JSON-LD structured data and more. Supports SSR (and Angular Universal). Use a service. Use routes' data. Set it up in a flash! 🚀
1,411 lines (1,406 loc) • 46.8 kB
TypeScript
// Generated by dts-bundle-generator v9.5.1
import * as i0 from '@angular/core';
import { EnvironmentProviders, FactoryProvider, InjectionToken, ModuleWithProviders, Provider } from '@angular/core';
import { Meta, MetaDefinition } from '@angular/platform-browser';
/**
* Metadata values to use for a page.
*
* Broadly speaking, it's just a JSON object.
*
* See the {@link https://ngx-meta.dev/guides/metadata-values-json/ | metadata values JSON}
* guide for more information about typing metadata values JSON with stricter types
*
* @public
*/
export type MetadataValues = object;
/**
* Abstract class every metadata manager must implement.
*
* Used as {@link https://angular.dev/guide/di/dependency-injection-providers#using-an-injectiontoken-object | injection token}
* to provide metadata managers the library will take into account.
*
* @remarks
*
* See also:
*
* - {@link https://ngx-meta.dev/guides/manage-your-custom-metadata/ | Manage your custom metadata guide}
*
* - {@link makeMetadataManagerProviderFromSetterFactory} for a helper to create a metadata manager
*
* - {@link provideNgxMetaManager} for an experimental helper to create a metadata manager
*
* @typeParam Value - Value type that can be handled by the setter
*
* @public
*/
export declare abstract class NgxMetaMetadataManager<Value = unknown> {
/**
* Identifies the metadata manager.
*
* Used to avoid setting same metadata twice in case same two managers are
* injected by mistake.
*/
abstract readonly id: string;
/**
* {@inheritDoc MetadataResolverOptions}
*/
abstract readonly resolverOptions: MetadataResolverOptions;
/**
* A function that alters a page's metadata with the provided value.
*/
abstract readonly set: MetadataSetter<Value>;
}
/**
* @internal
*/
export declare const _injectMetadataManagers: () => readonly NgxMetaMetadataManager[];
/**
* Options to resolve metadata values for a metadata manager
*
* Used in {@link NgxMetaMetadataManager.resolverOptions} with type {@link MetadataResolverOptions}
*
* @public
*/
export interface MetadataResolverOptions {
/**
* JSON path to use to access a metadata values JSON object when resolving a metadata value.
*
* @example
* The following JSON path
*
* ```typescript
* const jsonPath = `['foo', 'bar']`
* ```
*
* When resolving the following sample metadata values JSON
*
* ```typescript
* const metadataValues = {
* foo: {
* bar: 'fooBar'
* }
* }
* ```
*
* Would access the `bar` key inside the `foo` object and resolve `fooBar` as metadata value
*/
readonly jsonPath: readonly string[];
/**
* Global key in a metadata values object to use when resolving a metadata value.
*
* @example
* The following global
*
* ```typescript
* const global = 'foo'
* ```
*
* When resolving the following sample metadata values JSON
*
* ```typescript
* const metadataValues = {
* foo: 'bar'
* }
* ```
*
* Would access the `foo` global key and resolve `bar` as metadata value
*
* Defaults to `undefined` (no global to be used for the metadata manager)
*/
readonly global?: string;
/**
* Enables merging the metadata value when it's an object and multiple values are found
*
* @example
*
* Given a metadata manager whose:
*
* - {@link MetadataResolverOptions.jsonPath} is `['foo', 'bar']`
*
* - {@link MetadataResolverOptions.global} is `bar`
*
* Then resolving the following metadata values:
*
* ```typescript
* const metadataValues = {
* bar: {a: 'a', b: 'b'},
* foo: {
* bar: { b: 'B', c: 'C'}
* }
* }
* ```
*
* Would resolve to two objects (the JSON path one and the global one).
*
* If specifying both, specific JSON path one will take preference (as mentioned in the
* {@link https://ngx-meta.dev/guides/metadata-values-json/#combining-both | metadata values JSON guide}).
*
* So it would resolve to `{ b: 'B', c: 'C' }`. However, when enabling object merging, both objects resolved
* are merged (with specific one taking preference too). Therefore, final value resolved would be
* `{ a: 'a', b: 'B', c: 'C' }`
*
* This merging also happens when objects are found during defaults and route values resolution.
*/
readonly objectMerge?: boolean;
}
/**
* See {@link NgxMetaMetadataManager.set}
*
* @typeParam T - Value type the setter accepts as argument
*
* @public
*/
export type MetadataSetter<T> = (value: T) => void;
/**
* Typescript's type guard helper to ensure a value is neither `null` nor `undefined`.
*
* @param value - Value to check
*
* @internal
*/
export declare const _isDefined: <T>(value: T | null | undefined) => value is T;
/**
* Thunk to delay the instantiation of a new injection token.
*
* This way the injection token and its factory definition can be tree-shaken if unused.
* As their factory functions can bring many unused bytes to the production bundle.
*
* See also:
*
* - {@link https://github.com/davidlj95/ngx/pull/892 | PR where need for this was discovered}
*
* - {@link https://en.wikipedia.org/wiki/Thunk | Thunk definition (computer science)}
*
* - {@link https://github.com/davidlj95/ngx/pull/903 | Why can't create a helper function to create them}
*
* @internal
*/
export type _LazyInjectionToken<T> = () => InjectionToken<T>;
/**
* Creates an injection token with the given factory function if it doesn't exist.
* To determine if an injection token exists, the description string is used.
*
* Useful to create {@link _LazyInjectionToken}s.
* \> The function can't be used to create a lazy injection token directly
* \> As a function call won't be tree-shaken. Which is the main purpose of lazy tokens.
* \> More in https://github.com/davidlj95/ngx/pull/902
*
* It also adds the library name as prefix to the injection token description.
* In order to locate library's injectable easily when debugging an Angular project.
*
* @internal
*/
export declare const _makeInjectionToken: <T>(description: string, factory?: () => T) => InjectionToken<T>;
/**
* Helper function to combine multiple options (objects).
*
* In case of specifying same options more than once, the latter one will take precedence.
* Provide them sorted by ascendant priority. Less priority options first. Top priority options last.
*
* Can be used to combine options for:
*
* - {@link provideNgxMetaManager}
*
* @param options - Options to combine.
*
* @public
*/
export declare const withOptions: <T extends object>(...options: readonly T[]) => T;
interface MetadataRegistry {
readonly register: (manager: NgxMetaMetadataManager) => void;
readonly getAll: () => Iterable<NgxMetaMetadataManager>;
readonly findByGlobalOrJsonPath: (globalOrJsonPath: string) => Iterable<NgxMetaMetadataManager>;
}
/**
* Utility type for a factory function that returns a {@link MetadataSetter} given some injectable dependencies.
*
* Used as part of {@link makeMetadataManagerProviderFromSetterFactory}.
*
* @public
*/
export type MetadataSetterFactory<T> = (...deps: Exclude<FactoryProvider["deps"], undefined>) => MetadataSetter<T>;
/**
* Creates an Angular {@link https://angular.dev/guide/di/dependency-injection-providers#factory-providers-usefactory | factory provider}
* providing an {@link NgxMetaMetadataManager}.
*
* See {@link https://ngx-meta.dev/guides/manage-your-custom-metadata/ | manage custom metadata guide} for an example.
*
* @deprecated Use {@link provideNgxMetaManager} APIs instead.
* See {@link https://ngx-meta.dev/migrations/02-manager-provider-apis/ } for more information.
*
* @remarks
*
* Factory providers are used for built-in modules instead of Angular services.
* Reason is that code created by `@Injectable` decorator takes many bytes,
* whereas a call to this function creating a factory provider takes fewer.
*
* See {@link https://github.com/davidlj95/ngx/issues/112}
*
* @param setterFactory - Function that creates a {@link NgxMetaMetadataManager} given some dependencies
* @param opts - Options to create the factory
* @public
*/
export declare const makeMetadataManagerProviderFromSetterFactory: <T>(setterFactory: MetadataSetterFactory<T>, opts: MakeMetadataManagerProviderFromSetterFactoryOptions) => FactoryProvider;
/**
* Options argument object for {@link makeMetadataManagerProviderFromSetterFactory}.
*
* @deprecated Use {@link provideNgxMetaManager} APIs instead.
* See {@link https://ngx-meta.dev/migrations/02-manager-provider-apis/ } for more information.
*
* @public
*/
export interface MakeMetadataManagerProviderFromSetterFactoryOptions {
/**
* Dependencies to inject to the setter factory.
*
* See also:
*
* - {@link https://angular.dev/guide/di/dependency-injection-providers#factory-providers-usefactory:~:text=property%20is%20an%20array%20of%20provider%20tokens | Factory providers' deps}
*
* - {@link https://angular.dev/api/core/FactoryProvider#deps | FactoryProvider#deps}
*
* Defaults to no dependencies
*/
d?: FactoryProvider["deps"];
/**
* Metadata manager identifier
*
* See {@link NgxMetaMetadataManager.id}
*
* Defaults to the JSON path joined by dots (`['standard', 'title'] => 'standard.title'`)
*/
id?: string;
/**
* See {@link MetadataResolverOptions.jsonPath}
*/
jP: MetadataResolverOptions["jsonPath"];
/**
* See {@link MetadataResolverOptions.global}
*/
g?: MetadataResolverOptions["global"];
/**
* See {@link MetadataResolverOptions.objectMerge}
*/
m?: MetadataResolverOptions["objectMerge"];
}
/**
* Specifies image metadata (will be used for link previews / social cards)
* to be used for more than one module. Like:
*
* - {@link OpenGraph.image} (needs standard module)
*
* - {@link TwitterCard.image} (needs Twitter Cards module)
*
* Open Graph allows for more attributes for the image.
* Specify {@link OpenGraph.image} if you want to customize those too.
*
* @remarks
*
* Used in {@link GlobalMetadata.image} with type {@link GlobalMetadataImage}
*
* @public
*/
export interface GlobalMetadataImage {
/**
* URL of the image. Used for:
*
* - {@link OpenGraphImage.url} (needs Open Graph module)
*
* - {@link TwitterCardImage.url} (needs Twitter Cards module)
*/
readonly url: string | URL;
/**
* A description of what is in the image (not a caption) to users who are
* visually impaired.
*
* Used for:
*
* - {@link OpenGraphImage.alt} (needs Open Graph module)
*
* - {@link TwitterCardImage.alt} (needs Twitter Cards module)
*/
readonly alt: string;
}
/**
* Indicate Angular's router URL shall be used to set the page's URL as a
* metadata value.
*
* Needs {@link https://ngx-meta.dev/guides/url-resolution/ | URL resolution}
* feature enabled for the feature to work
*
* A type alias exists to avoid using `typeof` around {@link AngularRouterUrl}
*
* @public
*/
export declare const ANGULAR_ROUTER_URL: unique symbol;
/**
* Type alias for {@link ANGULAR_ROUTER_URL} symbol
*
* @public
*/
export type AngularRouterUrl = typeof ANGULAR_ROUTER_URL;
/**
* Base URL type for {@link withNgxMetaBaseUrl} feature
*
* @public
*/
export type BaseUrl = string;
/**
* Resolves relative URLs into absolute URLs if a base URL was provided.
* Otherwise, acts as a no-op and returns the input as is.
*
* Absolute URLs, nulls and undefined are also returned as is.
*
* @internal
*/
export declare const _urlResolver: _LazyInjectionToken<_UrlResolver>;
/**
* @internal
*/
export type _UrlResolver = (url: URL | string | undefined | null | AngularRouterUrl) => string | undefined | null;
declare const enum CoreFeatureKind {
Defaults = 0,
BaseUrl = 1,
TitleFormatter = 2
}
interface CoreFeature<FeatureKind extends CoreFeatureKind> {
_kind: FeatureKind;
_providers: Provider[];
}
type CoreFeatures = readonly CoreFeature<CoreFeatureKind>[];
/**
* Provides a base URL to enable resolving relative URLs. Including relative
* URLs provided by Angular's router.
*
* Metadata values requiring absolute URLs may accept relative URLs then.
* Internally, the library will turn the relative URL into an absolute URL
* using the base URL as prefix.
*
* The special value {@link ANGULAR_ROUTER_URL} can be used to query the
* Angular's router URL to be used as relative URL. Which with the feature
* enabled will be resolved into an absolute URL. Do not use the value if the
* feature isn't enabled. Otherwise, an invalid URL may end up used as
* metadata value.
*
* @example
*
* <b>Using standalone, recommended API</b>
* ```typescript
* provideNgxMetaCore(
* withNgxMetaBaseUrl('https://example.com')
* )
* ```
*
* <b>Using module-based API</b>
* ```typescript
* NgxMetaCoreModule.forRoot(
* withNgxMetaBaseUrl('https://example.com')
* )
* ```
*
* See also:
*
* - {@link provideNgxMetaCore}: to use it with the standalone, recommended API.
*
* - {@link NgxMetaCoreModule.(forRoot:1)}: to use it with the module-based API.
*
* - {@link https://ngx-meta.dev/guides/url-resolution/ | URL resolution guide}
*
*
* @param baseUrl - Prefix URL to use when relative URLs are used in metadata
* values where an absolute URL is preferred or required.
*
* @public
*/
export declare const withNgxMetaBaseUrl: (baseUrl: BaseUrl) => CoreFeature<CoreFeatureKind.BaseUrl>;
/**
* Specifies metadata that will be used by more than one module.
*
* @public
*/
export interface GlobalMetadata {
/**
* Sets title for:
*
* - {@link Standard.title} (needs standard module)
*
* - {@link OpenGraph.title} (needs Open Graph module)
*
* - {@link TwitterCard.title} (needs Twitter Cards module)
*
* Title will be formatted for all of them when
* {@link https://ngx-meta.dev/guides/title-formatting | title formatting} is set up.
*/
readonly title?: string;
/**
* Sets description for:
*
* - {@link Standard.description} (needs standard module)
*
* - {@link OpenGraph.description} (needs Open Graph module)
*
* - {@link TwitterCard.description} (needs Twitter Cards module)
*/
readonly description?: string | null;
/**
* Sets application name for:
*
* - {@link Standard.applicationName} (needs standard module)
*
* - {@link OpenGraph.siteName} (needs Open Graph module)
*/
readonly applicationName?: string | null;
/**
* Sets canonical URL for:
*
* - {@link Standard.canonicalUrl} (needs standard module)
*
* - {@link OpenGraph.url} (needs Open Graph module)
*
* If {@link https://ngx-meta.dev/guides/url-resolution/ | URL resolution} feature is enabled, you may use
* a relative URL here. It will be resolved and the absolute URL will be used instead.
*
* You can also use the special value {@link ANGULAR_ROUTER_URL} to use the current Angular router's URL
* as the relative URL to be resolved into an absolute one.
*/
readonly canonicalUrl?: URL | AngularRouterUrl | string | null;
/**
* Sets localization of this page.
*
* Value must be a valid language tag complying with BCP 47.
* For instance: "`es`" or "`es-ES`"
*
* For:
*
* - {@link Standard.locale} (needs standard module)
*
* - {@link OpenGraph.locale} (needs Open Graph module)
*
* @remarks
*
* See also:
*
* - {@link https://datatracker.ietf.org/doc/html/rfc5646 | RFC 5646 / BCP 47}
*/
readonly locale?: string | null;
/**
* {@inheritDoc GlobalMetadataImage}
*/
readonly image?: GlobalMetadataImage | null;
}
/**
* @internal
*/
export declare const _GLOBAL_TITLE = "title";
/**
* @internal
*/
export declare const _GLOBAL_DESCRIPTION = "description";
/**
* @internal
*/
export declare const _GLOBAL_APPLICATION_NAME = "applicationName";
/**
* @internal
*/
export declare const _GLOBAL_CANONICAL_URL = "canonicalUrl";
/**
* @internal
*/
export declare const _GLOBAL_LOCALE = "locale";
/**
* @internal
*/
export declare const _GLOBAL_IMAGE = "image";
type StringKeyOf<T = object> = Extract<keyof T, string>;
/**
* Creates an {@link NgxMetaMetadataManager} provider to manage some metadata.
*
* Check out {@link https://ngx-meta.dev/guides/manage-your-custom-metadata/ | manage your custom metadata guide} to
* learn how to provide your custom metadata managers.
*
* @remarks
*
* Options can be specified using helper functions. {@link withOptions} can be used to combine more than one.
*
* Available option functions:
*
* - {@link withManagerDeps}
*
* - {@link withManagerGlobal}
*
* - {@link withManagerObjectMerging}
*
* @example
*
* ```typescript
* const CUSTOM_TITLE_PROVIDER = provideNgxMetaManager<string | undefined>(
* 'custom.title',
* (metaElementsService: NgxMetaElementsService) => (value) => {
* metaElementsService.set(
* withNameAttribute('custom:title'),
* withContentAttribute(value),
* )
* },
* withOptions(
* withManagerDeps(NgxMetaElementsService),
* withGlobal('title'),
* ),
* )
* ```
*
* @param jsonPath - Path to access the metadata value this manager needs given a JSON object
* containing metadata values. Path is expressed as the keys to use to access the value
* joined by a "." character.
* You can use {@link withManagerJsonPath} to provide an array of keys instead.
* For more information, checkout {@link MetadataResolverOptions.jsonPath}
* @param setterFactory - Factory function that creates the {@link MetadataSetter} function for the manager (which
* manages the metadata element on the page).
* You can inject dependencies either using {@link withManagerDeps} option, that will be passed
* as arguments to the setter factory function. This way is preferred, as takes fewer bytes of
* your bundle size. However, type safety depends on you.
* Or use {@link https://angular.dev/api/core/inject | Angular's `inject` function} for a more
* type-safe option.
* @param options - Extra options for the metadata manager provider creation. Use one of the helpers listed in this
* method's reference docs to supply one or more of them.
* @public
*/
export declare const provideNgxMetaManager: <T>(jsonPath: string, setterFactory: MetadataSetterFactory<T>, options?: _ProvideNgxMetaManagerOptions) => Provider;
/**
* @internal
*/
export type _ProvideNgxMetaManagerOptions = Partial<{
d: FactoryProvider["deps"];
g: MetadataResolverOptions["global"];
i: NgxMetaMetadataManager["id"];
o: MetadataResolverOptions["objectMerge"];
}>;
/**
* Specifies dependencies to inject to the setter factory function passed to {@link provideNgxMetaManager}
*
* See also:
*
* - {@link https://angular.dev/guide/di/dependency-injection-providers#factory-providers-usefactory:~:text=property%20is%20an%20array%20of%20provider%20tokens | Factory providers' deps}
*
* - {@link https://angular.dev/api/core/FactoryProvider#deps | FactoryProvider#deps}
*
* @param deps - Dependencies to inject. Each argument declares the dependency to inject.
*
* @public
*/
export declare const withManagerDeps: (...deps: Exclude<FactoryProvider["deps"], undefined>) => _ProvideNgxMetaManagerOptions;
/**
* Sets the global key to use for a metadata manager created with {@link provideNgxMetaManager}
*
* @param global - See {@link MetadataResolverOptions.global}
*
* @public
*/
export declare const withManagerGlobal: <G extends string = keyof GlobalMetadata>(global: G) => _ProvideNgxMetaManagerOptions;
/**
* Enables object merging for the manager being created with {@link provideNgxMetaManager}
*
* See {@link MetadataResolverOptions.objectMerge} for more information.
*
* @public
*/
export declare const withManagerObjectMerging: () => _ProvideNgxMetaManagerOptions;
/**
* Transforms a JSON Path specified as an array of keys into a string joined by dots.
*
* Useful to use with {@link provideNgxMetaManager} to avoid repeating same keys around.
*
* @remarks
*
* You can specify a type to ensure the keys are valid. See example below.
*
* Beware that specifying a type won't work if:
*
* The type refers other types and more than 2 levels are specified:
*
* ```typescript
* interface CustomMetadata { custom: Custom }
* interface Custom { moar: Moar }
*
* // 👇❌ Reports incorrect Typescript error about `never` type
* withManagerJsonPath<CustomMetadata>('custom', 'moar', 'foo')
* ```
*
* More than 3 keys are specified:
*
* ```typescript
* interface CustomMetadata {
* custom: {
* moar: {
* moarThanMoar: {
* foo: string
* }
* }
* }
* }
*
* // 👇❌ Reports incorrect Typescript error about `never` type
* withManagerJsonPath<CustomMetadata>('custom', 'moar', 'moarThanMoar', 'foo') //
* ```
*
* Omit the type to skip type checking and its limitations:
*
* ```typescript
* withManagerJsonPath('whatever', 'untyped', 'keys')
* ```
*
* @example
*
* ```typescript
* interface CustomMetadata {
* custom: {
* title: string
* }
* }
*
* withManagerJsonPath<CustomMetadata>('custom','title') // ✅ No error. IDE helps you auto-complete.
* withManagerJsonPath<CustomMetadata>('custom','not-a-prop') // ❌ Typescript error
* withManagerJsonPath('no', 'type', 'checks')
* ```
*
* @param jsonPath - Parts of the JSON Path to join into a string.
*
* @public
*/
export declare const withManagerJsonPath: WithManagerJsonPath;
interface WithManagerJsonPath {
<T extends object>(key1: StringKeyOf<T>): string;
<T extends object>(key1: StringKeyOf<T>, key2: StringKeyOf<T[typeof key1]>): string;
<T extends object>(key1: StringKeyOf<T>, key2: StringKeyOf<T[typeof key1]>, key3: StringKeyOf<T[typeof key1][typeof key2]>): string;
(...jsonPaths: readonly string[]): string;
}
/**
* Models a `<meta>` element which {@link NgxMetaMetaService.set} can manage
*
* To create one, you may also use one of these utility functions:
*
* - {@link makeKeyValMetaDefinition}
*
* - {@link makeComposedKeyValMetaDefinition}
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @remarks
*
* Inspired by Angular {@link https://angular.dev/api/platform-browser/MetaDefinition | MetaDefinition}.
*
* @public
*/
export interface NgxMetaMetaDefinition {
/**
* Creates an Angular {@link https://angular.dev/api/platform-browser/MetaDefinition | MetaDefinition}
* to create or update the element in the page.
*
* With the given content as value of the `<meta>` element.
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @example
* For instance, `(content) => ({name: 'description', content})` to create a
* `<meta name='description' content='{content}'>` element. Where `content` will come from
* {@link NgxMetaMetaService.set} second argument value.
*/
readonly withContent: (content: string) => MetaDefinition;
/**
* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors | Attribute selector}
* to identify the `<meta>` element. In order to remove this specific `<meta>` element when needed.
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @example
* For instance, `[name='description']` for the `<meta name='description'>` element.
*/
readonly attrSelector: string;
}
/**
* Creates a {@link NgxMetaMetaDefinition} for its use with {@link NgxMetaMetaService}
* by understanding `<meta>` elements as key / value pair elements.
*
* @remarks
*
* One can think about some `<meta>` elements as key / value pairs.
*
* For instance `<meta name='description' content='Lorem ipsum'>` would
* actually be a key / value pair meta where
* - `description` is the key
* - `Lorem ipsum` is the value
* - `name` is the key's HTML attribute name
* - `content`is the value's HTML attribute name
*
* Value is set by {@link NgxMetaMetaService.set} by providing this model and an
* actual value
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @param keyName - Name of the key in the key/value meta definition
* @param options - Specifies HTML attribute names and extras of the definition if any
*
* @public
*/
export declare const makeKeyValMetaDefinition: (keyName: string, options?: MakeKeyValMetaDefinitionOptions) => NgxMetaMetaDefinition;
/**
* Options argument object for {@link makeKeyValMetaDefinition}
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @public
*/
export interface MakeKeyValMetaDefinitionOptions {
/**
* Name of the `<meta>` attribute that will hold the key
*
* Default value is `name`
*/
keyAttr?: string;
/**
* Name of the `<meta>` attribute that will hold the value
*
* Default value is `content`
*/
valAttr?: string;
/**
* Extra contents for the meta definition
*
* Default value is `undefined`
*/
extras?: MetaDefinition;
}
/**
* Creates a key / value meta definition ({@link NgxMetaMetaDefinition})
* where the key name is composed by several strings joined by a separator.
*
* See also {@link makeKeyValMetaDefinition}
*
* @example
* For instance, Open Graph's meta definition for property `og:title` (hence
* element `<meta property='og:title'>`) is composed of `og` and `title`.
* Its {@link NgxMetaMetaDefinition} could be created with:
*
* ```typescript
* const ogTitleMetaDefinition = makeComposedKeyValMetaDefinition(
* ['og', 'title'],
* {
* keyAttr: 'property',
* separator: ':', // Could be omitted, as it's the default one
* }
* )
* ```
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @param names - Names to create they key name
* @param options - Options object
* @public
*/
export declare const makeComposedKeyValMetaDefinition: (names: readonly string[], options?: MakeComposedKeyValMetaDefinitionOptions) => NgxMetaMetaDefinition;
/**
* Options argument object for {@link makeComposedKeyValMetaDefinition}
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @public
*/
export interface MakeComposedKeyValMetaDefinitionOptions extends MakeKeyValMetaDefinitionOptions {
/**
* Character to use to join key strings
*
* Default value is `:`
*/
separator?: string;
}
/**
* Content to be set for a specific `<meta>` element in the page
*
* Can be `undefined` or `null`. In that case, the element will be removed.
*
* See {@link NgxMetaMetaService.set}
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @public
*/
export type NgxMetaMetaContent = string | undefined | null;
/**
* Creates, updates or removes `<meta>` elements.
*
* Uses Angular {@link https://angular.dev/api/platform-browser/Meta | Meta} APIs under the hood.
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @public
*/
export declare class NgxMetaMetaService {
private readonly meta;
constructor(meta: Meta);
/**
* Creates, updates or removes a specific `<meta>` element.
*
* The element is modeled using a {@link NgxMetaMetaDefinition} object.
*
* The element is created with the provided content. If no content is given, element is removed.
*
* @deprecated Use {@link NgxMetaElementsService} APIs instead.
* See {@link https://ngx-meta.dev/migrations/01-meta-element-apis | migration guide} for more info
*
* @param definition - `<meta>` element to create, update or remove
* @param content - Content value to create or update the `<meta>` element.
* Use `null` or `undefined` to remove the element from the page.
*/
set(definition: NgxMetaMetaDefinition, content: NgxMetaMetaContent): void;
static ɵfac: i0.ɵɵFactoryDeclaration<NgxMetaMetaService, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<NgxMetaMetaService>;
}
/**
* Models a `<meta>` element HTML's attributes as a key / value JSON object.
*
* Almost equivalent to Angular's {@link https://angular.dev/api/platform-browser/MetaDefinition/ | MetaDefinition}
*
* Only difference is `http-equiv` property. In an Angular's
* {@link https://angular.dev/api/platform-browser/MetaDefinition/ | MetaDefinition}, `httpEquiv` would also be
* accepted. This way there's no need to quote the key property.
* But without `httpEquiv` there's no need to map attribute names. So one bit of code less.
*
* @public
*/
export type NgxMetaElementAttributes = Partial<{
charset: string;
content: string;
"http-equiv": string;
id: string;
itemprop: string;
name: string;
property: string;
scheme: string;
url: string;
media: string;
}> & Record<string, string>;
/**
* See {@link NgxMetaElementsService.set}
*
* @public
*/
export type NgxMetaElementNameAttribute = readonly [
name: string,
value: string
];
/**
* Manages `<meta>` elements inside `<head>`
*
* @public
*/
export declare class NgxMetaElementsService {
private meta;
constructor(meta: Meta);
/**
* Creates, updates or removes some kind of `<meta>` elements inside `<head>` in a declarative fashion.
*
* Kind of `<meta>` elements to manage are identified by an HTML attribute providing its metadata name.
* For instance, to manage description metadata elements (`<meta name="description">`) on the page, the
* `name` attribute with `description` value identifies them.
*
* Then, contents for those can be specified. In the shape of a key/value JSON object declaring each element's
* additional attributes. Mainly `content` named attributes. See {@link NgxMetaElementAttributes}.
* If no contents are provided, all `<meta>` elements of that kind will be removed.
* An array of contents may be given to create multiple `<meta>` elements with same kind.
*
* @example
* <b>Setting `<meta name="description" content="Cool page"/>`</b>
*
* ```typescript
* ngxMetaElementsService.set(
* withNameAttribute('description'), // same as `['name','description']`
* withContent('Cool page'), // same as `{content:'Cool page'}`
* )
* ```
*
* Utility functions {@link withNameAttribute} and {@link withContentAttribute} help creating the
* name attribute identifying the kind of meta elements and the contents to provide for it.
*
* {@link withContentAttribute} helps to create the attributes key / value object.
*
* <b>Removing any `<meta name="description"/>` existing elements</b>
*
* ```typescript
* ngxMetaElementsService.set(
* withNameAttribute('description'), // same as `['name','description']`
* undefined, // same as `withContent(undefined)`
* )
* ```
*
* <b>Setting many `<meta name="theme-color"/>` elements</b>
*
* ```typescript
* ngxMetaElementsService.set(
* withNameAttribute('theme-color'), // same as `['name','theme-color']`
* [
* withContent('darkblue', { media: "(prefers-color-scheme: dark)" }),
* withContent('lightblue') // same as `{content:'lightblue'}`
* ]
* )
* ```
*
* <b>Removing any `<meta name="theme-color"/>` existing elements</b>
*
* ```typescript
* ngxMetaElementsService.set(
* withNameAttribute('theme-color'), // same as `['name','theme-color']`
* [], // `undefined` is valid too
* )
* ```
*
* Attribute name helpers:
*
* - {@link withNameAttribute}
*
* - {@link withPropertyAttribute}
*
* Content helpers:
*
* - {@link withContentAttribute}
*
* @param nameAttribute - Attribute use to identify which kind of `<meta>` elements to manage.
* As an array with the attribute name in first position and attribute value in second one.
* Utility functions exist to generate arrays for common name attributes.
* See {@link withNameAttribute} and {@link withPropertyAttribute} helpers to create those
* arrays without repeating attribute names around.
*
* @param content - Content(s) attributes to set for this `<meta>` elements kind.
* Or the lack of them to remove all `<meta>` elements of this kind.
* See {@link withContentAttribute} helper for creating content objects.
*/
set(nameAttribute: NgxMetaElementNameAttribute, content: readonly NgxMetaElementAttributes[] | NgxMetaElementAttributes | undefined): void;
static ɵfac: i0.ɵɵFactoryDeclaration<NgxMetaElementsService, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<NgxMetaElementsService>;
}
/**
* Creates an attribute name/value identifying a `<meta name="{value}">` element kind.
*
* See {@link NgxMetaElementsService.set}.
*
* @param value - Value for the `name` attribute of the `<meta>` element
*
* @public
*/
export declare const withNameAttribute: (value: string) => readonly [
"name",
string
];
/**
* Creates an attribute name/value identifying a `<meta property="{value}">` element kind.
*
* See {@link NgxMetaElementsService.set}.
*
* @param value - Value for the `property` attribute of the `<meta>` element
*
* @public
*/
export declare const withPropertyAttribute: (value: string) => readonly [
"property",
string
];
/**
* Creates an {@link NgxMetaElementAttributes} object specifying the `content` attribute to the
* given `value`. Plus optional `extras`.
*
* Unless given `value` is `null` or `undefined`. In that case, `undefined` is returned.
*
* See {@link NgxMetaElementsService.set}
*
* @param content - Value for the `property` attribute of the `<meta>` element
* @param extras - Extra attributes to include in the object if `content` is defined.
*
* @public
*/
export declare const withContentAttribute: {
(content: null | undefined, extras?: NgxMetaElementAttributes): undefined;
(content: string, extras?: NgxMetaElementAttributes): NgxMetaElementAttributes;
(content: string | null | undefined, extras?: NgxMetaElementAttributes): NgxMetaElementAttributes | undefined;
};
/**
* @internal
*/
export declare const _composedMetadataName: (...names: readonly string[]) => string;
/**
* @internal
*/
export declare const _provideNgxMetaModuleManager: <Type extends object, Key extends StringKeyOf<Type>>(key: Key, scope: readonly string[], options: _ProvideNgxMetaModuleManagerOptions<Type[Key]>) => import("@angular/core").Provider;
/**
* @internal
*/
export type _ProvideNgxMetaModuleManagerOptions<T> = Partial<{
f: MetadataSetterFactory<T>;
n: NgxMetaElementNameAttribute;
k: true;
}> & _ProvideNgxMetaManagerOptions;
/**
* @internal
*/
export declare const _withModuleManagerSetterFactory: <T>(setterFactory: _ProvideNgxMetaModuleManagerOptions<T>["f"]) => _ProvideNgxMetaModuleManagerOptions<T>;
/**
* @internal
*/
export declare const _withModuleManagerNameAttribute: <T>(nameAttribute: _ProvideNgxMetaModuleManagerOptions<T>["n"]) => _ProvideNgxMetaModuleManagerOptions<T>;
/**
* @internal
*/
export declare const _withModuleManagerSameGlobalKey: <T>() => _ProvideNgxMetaModuleManagerOptions<T>;
type MetadataResolver = (values: MetadataValues, resolverOptions: MetadataResolverOptions) => unknown;
/**
* Manages the metadata values of the current page.
*
* @public
*/
export declare class NgxMetaService {
private registry;
private resolver;
constructor(registry: MetadataRegistry, resolver: MetadataResolver);
/**
* Sets the metadata values of the current page
*
* @remarks
*
* The method is designed as an atomic operation. Subsequent calls to this
* method won't set more metadata, but will instead set the metadata values
* provided when calling it.
*
* For instance,
*
* ```typescript
* ngxMetaService.set({description: 'Description'})
* ngxMetaService.set({title: 'Title'})
* ```
*
* Will result in a page with title <b>but no description</b>
*
* For more information check the {@link https://ngx-meta.dev/guides/set-metadata-using-service/ | service guide docs}
*
* @param values - Metadata values to set, as a JSON object
*/
set(values?: MetadataValues): void;
/**
* Sets a metadata value for the page
*
* You can specify which metadata elements will be changed by using the
* global or JSON Path that you would use if using {@link NgxMetaService.set} API
*
* @remarks
* For instance, if you want to just set the title of the page. You'd set it
* with {@link NgxMetaService.set} API like this:
*
* ```typescript
* this.ngxMetaService.set({
* title: 'Global title'
* standard: {
* title: 'Standard title',
* }
* })
* ```
*
* But rest of metadata would be removed.
*
* To only set the `title`, you can use this API:
*
* ```typescript
* this.ngxMetaService.setOne('title', 'Global title')
* this.ngxMetaService.setOne('standard.title', 'Standard title')
* ```
*
* For more information check the {@link https://ngx-meta.dev/guides/set-metadata-using-service/ | service guide docs}
*
* @param globalOrJsonPath - Looks for metadata managers whose global matches
* this argument. Or whose JSON path matches this
* argument.
* @param value - Value to set for matching metadata elements
*/
setOne(globalOrJsonPath: string, value: unknown): void;
/**
* Clears all managed metadata elements of the current page
*/
clear(): void;
static ɵfac: i0.ɵɵFactoryDeclaration<NgxMetaService, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<NgxMetaService>;
}
/**
* Sets up default metadata values.
*
* When setting metadata values for a page, default values will be used as
* fallback when a metadata value isn't specified.
*
* @example
*
* <b>Using standalone, recommended API</b>
* ```typescript
* provideNgxMetaCore(
* withNgxMetaDefaults({title: 'Default title'})
* )
* ```
*
* <b>Using module-based API</b>
* ```typescript
* NgxMetaCoreModule.forRoot(
* withNgxMetaDefaults({title: 'Default title'})
* )
* ```
*
* See also:
*
* - {@link provideNgxMetaCore}: to use it with the standalone, recommended API.
*
* - {@link NgxMetaCoreModule.(forRoot:1)}: to use it with the module-based API.
*
* - {@link https://ngx-meta.dev/guides/defaults/ | Defaults guide}
*
* - {@link https://ngx-meta.dev/guides/metadata-values-json/ | Metadata values JSON guide}
*
* @param defaults - Default metadata values to use
*
* @public
*/
export declare const withNgxMetaDefaults: (defaults: MetadataValues) => CoreFeature<CoreFeatureKind.Defaults>;
/**
* Formats page titles.
*
* The default is to provide the page title as is.
*
* @internal
*/
export declare const _titleFormatter: _LazyInjectionToken<TitleFormatter>;
/**
* Page title formatter function type
*
* @param titleFormatter - Title to format. The one specified in metadata values.
* @returns Formatted title
*
* @beta
*/
export type TitleFormatter = (title: string) => string;
/**
* Provides a page title formatter.
*
* The formatter will be called with the specified page title metadata.
* Its output will be the value placed as the page's title by the metadata manager.
* This way you can prepend or append your site name or brand to all page titles, for instance.
*
* Built-in metadata managers that use this formatter are:
*
* - {@link Standard.title}
*
* - {@link OpenGraph.title}
*
* - {@link TwitterCard.title}
*
* @example
*
* <b>Using standalone, recommended API</b>
* ```typescript
* provideNgxMetaCore(
* withNgxMetaTitleFormatter((title) => `${title} - Site name`)
* )
* ```
*
* <b>Using module-based API</b>
* ```typescript
* NgxMetaCoreModule.forRoot(
* withNgxMetaTitleFormatter((title) => `${title} - Site name`)
* )
* ```
*
* See also:
*
* - {@link provideNgxMetaCore}: to use it with the standalone, recommended API.
*
* - {@link NgxMetaCoreModule.(forRoot:1)}: to use it with the module-based API.
*
* - {@link https://ngx-meta.dev/guides/title-formatting/ | Title formatting guide}
*
*
* @param titleFormatter - A function that takes the page title set in metadata values and returns the formatted title
*
* @beta
*/
export declare const withNgxMetaTitleFormatter: (titleFormatter: TitleFormatter) => CoreFeature<CoreFeatureKind.TitleFormatter>;
/**
* @internal
*/
export declare const _headElementUpsertOrRemove: _LazyInjectionToken<_HeadElementUpsertOrRemove>;
/**
* @internal
*/
export type _HeadElementUpsertOrRemove = (selector: string, element: HTMLElement | null | undefined) => void;
/**
* Allows to load metadata managers after library has been initialized.
*
* Check out {@link provideNgxMetaMetadataLoader} for the standalone, recommended API.
*
* @public
*/
export declare class NgxMetaMetadataLoaderModule {
static ɵfac: i0.ɵɵFactoryDeclaration<NgxMetaMetadataLoaderModule, never>;
static ɵmod: i0.ɵɵNgModuleDeclaration<NgxMetaMetadataLoaderModule, never, never, never>;
static ɵinj: i0.ɵɵInjectorDeclaration<NgxMetaMetadataLoaderModule>;
}
/**
* Allows to load metadata managers after library has been initialized.
*
* @remarks
*
* This is the standalone, recommended API. Using this API is preferred.
* However, you may also use {@link NgxMetaMetadataLoaderModule} as the Angular module-based equivalent API.
*
* @public
*/
export declare const provideNgxMetaMetadataLoader: () => Provider;
/**
* @internal
*/
export interface _FormatDevMessageOptions {
module: string;
property?: string;
value?: string | null;
link?: string;
}
/**
* @internal
*/
export declare const _formatDevMessage: (message: string, options: _FormatDevMessageOptions) => string;
/**
* Logs an error message about a URL not being HTTP or HTTPs
*
* Useful to warn developers about some metadata that requires absolute HTTP
* or HTTPs URLs
*
* MUST be used with `ngDevMode` so that this message only runs in development
*
* @internal
*/
export declare const _maybeNonHttpUrlDevMessage: (url: string | URL | undefined | null, opts: _FormatDevMessageOptions & {
shouldInsteadOfMust?: boolean;
}) => void;
/**
* Logs a warn message when a value string exceeds a length threshold
*
* Useful to warn developers about some metadata improperly used
*
* MUST be used with `ngDevMode` so that this message only runs in development
*
* @internal
*/
export declare const _maybeTooLongDevMessage: (value: string | undefined | null, maxLength: number, opts: _FormatDevMessageOptions) => void;
/**
* Provides `ngx-meta`'s core library services.
*
* Check out {@link provideNgxMetaCore} for the standalone, recommended API.
*
* Use {@link NgxMetaCoreModule.(forRoot:1)} method. Importing the module class alone does nothing.
*
* @public
*/
export declare class NgxMetaCoreModule {
/**
* Provides `ngx-meta`'s core library services.
*
* Check out {@link provideNgxMetaCore} for the standalone, recommended API.
*
* Allows setting up additional features:
*
* - {@link withNgxMetaDefaults}
*
* - {@link withNgxMetaBaseUrl}
*
* - {@link withNgxMetaTitleFormatter}
*
* Previous features configuration with an options object has been deprecated.
* See {@link NgxMetaCoreModule.(forRoot:2)} for more information and how to migrate.
*
* @param features - Features to configure the core module with
*/
static forRoot(...features: CoreFeatures): ModuleWithProviders<NgxMetaCoreModule>;
/**
* Deprecated way of configuring the core module features.
*
* Check out {@link provideNgxMetaCore} for the standalone, recommended API.
*
* Otherwise, to keep using module-based APIs, keep reading.
*
* This way of configuring options doesn't allow tree shaking unneeded features.
* So usage is discouraged and deprecated.
* See deprecation notice in API docs details for the tree-shaking friendly alternative
* Check out the example below for a migration example
*
* @deprecated Use {@link NgxMetaCoreModule.(forRoot:1)} for a module-based API with feature APIs as arguments instead.
* Even better, use {@link provideNgxMetaCore} for the standalone, recommended API.
*
* @example
* ```typescript
* NgxMetaCoreModule.forRoot({defaults: {title: 'Default title'}})
* ```
*
* should be migrated to
*
* ```typescript
* NgxMetaCoreModule.forRoot(withNgxMetaDefaults({title: 'Default title'}))
* ```
*/
static forRoot(options: NgxMetaCoreModuleForRootOptions): ModuleWithProviders<NgxMetaCoreModule>;
static ɵfac: i0.ɵɵFactoryDeclaration<NgxMetaCoreModule, never>;
static ɵmod: i0.ɵɵNgModuleDeclaration<NgxMetaCoreModule, never, never, never>;
static ɵinj: i0.ɵɵInjectorDeclaration<NgxMetaCoreModule>;
}
/**
* Configuration options for {@link NgxMetaCoreModule.(forRoot:2)}
*
* @deprecated Use {@link NgxMetaCoreModule.(forRoot:1)} with feature APIs as arguments instead.
* Or even better, use the {@link provideNgxMetaCore} standalone, recommended API.
* See {@link NgxMetaCoreModule.(forRoot:2)} for a migration example
* @public
*/
export interface NgxMetaCoreModuleForRootOptions {
/**
* See {@link withNgxMetaDefaults}
*/
defaults?: MetadataValues;
}
/**
* Provides `ngx-meta`'s core library services.
*
* @remarks
*
* This is the standalone, recommended API. Using this API is preferred.
* However, you may also use {@link NgxMetaCoreModule.(forRoot:1)} as the Angular module-based equivalent API.
*
* Allows setting up additional features:
*
* - {@link withNgxMetaDefaults}
*
* - {@link withNgxMetaBaseUrl}
*
* - {@link withNgxMetaTitleFormatter}
*
* @param features - Features to configure
*
* @public
*/
export declare const provideNgxMetaCore: (...features: CoreFeatures) => EnvironmentProviders;
/**
* @internal
*/
export declare const _routeMetadataStrategy: _LazyInjectionToken<_RouteMetadataStrategy>;
/**
* @internal
*/
export type _RouteMetadataStrategy = () => MetadataValues | undefined;
export {};