From: Matias Insaurralde Date: Mon, 27 Jul 2015 02:57:43 +0000 (-0400) Subject: first docs X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=faf10183d8275daedb23659641135e236418c973;p=platform%2Fframework%2Fweb%2Fcrosswalk-tizen.git first docs --- diff --git a/docs/README-es.md b/docs/README-es.md index 16ecc3a..991c80b 100644 --- a/docs/README-es.md +++ b/docs/README-es.md @@ -1,16 +1,16 @@ ## Guías -* [Application distribution](tutorial/application-distribution.md) -* [Application packaging](tutorial/application-packaging.md) -* [Utilizando módulos nativos](tutorial/using-native-node-modules.md) -* [Depurando el proceso principal](tutorial/debugging-main-process.md) -* [Utilizando Selenium y WebDriver](tutorial/using-selenium-and-webdriver.md) -* [Extensión DevTools](tutorial/devtools-extension.md) -* [Utilizando el plugin pepper flash](tutorial/using-pepper-flash-plugin.md) +* [Distribución de aplicaciones](tutorial/application-distribution-es.md) +* [Empaquetamiento de aplicaciones](tutorial/application-packaging-es.md) +* [Utilizando módulos nativos](tutorial/using-native-node-modules-es.md) +* [Depurando el proceso principal](tutorial/debugging-main-process-es.md) +* [Utilizando Selenium y WebDriver](tutorial/using-selenium-and-webdriver-es.md) +* [Extensión DevTools](tutorial/devtools-extension-es.md) +* [Utilizando el plugin pepper flash](tutorial/using-pepper-flash-plugin-es.md) ## Tutoriales -* [Quick start](tutorial/quick-start.md) +* [Introducción](tutorial/quick-start.md) * [Integración con el entorno de escritorio](tutorial/desktop-environment-integration.md) * [Detección del evento en línea/fuera de línea](tutorial/online-offline-events.md) @@ -18,7 +18,7 @@ * [Sinopsis](api/synopsis.md) * [Proceso](api/process.md) -* [Supported Chrome command line switches](api/chrome-command-line-switches.md) +* [Parámetros CLI soportados (Chrome)](api/chrome-command-line-switches.md) Elementos DOM customizados: @@ -26,7 +26,7 @@ Elementos DOM customizados: * [`` tag](api/web-view-tag.md) * [`window.open` function](api/window-open.md) -Módulos para el proceso principal: +Módulos del proceso principal: * [app](api/app.md) * [auto-updater](api/auto-updater.md) @@ -42,13 +42,13 @@ Módulos para el proceso principal: * [protocol](api/protocol.md) * [tray](api/tray.md) -Módulos para el renderer (página web): +Módulos del renderer (página web): * [ipc (renderer)](api/ipc-renderer.md) * [remote](api/remote.md) * [web-frame](api/web-frame.md) -Módulos para ambos procesos: +Módulos de ambos procesos: * [clipboard](api/clipboard.md) * [crash-reporter](api/crash-reporter.md) @@ -61,8 +61,8 @@ Módulos para ambos procesos: * [Guía de estilo](development/coding-style.md) * [Estructura de directorio](development/source-code-directory-structure.md) * [Diferencias técnicas con NW.js (anteriormente conocido como node-webkit)](development/atom-shell-vs-node-webkit.md) -* [Build system overview](development/build-system-overview.md) -* [Build instructions (Mac)](development/build-instructions-mac.md) -* [Build instructions (Windows)](development/build-instructions-windows.md) -* [Build instructions (Linux)](development/build-instructions-linux.md) -* [Setting up symbol server in debugger](development/setting-up-symbol-server.md) +* [Sistema de compilación](development/build-system-overview.md) +* [Instrucciones de compilación (Mac)](development/build-instructions-mac.md) +* [Instrucciones de compilación (Windows)](development/build-instructions-windows.md) +* [Instrucciones de compilación (Linux)](development/build-instructions-linux.md) +* [Configurando un servidor de símbolos en el depurador](development/setting-up-symbol-server.md) diff --git a/docs/tutorial/application-distribution-es.md b/docs/tutorial/application-distribution-es.md new file mode 100644 index 0000000..644da8c --- /dev/null +++ b/docs/tutorial/application-distribution-es.md @@ -0,0 +1,114 @@ +# Distribución de aplicaciones + +Para distribuir tu aplicación con Electron, debes nombrar al directorio de tu aplicación +como `app`, y ponerlo bajo el directorio de recursos de Electron (en OSX es `Electron.app/Contents/Resources/`, +en Linux y Windows es `resources/`): + +En OSX: + +```text +electron/Electron.app/Contents/Resources/app/ +├── package.json +├── main.js +└── index.html +``` + +En Windows y Linux: + +```text +electron/resources/app +├── package.json +├── main.js +└── index.html +``` + +Posteriormente ejecutas `Electron.app` (o `electron` en Linux, `electron.exe` en Windows), +y Electron iniciará la aplicación. El directorio `electron` será la distribución que recibirán los usuarios finales. + +## Empaquetando tu aplicación como un archivo + +Además de copiar todos tus archivos fuente para la distribución, también puedes +empaquetar tu aplicación como un archivo [asar](https://github.com/atom/asar) +y de esta forma evitar la exposición del código fuente de tu aplicación a los usuarios. + +Para usar un archivo `asar` en reemplazo de la carpeta `app`, debes renombrar +el archivo a `app.asar`, y ponerlo bajo el directorio de recursos de Electron (como arriba), +Electron intentará leer el archivo y ejecutar la aplicación desde él. + +En OS X: + +```text +electron/Electron.app/Contents/Resources/ +└── app.asar +``` + +En Windows y Linux: + +```text +electron/resources/ +└── app.asar +``` + +Más detalles en [Empaquetamiento de aplicaciones](application-packaging-es.md). + +## Rebranding con binarios descargados + +Luego de empaquetar tu aplicación con Electron, podría ser útil agregar tu marca +antes de realizar la distribución. + +### Windows + +Puedes renombrar `electron.exe` a cualquier nombre que desees, y editar su ícono y otras informaciones +con herramientas como [rcedit](https://github.com/atom/rcedit) o [ResEdit](http://www.resedit.net). + +### OS X + +Puedes renombrar `Electron.app` a cualquier nombre que desees. También debes modificar los campos +`CFBundleDisplayName`, `CFBundleIdentifier` y `CFBundleName` en los siguientes archivos: + +* `Electron.app/Contents/Info.plist` +* `Electron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plist` + +También puedes renombrar el helper de la aplicación para evitar que aparezca como `Electron Helper` +en el Monitor de Actividades. + +La estructura de una aplicación renombrada sería así: + +``` +MyApp.app/Contents +├── Info.plist +├── MacOS/ +│   └── MyApp +└── Frameworks/ + ├── MyApp Helper EH.app + | ├── Info.plist + | └── MacOS/ + |    └── MyApp Helper EH + ├── MyApp Helper NP.app + | ├── Info.plist + | └── MacOS/ + |    └── MyApp Helper NP + └── MyApp Helper.app + ├── Info.plist + └── MacOS/ +    └── MyApp Helper +``` + +### Linux + +Puedes renombrar el ejectuable `electron` a cualquier nombre que desees. + +## Rebranding desde el código fuente de Electron + +También es posible agregar tu marca a Electron mediante un build personalizado. +Para realizar esto debes modificar el archivo `atom.gyp`. + +### grunt-build-atom-shell + +La modificación del código de Electron para agregar tu marca puede resultar complicada, una tarea Grunt +se ha creado para manejar esto de forma automatizada: + +[grunt-build-atom-shell](https://github.com/paulcbetts/grunt-build-atom-shell). + +Esta tarea se encargará de modificar el archivo `.gyp`, compilar el código +y reconstruir los módulos nativos de la aplicación para que coincidan con el nuevo nombre. diff --git a/docs/tutorial/application-packaging-es.md b/docs/tutorial/application-packaging-es.md new file mode 100644 index 0000000..56698c1 --- /dev/null +++ b/docs/tutorial/application-packaging-es.md @@ -0,0 +1,157 @@ +# Empaquetamiento de aplicaciones + +Para proteger los recursos y el código fuente de tu aplicación, puedes optar por empaquetar +tu aplicación en un paquete [asar][asar]. + +## Generando un archivo `asar` + +Un paquete [asar][asar] es un formato sencillo similar a tar, este formato concatena todos los archivos en uno, +Electron puede leer el contenido sin desempaquetar todos los archivos. + +A continuación, los pasos para empaquetar tu aplicación con `asar`: + +### 1. Instalar asar + +```bash +$ npm install -g asar +``` + +### 2. Empaquetar utilizando `asar pack` + +```bash +$ asar pack your-app app.asar +``` + +## Utilizando los paquetes `asar` + +En Electron existen dos tipos de APIs: las APIs de Node, proveídas por Node.js, +y las APIs Web, proveídas por Chromium. Ambas APIs soportan la lecutra de paquetes `asar`. + +### API Node + +Con parches especiales en Electron, las APIs de Node como `fs.readFile` and `require` +tratan los paquetes `asar` como directorios virtuales, y el contenido es accesible como si se tratara +de archivos normales en el sistema de archivos. + +Por ejemplo, supongamos que tenemos un paquete `example.asar` bajo `/path/to`: + +```bash +$ asar list /path/to/example.asar +/app.js +/file.txt +/dir/module.js +/static/index.html +/static/main.css +/static/jquery.min.js +``` + +Leer un archivo de nuestro paquete `asar`: + +```javascript +var fs = require('fs'); +fs.readFileSync('/path/to/example.asar/file.txt'); +``` + +Listar todos los archivos de la raíz: + +```javascript +var fs = require('fs'); +fs.readdirSync('/path/to/example.asar'); +``` + +Utilizar un módulo que se encuentra dentro del archivo: + +```javascript +require('/path/to/example.asar/dir/module.js'); +``` + +También puedes mostrar una página web contenida en un `asar` utilizando `BrowserWindow`. + +```javascript +var BrowserWindow = require('browser-window'); +var win = new BrowserWindow({width: 800, height: 600}); +win.loadUrl('file:///path/to/example.asar/static/index.html'); +``` + +### API Web + +En una págin web, los archivos que se encuentran en el paquete son accesibles a través del protocolo `file:`. +Al igual que la API Node, los paquetes `asar` son tratados como directorios. + +Por ejemplo, para obtener un archivo con `$.get`: + +```html + +``` + +### Utilizando un paquete `asar` como un archivo normal + +En algunas situaciones necesitaremos acceder al paquete `asar` como archivo, por ejemplo, +si necesitaramos verificar la integridad del archivo con un checksum. +Para casos así es posible utilizar el módulo `original-fs`, que provee la API `fs` original: + +```javascript +var originalFs = require('original-fs'); +originalFs.readFileSync('/path/to/example.asar'); +``` + +## Limitaciones de la API Node: + +A pesar de que hemos intentado que los paquetes `asar` funcionen como directorios de la mejor forma posible, +aún existen limitaciones debido a la naturaleza de bajo nivel de la API Node. + +### Los paquetes son de sólo lecutra + +Los paquetes `asar` no pueden ser modificados, por lo cual todas las funciones que modifiquen archivos +no funcionarán. + +## Los directorios del paquete no pueden establecerse como working directories + +A pesar de que los paquetes `asar` son manejados virtualmente como directorios, +estos directorios no existen en el sistema de archivos, por lo cual no es posible establecerlos +como working directory, el uso de la opción `cwd` en algunas APIs podría causar errores. + +### Desempaquetamiento adicional en algunas APIs + +La mayoría de las APIs `fs` pueden leer u obtener información sobre un archivo en un paquete `asar` sin +la necesidad de desempaquetarlo, pero algunas APIs requieren la ruta real. En estos casos Electron extraerá +el archivo a una ruta temporal. Esto agrega un overhead a algunas APIs. + +Las APIs que requieren el desempaquetamiento adicional son: + +* `child_process.execFile` +* `fs.open` +* `fs.openSync` +* `process.dlopen` - Utilizado po `require` en los módulos nativos + +### Información falsa en `fs.stat` + +El objeto `Stats` retornado por `fs.stat` y otras funciones relacionadas, +no es preciso, ya que los archivos del paquete `asar` no existen el sistema de archivos. +La utilización del objeto `Stats` sólo es recomendable para obtener el tamaño del archivo y/o +comprobar el tipo de archivo. + + +## Agregando archivos al paquete `asar` + +Como se menciona arriba, algunas APIs de Node desempaquetarán archivos cuando exista una llamada +que los referencie, además de los problemas de rendimiento que esto podría ocasionar, también +podría accionar alertas falsas en software antivirus. + +Para lidiar con esto, puedes desempaquetar algunos archivos utilizando la opción `--unpack`, +a continuación un ejemplo que excluye las librerías compartidas de los módulos nativos: + +```bash +$ asar pack app app.asar --unpack *.node +``` + +Después de ejecutar este comando, además del archivo `app.asar`, también se creará +un directorio `app.asar.unpacked`, que contendrá los archivos desempaquetados. +Este directorio deberá copiarse junto con el archivo `app.asar` a la hora de distribuir la aplicación. + +[asar]: https://github.com/atom/asar diff --git a/docs/tutorial/debugging-main-process-es.md b/docs/tutorial/debugging-main-process-es.md new file mode 100644 index 0000000..1a76403 --- /dev/null +++ b/docs/tutorial/debugging-main-process-es.md @@ -0,0 +1,45 @@ +# Depurando el proceso principal + +Los devtools sólo pueden depurar las páginas web (el código del proceso renderer). +Para depurar el código del proceso principal, Electron provee dos opciones para la línea de comandos: `--debug` y `--debug-brk`. + +## Opciones para la línea de comandos + +### `--debug=[port]` + +Esta opción escuchará mensajes del protocolo de depuración V8 en `port`, por defecto `port` es `5858`. + +### `--debug-brk=[port]` + +Similar a `--debug` pero realiza una pausa en la primera línea del script. + +## Utilizando node-inspector para depuración + +__Nota:__ Electron utiliza node v0.11.13, esta versión aún no funciona bien con node-inspector, +el proceso principal podría fallar al inspeccionar el objeto `process`. + +### 1. Iniciar [node-inspector][node-inspector] + +```bash +$ node-inspector +``` + +### 2. Activar el modo de depuración en Electron + +Es posible iniciar Electron con la opción de depuración: + +```bash +$ electron --debug=5858 your/app +``` + +o, pausar el script en la primera línea: + +```bash +$ electron --debug-brk=5858 your/app +``` + +### 3. Cargar la interfaz del depurador + +Abre http://127.0.0.1:8080/debug?ws=127.0.0.1:8080&port=5858 en Chrome. + +[node-inspector]: https://github.com/node-inspector/node-inspector diff --git a/docs/tutorial/desktop-environment-integration-es.md b/docs/tutorial/desktop-environment-integration-es.md new file mode 100644 index 0000000..f19f363 --- /dev/null +++ b/docs/tutorial/desktop-environment-integration-es.md @@ -0,0 +1,171 @@ +# Integración con el entorno de escritorio + +Los sistemas operativos proveen diferentes características para integrar aplicaciones +en sus entornos de escritorio. Por ejemplo, en Windows, las aplicaciones pueden agregar accesos directos +en la JumpList de la barra de tareas, y en Mac, las aplicaciones pueden agregar un menú personalizado en el dock. + +Esta guía explica cómo integrar tu aplicación en esos entornos de escritorio a través de las APIs de Electron. + +## Documentos recientes (Windows y OS X) + +Windows y OS X proveen un acceso sencillo a la lista de documentos recientes. + +__JumpList:__ + +![JumpList, Archivos recientes](http://i.msdn.microsoft.com/dynimg/IC420538.png) + +__Menú Dock:__ + + + +Para agregar un archivo a la lista de documentos recientes, puedes utilizar: +[app.addRecentDocument][addrecentdocument] API: + +```javascript +var app = require('app'); +app.addRecentDocument('/Users/USERNAME/Desktop/work.type'); +``` + +También puedes utilizar [app.clearRecentDocuments](clearrecentdocuments) para vaciar la lista de documentos recientes: + +```javascript +app.clearRecentDocuments(); +``` + +### Notas sobre Windows + +Para activar esta característica en Windows, tu aplicación debe registrar un handler +para el tipo de archivo que quieres utilizar, de lo contrario el archivo no aparecerá +en la JumpList, aún después de agregarlo. Puedes encontrar más información sobre el proceso de +registrar tu aplicación en [Application Registration][app-registration]. + +Cuando un usuario haga click en un archivo de la JumpList, una nueva instancia de tu aplicación +se iniciará, la ruta del archivo se agregará como un argumento de la línea de comandos. + +### Notas sobre OS X + +Cuando un archivo es solicitado desde el menú de documentos recientes, el evento `open-file` +del módulo `app` será emitido. + +## Menú dock personalizado (OS X) + +OS X permite a los desarrolladores definir un menú personalizado para el dock, +el cual usualmente contiene algunos accesos directos a las características más comunes +de tu aplicación: + +__Menú dock de Terminal.app:__ + + + +Para establecer tu menú dock, puedes utilizar la API `app.dock.setMenu`, la cual sólo está disponible para OSX: + +```javascript +var app = require('app'); +var Menu = require('menu'); +var dockMenu = Menu.buildFromTemplate([ + { label: 'New Window', click: function() { console.log('New Window'); } }, + { label: 'New Window with Settings', submenu: [ + { label: 'Basic' }, + { label: 'Pro'} + ]}, + { label: 'New Command...'} +]); +app.dock.setMenu(dockMenu); +``` + +## Tareas de usuario (Windows) + +En Windows puedes especificar acciones personalizadas en la categoría `Tasks` del JumpList, +tal como menciona MSDN: + + +> Las aplicaciones definen tareas basadas en las características del programa +> y las acciones clave que se esperan de un usuario. Las tareas deben ser +> libres de contexto, es decir, la aplicación no debe encontrarse en ejecución +> para que estas acciones funcionen. También deberían ser las acciones estadísticamente +> más comunes que un usuario normal realizaría en tu aplicación, como por ejemplo, +> redactar un mensaje de correo electrónico, crear un documento en el procesador de textos, +> ejecutar una aplicación en cierto modo, o ejecutar alguno de sus subcomandos. Una aplicación +> no debería popular el menú con características avanzadas que el usuario estándar no necesita +> ni con acciones que sólo se realizan una vez, como por ejemplo, el registro. No utilices +> las tareas para mostrar elementos promocionales como actualizaciones u ofertas especiales. +> +> Es recomendable que la lista de tareas sea estática. Debe mantenerse a pesar +> de los cambios de estado de la aplicación. Aunque exista la posibilidad de variar +> el contenido de la lista dinámicamente, debes considerar que podría ser confuso +> para un usuario que no espera que el destino de la lista cambie. + +__Tareas de Internet Explorer:__ + +![IE](http://i.msdn.microsoft.com/dynimg/IC420539.png) + +A diferencia del menú dock en OS X, el cual es un menú real, las tareas de usuario en Windows +funcionan como accesos directos de aplicación, que al ser clickeados, lanzan el programa +con argumentos específicos. + +Para establecer las tareas de usuario en tu aplicación, puedes utilizar: +[app.setUserTasks][setusertaskstasks] API: + +```javascript +var app = require('app'); +app.setUserTasks([ + { + program: process.execPath, + arguments: '--new-window', + iconPath: process.execPath, + iconIndex: 0, + title: 'New Window', + description: 'Create a new window' + } +]); +``` + +Para purgar la lista de tareas, puedes llamar a `app.setUserTasks` con un array vacío: + +```javascript +app.setUserTasks([]); +``` + +Las tareas de usuario aún serán visibles después de cerrar tu aplicación, por lo cual +el ícono y la ruta del programa deben existir hasta que la aplicación sea desinstalada. + +## Accesos directos en el lanzador Unity (Linux) + +En Unity, es posible agregar algunas entradas personalizadas, modificando el archivo `.desktop`, +ver [Adding shortcuts to a launcher][unity-launcher]. + +__Accesos directos de Audacious:__ + +![audacious](https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles?action=AttachFile&do=get&target=shortcuts.png) + +## Barra de progreso en la barra de tareas (Windows y Unity) + +En Windows, un botón en la barra de tareas puede utilizarse para mostrar una barra de progreso. Esto permite +que una ventana muestre la información de progreso al usuario, sin que el usuario tenga la ventana de la aplicación activa. + +El entorno de escritorio Unity también posee una característica similar que permite mostrar una barra de progreso en el lanzador. + +__Barra de progreso en un botón de la barra de herramientas:__ + +![Taskbar Progress Bar](https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png) + +__Barra de progreso en el lanzador Unity:__ + +![Unity Launcher](https://cloud.githubusercontent.com/assets/639601/5081747/4a0a589e-6f0f-11e4-803f-91594716a546.png) + +Para establecer la barra de progreso de una ventana, puedes utilizar +[BrowserWindow.setProgressBar][setprogressbar] API: + +```javascript +var window = new BrowserWindow({...}); +window.setProgressBar(0.5); +``` + +[addrecentdocument]: ../api/app.md#appaddrecentdocumentpath +[clearrecentdocuments]: ../api/app.md#appclearrecentdocuments +[setusertaskstasks]: ../api/app.md#appsetusertaskstasks +[setprogressbar]: ../api/browser-window.md#browserwindowsetprogressbarprogress +[setrepresentedfilename]: ../api/browser-window.md#browserwindowsetrepresentedfilenamefilename +[setdocumentedited]: ../api/browser-window.md#browserwindowsetdocumenteditededited +[app-registration]: http://msdn.microsoft.com/en-us/library/windows/desktop/ee872121(v=vs.85).aspx +[unity-launcher]: https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles#Adding_shortcuts_to_a_launcher diff --git a/docs/tutorial/devtools-extension-es.md b/docs/tutorial/devtools-extension-es.md new file mode 100644 index 0000000..f54c3e0 --- /dev/null +++ b/docs/tutorial/devtools-extension-es.md @@ -0,0 +1,49 @@ +# Extensión DevTools + +Para facilitar la depuración, Electron provee un soporte básico para la extensión +[Chrome DevTools Extension][devtools-extension]. + +Para la mayoría de las extensiones devtools, simplemente puedes descargar el código fuente +y utilizar `BrowserWindow.addDevToolsExtension` para cargarlas, las extensiones cargadas +serán recordadas para que no sea necesario llamar a la función cada vez que creas una ventana. + +Por ejemplo, para usar la extensión [React DevTools Extension](https://github.com/facebook/react-devtools), primero debes descargar el código fuente: + +```bash +$ cd /some-directory +$ git clone --recursive https://github.com/facebook/react-devtools.git +``` + +Luego cargas la aplicación en Electron, abriendo devtools en cualquier ventana, +y ejecutando este código en la consola devtools: + +```javascript +require('remote').require('browser-window').addDevToolsExtension('/some-directory/react-devtools'); +``` + +Para remover una extensión, puedes utilizar `BrowserWindow.removeDevToolsExtension` +especificando el nombre, y esta ya no se cargará la siguiente vez que abras devtools: + +```javascript +require('remote').require('browser-window').removeDevToolsExtension('React Developer Tools'); +``` + +## Formato de las extensiones devtools + +Idealmente todas las extensiones devtools escritas para Chrome pueden ser cargadas por Electron, +pero para ello deben estar en un directorio plano, las extensiones empaquetadas como `crx` +no pueden ser cargadas por Chrome a no ser que halles una forma de extraerlas a un directorio. + +## Páginas en segundo plano (background) + +Electron no soporta la característica de páginas en segundo plano de las extensiones de Chrome, +las extensiones que utilizan esta característica podrían no funcionar. + +## APIs `chrome.*` + +Algunas extensiones utilizan las APIs `chrome.*`, hemos realizado un esfuerzo +para implementar esas APIs en Electron, sin embargo no han sido implementadas en su totalidad. + +Dado que no todas las funciones `chrome.*` han sido implementadas, si la extensión devtools está utilizando otras APIs más allá de `chrome.devtools.*`, es muy probable que no funcione. Puedes reportar fallos en el issue tracker para que podamos agregar soporte a esas APIs. + +[devtools-extension]: https://developer.chrome.com/extensions/devtools diff --git a/docs/tutorial/online-offline-events-es.md b/docs/tutorial/online-offline-events-es.md new file mode 100644 index 0000000..0e43f9b --- /dev/null +++ b/docs/tutorial/online-offline-events-es.md @@ -0,0 +1,80 @@ +# Detección del evento en línea/fuera de línea + +La detección de estos eventos puede ser implementada en el proceso renderer utilizando las APIs HTML5 estándar, +como en este ejemplo: + +_main.js_ + +```javascript +var app = require('app'); +var BrowserWindow = require('browser-window'); +var onlineStatusWindow; + +app.on('ready', function() { + onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false }); + onlineStatusWindow.loadUrl('file://' + __dirname + '/online-status.html'); +}); +``` + +_online-status.html_ + +```html + + + + + + +``` + +Existen casos en donde necesitas responder a estos eventos desde el proceso principal. +El proceso principal no posee un objeto `navigator`, por lo tanto no puede detectar estos eventos directamente. +Es posible reenviar el evento al proceso principal mediante la utilidad de intercomunicación entre procesos (ipc): + +_main.js_ + +```javascript +var app = require('app'); +var ipc = require('ipc'); +var BrowserWindow = require('browser-window'); +var onlineStatusWindow; + +app.on('ready', function() { + onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false }); + onlineStatusWindow.loadUrl('file://' + __dirname + '/online-status.html'); +}); + +ipc.on('online-status-changed', function(event, status) { + console.log(status); +}); +``` + +_online-status.html_ + +```html + + + + + + +``` diff --git a/docs/tutorial/quick-start-es.md b/docs/tutorial/quick-start-es.md new file mode 100644 index 0000000..5c3095d --- /dev/null +++ b/docs/tutorial/quick-start-es.md @@ -0,0 +1,154 @@ +# Intro + +## Introducción + +Electron permite la creación de aplicaciones de escritorio utilizando JavaScript puro, a través de un runtime con APIs nativas. Puedes verlo como una variante de io.js, enfocado en aplicaciones de escritorio, en vez de servidores web. + +Esto no significa que Electron sea un binding de librerías GUI para JavaScript. +Electron utiliza páginas web como su GUI, por lo cual puedes verlo como un navegador Chromium mínimo, +controlado por JavaScript. + +### El proceso principal (main process) + +En Electron, el proceso que ejecuta el script `main` del `package.json` se llama __el proceso principal__. +El script que corre en el proceso principal puede crear páginas para mostrar la GUI. + +### El proceso renderer (renderer process) + +Dado que Electron utiliza Chromium para mostrar las páginas web, +también es utilizada la arquitectura multiproceso de Chromium. +Cada página web en Electron se ejecuta en su propio proceso, +el cual es llamado __el proceso renderer__. + +En los navegadores normales, las páginas web usualmente se ejecutan en un entorno +sandbox y no tienen acceso a los recursos nativos. Los usuarios de Electron tienen el poder +de utilizar las APIs de io.js en las páginas web, permitiendo interacciones de bajo nivel con el sistema operativo. + +### Diferencias entre el proceso principal y el proceso renderer + +El proceso principal crea páginas web mediante instancias de `BrowserWindow`. Cada instancia de `BrowserWindow` ejecuta su propia página web y su propio proceso renderer. +Cuando una instancia de `BrowserWindow` es destruida, también su proceso renderer correspondiente acaba. + +El proceso principal gestiona las páginas web y sus correspondientes procesos renderer. +Cada proceso renderer es aislado y sólo considera relevante la página web que corre en él. + +En las páginas web, no está permitido llamar a APIs relacionadas a la GUI nativa +porque la gestión de los recursos GUI nativos es peligrosa, y tiende a que ocurran leaks de memoria. +Si deseas realizar operaciones GUI en una página web, el proceso renderer de la página web debe comunicarse +con el proceso principal, y solicitar a este que realice esas operaciones. + +En Electron, hemos proveído el módulo [ipc](../api/ipc-renderer.md) para la comunicación +entre el proceso principal y el proceso renderer. Y también hay un módulo [remote](../api/remote.md) +para comunicación al estilo RPC. + +## Escribe tu primera aplicación Electron + +Generalmente, una aplicación Electron tendrá la siguiente estructura: + +```text +your-app/ +├── package.json +├── main.js +└── index.html +``` + +El formato de `package.json` es exactamente el mismo que cualquier módulo Node, +y el script especificado en el campo `main` será el script de arranque de tu aplicación, +a ser ejecutado por el proceso principal. Un ejemplo de `package.json` podría verse así: + +```json +{ + "name" : "your-app", + "version" : "0.1.0", + "main" : "main.js" +} +``` + +El `main.js` debería crear las ventanas y gestionar los eventos del sistema, un ejemplo típico sería: +example being: + +```javascript +var app = require('app'); // Módulo para controlar el ciclo de vida de la aplicación. +var BrowserWindow = require('browser-window'); // Módulo para crear uan ventana de navegador. + +// Reportar crashes a nuestro servidor. +require('crash-reporter').start(); + +// Mantener una referencia global al objeto window, si no lo haces, esta ventana +// se cerrará automáticamente cuando el objeto JavaScript sea recolectado (garbage collected): +var mainWindow = null; + +// Salir de todas las ventanas cuando se cierren. +app.on('window-all-closed', function() { + // En OS X es común que las aplicaciones y su barra de menú + // se mantengan activas hasta que el usuario cierre la aplicación + // explícitamente utilizando Cmd + Q + if (process.platform != 'darwin') { + app.quit(); + } +}); + +// Este método será llamado cuando Electron haya finalizado la inicialización +// y esté listo para crear ventanas de navegador. +app.on('ready', function() { + // Crear la ventana. + mainWindow = new BrowserWindow({width: 800, height: 600}); + + // cargar el index.html de nuestra aplicación. + mainWindow.loadUrl('file://' + __dirname + '/index.html'); + + // Desplegar devtools. + mainWindow.openDevTools(); + + // Evento emitido cuando se cierra la ventana. + mainWindow.on('closed', function() { + // Eliminar la referencia del objeto window. + // En el caso de soportar multiples ventanas, es usual almacenar + // los objetos window en un array, este es el momento en el que debes eliminar el elemento correspondiente. + mainWindow = null; + }); +}); +``` + +Finalmente el `index.html` es la página web que mostraremos: + +```html + + + + Hello World! + + +

