FAQ

Kris De Volder edited this page Oct 19, 2012 · 20 revisions

Sections in this FAQ

General

Q. What is Scripted?
Scripted is a light-weight browser-based editor. Although browser-based the client and server both run locally. Scripted can edit any text file on your local system and provides syntax highlighting and simple content assist for HTML and CSS files, but the focus is currently on providing the best JavaScript editing experience possible. The goal of Scripted is to provide a sophisticated editing experience for your JavaScript files while at the same time remaining fast and easy to use. The editor component of Scripted has been reused from Eclipse Orion.

Q. What features are implemented?
Scripted is still in its early stages. See the project front page for a quick list of supported features, or the Features page for detailed information.

Q. What is the architecture?
Scripted is entirely JavaScript and HTML/CSS. A small node backend serves the editor and its content. The server also tracks down module dependencies and performs filesystem searches. The editor itself is the same as that used in Eclipse Orion.

You can read more on the Architecture page.

Q. What are the next features we are likely to see?
There are a number of avenues we are exploring going forward:

  • Content assist. Always more to do here, we want to make it smarter. We are looking at exploiting further metadata to enhance inferencing - perhaps supporting vjet type libraries. We want to look at cross language inferencing too, navigating from code to css and back.
  • Side panel. Currently just host to a secondary editor, we want to exploit this space to show content relevant to the users task in the main editor. Might be search results for some query, jsdoc of some API, or a live linked view showing the definition of the function referenced at the cursor position in the main editor.

Q. Can I run the server component on another machine?
At the moment, you cannot. One key reason is that there is no security setup for the executing of shell commands and so the server is deliberately limited to accepting local connections (to avoid anyone anywhere connecting and running rm -rf on your machine). It will be movable in the future.

Editor and configuration

Q. How do I tell Scripted about my project structure?
In keeping with being ‘light-weight’, Scripted does not require you to explicitly define a project structure in a scripted specific format. Scripted will attempt to infer the project setup/context. When scripted is opened on a particular file it will walk up the directory hierarchy until it hits a .git, .project, or .scripted file and assume that is the project context. This is the context in which project dependencies will be resolved and the scope in which ‘open file’ will search for files.

A .scripted file can be used for two things:

  • to define where the project base is, if there isn't any other identifying resource.
  • to optionally configure the editor.

Q. Is the editor configurable?

There is no UI support for configuration, instead the Scripted is configured via a JSON formatted .scripted file, like a .virc file for vi. This file should be placed at the project root. Since version 0.3 you can also place configuration in a .scriptedrc file in your user home directory.

The config file is of this form:

{
  "formatter": {
    "js": {
      "indent_size": 1,
      "indent_char": "\t"
    }
  },
  "ui": {
    "font":"Ubuntu Mono",
    "font_size":12,
    "navigator": false
  }
}

All the elements are optional. Anything supplied in .scripted or .scriptedrc will override built-in defaults. Conflicts between .scripted and .scriptedrc are resolved in favor of .scripted. See issue SCRIPTED-76 for more detailed information on how .scriptedrc and .scripted get merged.

See below for more specifics on various customization options.

**Q. Can I share editor configurations between multiple projects?

Yes, but only in version 0.3 or later. Since 0.3, you can place shared configuration in a .scriptedrc file in your user home. Prior to 0.3 there was no support for the .scriptedrc file, so the only way to share settings pre 0.3 is by copying them to each project.

Q. How do I configure the formatter?
The options are specified as follows in the .scripted file:

{
  "formatter": {
    "js": {
        // insert options here...
    }
  }
}

