droidQuery
Introduction
droidQuery is an Android port of jQuery, and is designed to be as syntactically alike as possible in Java.
For those not familiar with jQuery, it essentially provides magic for allowing the simultaneous manipulation of a set of UI entities (using animations, attributes settings, etc), as well as to perform complex tasks, such as asynchronous network tasks. droidQuery can do all of these things.
Essentially, droidQuery provides this same type of magic for the view hierarchy and AsyncTasks, and can be used to perform other frequent jobs, such as showing alert messages. Also like jQuery, droidQuery allows the addition of extensions to add to the power of the library.
Popular extensions currently available include droidProgress, which can show a progress bar or spinner, and droidMail, which allows email to be configured and sent without using Intent. A full listing can be found on the wiki. If you have created a new droidQuery extension, please let me know, and I can add a link on the wiki.
droidQuery is intended to be used by all Android developers, as it greatly simplifies the procedures for performing many common tasks. droidQuery can also be used to help web developers that are familiar with jQuery to get into Android development.
How to Include droidQuery in your Project
There are three ways to include droidQuery in your project:
- Clone the repo, import into Eclipse (
Import > Android > Existing Android Code Into Workspace), and include a project dependency. - Include the full
jar, which includes dependencies, available here, or can be generated using the antbuild.xmlscript. You can tell these apart because they are named with the current version. - The best way is to include each dependent
jarseparately. This will allow you to include projects with the same dependencies. Do this by grabbing the latest release (this file is simply called droidquery.jar), then grab the dependency jars here.
License
Copyright 2013 Phil Brown
droidQuery is licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
How to Use
Note: droidQuery is a work in progress. If you find any bugs or would like functionality that is missing, please create a new issue ( https://github.com/phil-brown/droidQuery/issues).
Note About new APIs. By default, Ajax requests currently uses the Apache HTTP Client. This is being deprecated in the newest version of Android, and is generally less used. To accommodate the update, you will either need to include the client in your dependencies, or better yet, you should call
useNewApi(true)on your AjaxOptions Object. This WILL cause some differences in behavior of returned objects, but it should be minimal. More docs coming soon.
Below are some of the most common tasks that droidQuery can be used for. A full list, as well as examples, is currently under construction in the wiki. A sample application can also be found in the droidQueryTest directory. The relevant code can be found in ExampleActivity.java. You may also browse the javadocs here. Finally, most of the jQuery API Documentation is sufficient to explain the droidQuery API.
To instantiate a new droidQuery, you need to pass in a Context, a View, or set of Views. The simplest way to create the instance is using the with static methods:
$.with(Context);
$.with(View);
$.with(List<View>);
$.with(View...);
If Context is passed, droidQuery will attempt to manipulate the root view. For example, if Context is an Activity, the content view will be selected. There is also a way to select a View using it's id:
$.with(Context).id(Integer);
or, for short:
$.with(Context, Integer);
Once you have the droidQuery instance, you can either save it as a variable, or chain calls to manipulate the selected View or Views.
Ajax
To perform an asynchronous network task, you can use ajax. The most straight-forward way to create and start an ajax task is with the $.ajax(AjaxOptions) method. For example:
$.ajax(new AjaxOptions().url("http://www.example.com")
.type("GET")
.dataType("text")
.context(this)
.success(new Function() {
@Override
public void invoke($ droidQuery, Object... params) {
droidQuery.alert((String) params[0]);
}
}
).error(new Function() {
@Override
public void invoke($ droidQuery, Object... params) {
int statusCode = (Integer) params[1];
String error = (String) params[2];
Log.e("Ajax", statusCode + " " + error);
}
}
));
Attributes
droidQuery can be used to get or change the attributes of its selected Views. The most common methods include attr() to get an attribute, attr(String, Object) to set an attribute, val() to get the value of a UI element (such as CharSequence for TextViews, Drawables for ImageViews, etc), and val(Object) to set the value.
Callbacks
The Callbacks Object provides a simple way to manage and fire sets of callbacks. To get an instance of this Object, use $.Callbacks(this).
Effects
droidQuery can be used to animate the selected Views. The simplest way to perform a custom animation is by using the animate(String, long, Easing, Function) method. For example:
$.with(myView).children().animate("{
left: 100px, top: 100, width: 50%, height: 50%
}
", 400, Easing.LINEAR, new Function() {
@Override public void invoke($ droidQuery, Object... params) {
droidQuery.toast("animation complete", Toast.LENGTH_SHORT);
}
}
);
It can also be used to perform pre-configured animations, such as fades (using fadeIn, fadeOut, fadeTo, and fadeToggle) and slides ( slideUp, slideDown, slideLeft, and slideRight).
Events
droidQuery can be used to register events (such user input or view changes) on the selected UI elements. This can be done using the following methods: bind, on, one, change, click, longclick, swipe, swipeUp, swipeLeft, swipeDown, swipeRight, focus, focusOut, keyDown, keyUp, keyPress, select, and unbind. For example:
//Register a click event $.with(this, R.id.btn_refresh).click(new Function() {
@Override public void invoke($ droidQuery, Object... params) {
droidQuery.alert("refresh");
refresh();
}
}
);
//or use the "on" method to register a click event. $.with(this, R.id.btn_refresh).on("click", new Function() {
@Override public void invoke($ droidQuery, Object... params) {
droidQuery.toast("Refresh", Toast.LENGTH_LONG);
refresh();
}
}
);
Selectors
The real magic behind droidQuery is its ability to manipulate a set of UI elements at one instance. a View or a set of Views can be passed to a droidQuery instance using any of the with methods, or a new instance of droidQuery containing a set of Views can be created using any of the selector methods, including view, child, parent, children, siblings, slice, selectAll, selectByType, selectChildren, selectEmpties, selectFocused, selectHidden, selectVisible, id, selectImages, selectOnlyChilds, and selectParents.
Miscellaneous
droidQuery also comes with several methods that simplify a lot of common tasks. including:
- each(Function) - invokes the given function for each selected View
- map(String)/map(JSONObject) - converts a JSON String or a JSONObject to a Map Object
- map(Entry...) - quickly make a Map Object
- entry(String, Object) - quickly make a Map Entry Object
- alert - show an alert dialog
- toast - show a
Toastmessage - write - write text to a file
- parseJSON - parses a JSON string and returns a JSONObject
- parseXML - parses an XML string and returns a Document Object
A note about Scripts
In jQuery, there is an Ajax type called Script, which can be used to download a Javascript file. This type also exists in droidQuery, but instead of Javascript, it expects a Bourne script, which is runnable on the Android command line. Common usage for such a feature include running an existing script, without the need to port to Java, or to run Android Debug Bridge (adb) commands. For example, say the POST request to http://www.example.com/settings returns a bourne script as a response to issue a command based on the current application settings. The command, for example, could broadcast an Intent to open an app:
am broadcast -a android.intent.action.CAMERA_BUTTON The request would likely look like this:
$.ajax("{
url: 'http://www.example.com/settings', type: 'post', dataType: 'script', data: '{
id: 4, setting: 1
}
'
}
");
and as long as the request was successful, the native camera app would open once the response came back.
If the script does not issue an adb command, but instead calculates some data, the response would include the script output.
News
I introduced droidQuery at Google DevFest Twin Cities! You can view my slides online at http://www.slideshare.net/PhDBrown/droid-query .
Special Thanks
This project uses AsyncTaskEx to allow an unlimited number of simultaneous network tasks. It also uses NineOldAndroids to provide animation support for Pre-Honeycomb versions of Android. CSS parsing is handled by jCSS-Parser, which I wrote with this project in mind. Finally, this project would not exist if it were not for the excellent jQuery library, and its excellent documentation.