Hello World!

+ We are using io.js + and Electron . + + +``` + +## Ejecutar la aplicación + +Cuando termines de escribir tu aplicación, puedes distribuirla +siguiendo la [guía de distribución](./application-distribution-es.md) +y luego ejecutar la aplicación empaquetada. También puedes utilizar el binario de Electron +para ejecutar tu aplicación de forma directa. + +En Windows: + +```bash +$ .\electron\electron.exe your-app\ +``` + +En Linux: + +```bash +$ ./electron/electron your-app/ +``` + +En OS X: + +```bash +$ ./Electron.app/Contents/MacOS/Electron your-app/ +``` + +`Electron.app` es parte del paquete de release de Electron, puedes descargarlo [aquí](https://github.com/atom/electron/releases). diff --git a/docs/tutorial/using-native-node-modules-es.md b/docs/tutorial/using-native-node-modules-es.md new file mode 100644 index 0000000..7840904 --- /dev/null +++ b/docs/tutorial/using-native-node-modules-es.md @@ -0,0 +1,57 @@ +# Utilizando módulos Node nativos + +Los módulos Node nativos son soportados por Electron, pero dado que Electron +está utilizando una versión distinta de V8, debes especificar manualmente la +ubicación de las cabeceras de Electron a la hora de compilar módulos nativos. + +## Compatibilidad de módulos nativos + +A partir de Node v0.11.x han habido cambios vitales en la API de V8. +Es de esperar que los módulos escritos para Node v0.10.x no funcionen con Node v0.11.x. +Electron utiliza Node v.0.11.13 internamente, y por este motivo tiene el mismo problema. + +Para resolver esto, debes usar módulos que soporten Node v0.11.x, +[muchos módulos](https://www.npmjs.org/browse/depended/nan) soportan ambas versiones. +En el caso de los módulos antiguos que sólo soportan Node v0.10.x, debes usar el módulo +[nan](https://github.com/rvagg/nan) para portarlos a v0.11.x. + +## ¿Cómo instalar módulos nativos? + +### La forma fácil + +La forma más sencilla de recompilar módulos nativos es a través del paquete +[`electron-rebuild`](https://github.com/paulcbetts/electron-rebuild), +el cual abstrae y maneja los pasos de descargar las cabeceras y compilar los módulos nativos: + +```sh +npm install --save-dev electron-rebuild + +# Ejecuta esto cada vez que ejecutes npm install +./node_modules/.bin/electron-rebuild +``` + +### La forma node-gyp + +Para compilar módulos Node con las cabeceras de Electron, debes indicar a `node-gyp` +desde dónde descargar las cabeceras y cuál versión usar: + +```bash +$ cd /path-to-module/ +$ HOME=~/.electron-gyp node-gyp rebuild --target=0.29.1 --arch=x64 --dist-url=https://atom.io/download/atom-shell +``` + +Los cambios en `HOME=~/.electron-gyp` fueron para especificar la ruta de las cabeceras. +La opción `--target=0.29.1` es la versión de Electron. La opción `--dist-url=...` especifica +dónde descargar las cabeceras. `--arch=x64` indica que el módulo será compilado para un sistema de 64bit. + +### La forma npm + +También puedes usar `npm` para instalar módulos, los pasos son exactamente igual a otros módulos Node, +con la excepción de que necesitas establecer algunas variables de entorno primero: + +```bash +export npm_config_disturl=https://atom.io/download/atom-shell +export npm_config_target=0.29.1 +export npm_config_arch=x64 +HOME=~/.electron-gyp npm install module-name +``` diff --git a/docs/tutorial/using-pepper-flash-plugin-es.md b/docs/tutorial/using-pepper-flash-plugin-es.md new file mode 100644 index 0000000..fbb2b6f --- /dev/null +++ b/docs/tutorial/using-pepper-flash-plugin-es.md @@ -0,0 +1,58 @@ +# Utilizando el plugin Pepper Flash + +El plugin Pepper Flash es soportado ahora. Para utilizar pepper flash en Electron, debes especificar la ubicación del plugin manualmente y activarlo en tu aplicación. + +## Preparar una copia del plugin Flash + +En OSX y Linux, el detalle del plugin puede encontrarse accediendo a `chrome://plugins` en el navegador. Su ubicación y versión son útiles para el soporte. También puedes copiarlo a otro lugar. + +## Agrega la opción a Electron + +Puedes agregar la opción `--ppapi-flash-path` y `ppapi-flash-version` o utilizar el método `app.commandLine.appendSwitch` antes del evento ready de la aplicación. +También puedes agregar la opción `plugins` de `browser-window`. Por ejemplo, + +```javascript +var app = require('app'); +var BrowserWindow = require('browser-window'); + +// Report crashes to our server. +require('crash-reporter').start(); + +// Keep a global reference of the window object, if you don't, the window will +// be closed automatically when the javascript object is GCed. +var mainWindow = null; + +// Quit when all windows are closed. +app.on('window-all-closed', function() { + if (process.platform != 'darwin') { + app.quit(); + } +}); + +// Specify flash path. +// On Windows, it might be /path/to/pepflashplayer.dll +// On Mac, /path/to/PepperFlashPlayer.plugin +// On Linux, /path/to/libpepflashplayer.so +app.commandLine.appendSwitch('ppapi-flash-path', '/path/to/libpepflashplayer.so'); + +// Specify flash version, for example, v17.0.0.169 +app.commandLine.appendSwitch('ppapi-flash-version', '17.0.0.169'); + +app.on('ready', function() { + mainWindow = new BrowserWindow({ + 'width': 800, + 'height': 600, + 'web-preferences': { + 'plugins': true + } + }); + mainWindow.loadUrl('file://' + __dirname + '/index.html'); + // Something else +}); +``` + +## Activar el plugin flash en una etiqueta `` +Agrega el atributo `plugins`. +```html + +``` diff --git a/docs/tutorial/using-selenium-and-webdriver-es.md b/docs/tutorial/using-selenium-and-webdriver-es.md new file mode 100644 index 0000000..7d99890 --- /dev/null +++ b/docs/tutorial/using-selenium-and-webdriver-es.md @@ -0,0 +1,72 @@ +# Utilizando Selenium y WebDriver + +De [ChromeDriver - WebDriver for Chrome][chrome-driver]: + +> WebDriver es una herramienta de código abierto para automatizar el testing de aplicaciones web +> en varios navegadores. WebDriver provee funciones de navegación, entrada de usuario, +> ejecución de JavaScript, y más. ChromeDriver es un servidor standalone que implementa +> el protocolo de WebDriver para Chromium. Se encuentra en desarrollo por los miembros de +> Chromium y WebDriver. + +En la página de [lanzamientos](https://github.com/atom/electron/releases) de Electron encontrarás paquetes de `chromedriver`. + +## Ajustando parámetros con WebDriverJs + +[WebDriverJs](https://code.google.com/p/selenium/wiki/WebDriverJs) provee +un paquete Node para realizar testing con web driver, lo usaremos como ejemplo. + +### 1. Inicia chrome driver + +Primero necesitas descargar el binario `chromedriver` y ejecutarlo: + +```bash +$ ./chromedriver +Starting ChromeDriver (v2.10.291558) on port 9515 +Only local connections are allowed. +``` + +Recuerda el puerto `9515`, lo utilizaremos después. + +### 2. Instala WebDriverJS + +```bash +$ npm install selenium-webdriver +``` + +### 3. Conecta chrome driver + +El uso de `selenium-webdriver` junto con Electron es básicamente el mismo que el original, +excepto que necesitas especificar manualmente cómo se conectará el chrome driver +y dónde encontrará el binario de Electron: + +```javascript +var webdriver = require('selenium-webdriver'); + +var driver = new webdriver.Builder() + // El puerto "9515" es que abre chrome driver. + .usingServer('http://localhost:9515') + .withCapabilities({chromeOptions: { + // Aquí especificamos la ruta a Electron + binary: '/Path-to-Your-App.app/Contents/MacOS/Atom'}}) + .forBrowser('electron') + .build(); + +driver.get('http://www.google.com'); +driver.findElement(webdriver.By.name('q')).sendKeys('webdriver'); +driver.findElement(webdriver.By.name('btnG')).click(); +driver.wait(function() { + return driver.getTitle().then(function(title) { + return title === 'webdriver - Google Search'; + }); +}, 1000); + +driver.quit(); +``` + +## Workflow + +Para probar tu aplicación sin recompilar Electron, simplemente [copia](https://github.com/atom/electron/blob/master/docs/tutorial/application-distribution.md) las fuentes de tu aplicación en el directorio de recursos de Electron. + +[chrome-driver]: https://sites.google.com/a/chromium.org/chromedriver/ + +