Supported options are:

  • indent_size (default 4) : indentation size,
  • indent_char (default space) : character to indent with,
  • preserve_newlines (default true) : whether existing line breaks should be preserved,
  • preserve_max_newlines (default unlimited) : maximum number of line breaks to be preserved in one chunk,
  • jslint_happy (default false) : if true, then jslint-stricter mode is enforced. jslint_happy will give 'function ()' !jslint_happy will give 'function()'
  • brace_style (default "collapse") :

    • collapse put braces on the same line as control statements (default),
    • expand put braces on own line (Allman / ANSI style)
    • end-expand put end braces on own line.
    • expand-strict put brace on own line even in such cases:

      var a =
      {
          a: 5,
          b: 6
      }
      

      This mode may break your scripts, so beware! - e.g when returning an object literal.

  • space_before_conditional (default true) should the space before conditional statement be added, if(true) vs if (true)`
  • unescape_strings (default false) ? should printable characters in strings encoded in \xNN notation be unescaped, "example" vs "\x65\x78\x61\x6d\x70\x6c\x65"

Q. How do I change the font / font-size?
Add the relevant section to the .scripted file (see the Q on configuration):

{
  "ui": {
    "font":"Monaco",
    "font_size":12
  }
}

Q. How do I disable the navigator?
Add the relevant section to the .scripted file (see the Q on configuration):

{
  "ui":{
    "navigator":false
  }
}

Q. Can I resize the navigator?
Yes. Hover just between the editor and the navigator and you’ll get the resize arrow for dragging it larger/smaller.

Q. Does Scripted support JSLint?
Yes. JSLint is a code quality tool for JavaScript. It looks for common syntax and semantic errors and is invaluable for keeping your code clean and readable. JSLint error markers will appear in the editor gutter. You can configure JSLint through the standard comments at the top of a JavaScript file, or you can configure the options project-wide through a .scripted file. Here is some sample configuration:

{
    "jslint": {
        "global": [
            "window","console"
        ],
        "options": {
            "browser": true
        }
    }
}

Q: What happens if I have the same file open in multiple tabs?
There is currently no cross tab syncing. If working in this mode be careful since edit/saves made in one editor will not be reflected in the other tabs editing the same file.

Q. What is that funny icon next to the breadcrumb?
It is a history icon, enabling you to quickly jump to other files you have edited since the page was last loaded.

Content assist

Q. What can we expect that JS content assist should do?
Scripted uses flow analysis to determine proposals for content assist. It also uses information from required modules. So, Scripted is able to determine type information lexically from inside the current file as well as lexically determine the exports of required modules. Scripted understands AMD-style define and require calls, and can understand most of the basic RequireJS configuration. Additionally, scripted recognizes CommonJS-style modules used by NodeJS. Scripted recognizes transitive dependencies across multiple modules.

Scripted cannot yet infer argument types. If you want to have content assist support for arguments, then see the JSDoc section below.

Q. How can I configure content assist to be browser-aware?
You can use the standard JSLint browser directive to turn on browser-aware type inferencing. Just add the following comment towards the top of your file:

/*jslint browser:true */

Alternatively, you can add the following to your .scripted file if you want the option to affect your entire project:

{
    "jslint": {
        "options": {
            "browser": true
        }
    }
}

This changes the implicit scope of the global context so that the global this is of type Window. All of the common browser-specific objects are available through content-assist, but some of the more esoteric ones have not been implemented yet. Please raise an issue if there is a specific API that you want to use, but is not available.

Q. How else can I configure content assist through JSLint?
Scripted also recognizes the global directive. All global variables will be available in content assist. For example, the following adds the console and history variables to content assist:

/*global console history */

Alternatively, you can add the following to your .scripted file if you want the option to affect your entire project:

{
    "jslint": {
        "global": [
            "console","history"
        ],
    }
}

Q. How is jsdoc used inside of content assist?
Scripted recognizes JSDoc comments on function and variable declarations. See the Closure compiler documentation for a full list of tag syntax. Currently, Scripted recognizes the @type, @param, and @return tags. All others are ignored by the editor.

For example:

/** @param string */
function foo(a) {
  a.|
}

Perform content assist at the | and you will see proposals appropriate for String. In the future, we will be looking into the @constructor and @typedef tags and possibly others depending on how useful they appear to be.

Executing shell commands

Q. Can I execute shell commands from within Scripted? How?
Yes. It is possible to add an 'exec' section to your .scripted file. In this section you can bind shell commands to certain events/triggers.

Scripted itself comes with a sample .scripted file you can have a look at for some examples.

See Executing Shell Commands for details about this feature.

Q. I defined a shell command binding. It doesn't seem to do anything, where is the output?
The command output is simply logged to the Browser's JavaScript Console . If you don't have the JavaScript Console open, it will look as if nothing happened. In the future we will probably add some dedicated UI to show this output (see SCRIPTED-110).

For 'onKeys' bindings, if you are not sure whether your key definition was properly registered... you can open the help side panel by clicking on the question mark icon. If the definition was properly parsed and registered it will be listed there. If it is not listed, try reloading the editor page in your browser and then look in the JavaScript console for potential errors.

Troubleshooting

Q. I get a could not connect to localhost:7261 message in the browser tab that opens when starting Scripted
This usually means the node process is not starting quickly enough. Just reload the page (the server will have started by then). If this keeps happening edit the startup script (scr/scripted) and extend the time delay it waits for node to start. In the longer term the server process will be a long running process, so this won’t be an issue.

Q. Why is the Open File Dialog (or other operations) sometimes hanging/slow?
Possibly the node process has crashed because of some kind of a bug. On Unix or Mac you can do ps -fe | grep scripted to check if the process is still running. On Windows, you can check the task manager. If it has crashed you can restart it by running scripted (no arguments) from the command-line. If you can reproduce the problem, please consider filing a bug report.

If the server is still running then likely you are running into a somewhat mysterious problem that has been occasionally observed only when using the Chrome browser. For an unknown reason, outgoing XHR requests will occasionally stick in the Pending state rather than being handled. The problem appears to be on the client side and we have only seen it happen with Chrome (we also use Firefox and it seems unaffected). If you open Chrome Dev Tools 'Network' tab, you will see several Pending connections. They will stay pending for up-to a minute and then suddenly all of them will be handled all at once.

We are still trying to diagnose this problem. Until we find the cause, if you find your Chrome hanging, please be patient. This problem appears to correct itself after a minute or so. If you hit this problem too often, consider using Scripted with Firefox.

Feedback

Q. How/Where do I give feedback?
For asking questions and having discussions, please use the google group. Please raise bugs and requirements in the issuetracker.