1,007
edits
Changes
→Commands with Arguments
<pre>
CmdUtils.CreateCommand({
},
execute: function( theShout arguments ) { var msg = theShoutarguments.object.text + "... " + theShoutarguments.object.text + "......";
displayMessage( msg );
}
});
</pre>
Ubiquity takes care of parsing the user's input, so you don't need to worry about handling prounoun substitution or any of the other natural-language-like features of the Ubiquity parser. Try selecting some text on a page, and Ubiq "echo this". Ubiquity should now echo the selected text.
=== The Input Object How Arguments are Defined ===
Your command can take multiple arguments. Each one is identified by a "role". To understand roles, it helps to think of your command name as a verb, and each argument as a noun. Remember that Ubiquity's command line is a pseudo-natural-language environment, so it attempts to be as close to natural language grammar as possible. For example, if you've ever used the <code>email</code> command, you know that it takes up to two arguments: a message and a person. <pre> email message email to person email message to person email to person message</pre> In grammatical terms, the message argument is the "direct object" of the verb "email". The person argument is an indirect object. We call it the "goal" of the verb. So if we were writing the email command, we'd define the arguments like this: <pre> arguments: [{role: "object", nountype: noun_arb_text, label: "message"}, {role: "goal", nountype: noun_type_contact, label: "recipient"}]</pre> Because we give the recipient argument the "goal" role, the Ubiquity parser knows to expect the user to type the word "to". When the user enters "email hello to Aza", the parser knows that the word following "to" -- that is, "Aza" -- should be assigned to the recipient argument. In our simple "echo" command, we expect the user to type "echo hellooooo" or something like that. The "hellooooo" is the direct object of the verb "echo", so we give it the "object" role. "Object" is the most common role. If a command takes only one argument, that argument is usually an "object". === What Roles Can I Use? === * object (in "echo helloooo", hello is the object.)* goal (in "email this to brandon", brandon is the goal.)* source (in "translate this from spanish", spanish is the source.)* location (in "yelp pizza near boston", boston is the location.)* time (in "book a flight on thursday", thursday is the time.)* instrument (in "search monkeys with google", google is the instrument.)* format (in "check weather in celsius", celsius is the format.)* modifier (in "get email address for chris", chris is the modifier.)* alias (in "twitter this as jono", jono is the alias.) === The input Arguments Object === When your execute method is called, it is passed a single object that encapsulates the values for all arguments. When your preview method is called, it is passed this object, too. The object has one attribute corresponding to each role. In our example above, the command accepts only an object-role argument, so the preview and execute methods get passed an argument with an "arguments.object" attribute. If we made a command, like email, that takes an object-role argument and a goal-role argument, its preview functions receive and execute methods would get passed an argument with "arguments.object" and "arguments.goal". arguments.object (or arguments.goal) has the following several attributesof its own:
<pre>
</pre>
