turbocommons-ts

/** * TurboCommons is a general purpose and cross-language library that implements frequently used and generic software development tasks. * * Website : -> https://turboframework.org/en/libs/turbocommons * License : -> Licensed under the Apache License, Version 2.0. You may not use this file except in compliance with the License. * License Url : -> http://www.apache.org/licenses/LICENSE-2.0 * CopyRight : -> Copyright 2015 Edertone Advanded Solutions (08211 Castellar del Vallès, Barcelona). http://www.edertone.com */ /** * An abstraction of the browser entity an all its related operations and properties * Browser entity is normally available only on client side or front end view applications, * but some of its features can also make sense on a server side app. So depending on the * implementation language, this class may or may not have some of its methods implemented. */ export declare class BrowserManager { /** * Get the current page full url, including 'https://', domain and any uri get parameters * * @return A well formed url */ getCurrentUrl(): string; /** * Tells if the current html document is fully loaded or not. * * @returns True if the current html document is fully loaded (including all frames, objects and images) or false otherwise. */ isDocumentLoaded(): boolean; /** * Check if the specified cookie exists * * @param key the name for the cookie we want to find * * @returns True if cookie with specified name exists, false otherwise */ isCookie(key: string): boolean; /** * Set the value for a cookie or create it if not exist * * Adapted from the jquery.cookie plugin by Klaus Hartl: https://github.com/carhartl/jquery-cookie * * @param key the name for the cookie we want to create * @param value the value we want to set to the new cookie. * @param expires The lifetime of the cookie. Value can be a `Number` which will be interpreted as days from time of creation or a `Date` object. If omitted or '' string, the cookie becomes a session cookie. * @param path Define the path where the cookie is valid. By default it is the whole domain: '/'. A specific path can be passed (/ca/Home/) or a '' string to set it as the current site http path. * @param domain Define the domain where the cookie is valid. Default: domain of page where the cookie was created. * @param secure If true, the cookie transmission requires a secure protocol (https). Default: false. * * @returns True if cookie was created, false otherwise. An exception may be thrown if invalid parameters are specified */ setCookie(key: string, value: string, expires?: any, path?: string, domain?: string, secure?: boolean): boolean; /** * Get the value for an existing cookie. * * Adapted from the jquery.cookie plugin by Klaus Hartl: https://github.com/carhartl/jquery-cookie * * @param key the name of the cookie we want to get * * @returns Cookie value or null if cookie does not exist */ getCookie(key: string): string | undefined; /** * Deletes the specified cookie from browser. * Note that the cookie will only be deleted if belongs to the same path as specified. * * @param key The name of the cookie we want to delete * @param path Define the path where the cookie is set. By default it is the whole domain: '/'. If the cookie is not set on this path, we must pass the right one or the delete will fail. * * @returns True if cookie was deleted or false if cookie could not be deleted or was not found. */ deleteCookie(key: string, path?: string): boolean; /** * Check if the currently active URL at the browser contains a hash fragment. * The fragment is a part of the URL that comes after the # symbol, and can be modified without * needing to reload the page. It is important to know that the url fragment is always available * at the browser level and will never be sent to server. * * An example of a hash: * https://someurl.com/home#somehash * * @returns True if the active URL has a hash fragment, false otherwise. */ isCurrentUrlWithHashFragment(): boolean; /** * Obtain the value that is found at the current URL hash fragment part. For example: * https://someurl.com/home#somehash * * Will return 'somehash' * * @returns The value of the URL hash fragment but without the # character */ getCurrentUrlHashFragment(): string; /** * TODO */ setCurrentUrlHashFragment(): void; /** * TODO */ deleteCurrentUrlHashFragment(): void; /** * TODO */ isCurrentUrlWithQuery(): void; /** * TODO */ getCurrentUrlQueryValues(): void; /** * Reloads the current url. This will make the browser load all the current html document again * and all page state will be lost. * * @returns void */ reload(): void; /** * Tries to detect the language that is set as preferred by the user on the current browser. * NOTE: Getting browser language is not accurate. It is always better to use server side language detection * * @returns A two digits string containing the detected browser language. For example 'es', 'en', ... */ getPreferredLanguage(): any; /** * Opens the specified url on the browser's current tab or in a new one. * * @param url The url that will be loaded * @param newWindow Setting it to true will open the url on a new browser tab. False by default * @param postData If we want to send POST data to the url, we can set this parameter to an object where * each property will be translated to a POST variable name, and each property value to the POST variable value * * @returns void */ goToUrl(url: string, newWindow?: boolean, postData?: Object | null): void; /** * Disable the hability for the user to navigate back on browser history. This method does not disable the * browser back button, but it prevents it from leaving the current page. * * @returns void */ disableBackButton(): void; /** * Event listener that will prevent the back button when disableBackButton is enabled */ private _onPopStatePreventBackButton; /** * Restore the back button normal behaviour which was blocked by calling disableBackButton() * * @returns void */ enableBackButton(): void; /** * Totally disables the current page scrolling. Useful when creating popups or elements that have an internal scroll, * and we don't want it to interfere with the main document scroll. * Can be enabled again with enableScroll. * * @returns void */ disableScroll(): void; /** * Restores main document scrolling if has been disabled with HtmlUtils.disableScroll * * @returns void */ enableScroll(): void; /** * Gives the current position for the browser scroll * * @returns Array with the current x,y position based on the top left corner of the current document */ getScrollPosition(): number[]; /** * Obtain the current viewport browser window width value * * @see https://stackoverflow.com/questions/1248081/get-the-browser-viewport-dimensions-with-javascript * * @returns A numeric value representing the window width in pixels */ getWindowWidth(): number; /** * Obtain the current viewport browser window height value * * @see https://stackoverflow.com/questions/1248081/get-the-browser-viewport-dimensions-with-javascript * * @returns A numeric value representing the window height in pixels */ getWindowHeight(): number; /** * Obtain the current html document width in pixels * * @returns Numeric value representing the document width in pixels */ getDocumentWidth(): number; /** * Obtain the current html document height in pixels * * @returns Numeric value representing the document height in pixels */ getDocumentHeight(): number; /** * Moves the browser scroll to the specified X,Y axis position or DOM element. * * @example browserManager.scrollTo(document.querySelector('#myId'), 800); * @example browserManager.scrollTo([100,200], 1000); * * @see https://pawelgrzybek.com/page-scroll-in-vanilla-javascript/ * * @param destination The location where the scroll must be moved to. It can be an HTML element instance or an array of two numbers with the [x,y] destination coordinates * @param duration The animation duration in miliseconds. Set it to 0 to perform a direct scroll change. * @param callback A method that will be executed right after the scroll finishes * * @returns void */ scrollTo(destination: HTMLElement | [number, number], duration?: number, callback?: Function | null): void; /** * Copies the specified text to the clipboard * * @param text Some string that will be placed on the system clipboard * * @returns Promise A promise to be resolved once the copy is performed */ copyToClipboard(text: string): Promise<void>; /** * Search for a file or files on the local user machine. Their contents will be loaded into the browser memory and can be used * locally without needing to update them to a remote server. * * @param event It is mandayory for security reasons that an event from an actual input type='file' element is passed to this method. * We can set here for example the change event that is fired by the input when the user selects a file. * Example for single file: <input type='file' accept=".txt" (change)="onFileSelected($event)"> (call browseLocalFiles() inside the change event handler) * Example for multi files: <input type='file' multiple="multiple" accept=".txt" (change)="onFileSelected($event)"> * of the onFileSelected method. * @param mode Specify if the files must be loaded as plain "TEXT" or "BASE64" encoded binary data * @param callback Once the files selected by the user are correctly loaded into the browser, this callback method will be * called with two parameters containing the name and contents for each one of the loaded files. * * @returns Void. (An exception will be thrown if the load fails) */ browseLocalFiles(event: any, mode: 'TEXT' | 'BASE64', callback: (fileNames: string[], fileContents: string[]) => void): void; }