Hello from Turbolinks! This demo app will help you get acquainted with the framework.
2 | 3 |interface TurbolinksScrollUpCallback
107 | Defines a callback for determining whether or not a child view can scroll up.
| Modifier and Type | 124 |Method and Description | 125 |
|---|---|
boolean |
128 | canChildScrollUp()
129 | Used to determine whether or not a child view can scroll up.
130 | |
131 |
boolean canChildScrollUp()154 |
Used to determine whether or not a child view can scroll up.
| Interface | 80 |Description | 81 |
|---|---|
| TurbolinksAdapter | 85 |
86 | Defines callbacks that Turbolinks makes available to your app.
87 | |
88 |
| Class | 97 |Description | 98 |
|---|---|
| TurbolinksSession | 102 |
103 | The main concrete class to use Turbolinks 5 in your app.
104 | |
105 |
| TurbolinksView | 108 |
109 | The custom view to add to your activity layout.
110 | |
111 |
Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:
79 |Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
91 |Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
111 |Each annotation type has its own separate page with the following sections:
115 |Each enum has its own separate page with the following sections:
126 |There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
144 |The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
148 |These links take you to the next or previous class, interface, package, or related page.
152 |These links show and hide the HTML frames. All pages are available with or without frames.
156 |The All Classes link shows all classes and interfaces except non-static nested types.
160 |Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
164 |The Constant Field Values page lists the static final fields and their values.
168 |TurbolinksAdapter implementation is required so that callbacks
83 | during the Turbolinks event lifecycle can be passed back to your app.Defines callbacks that Turbolinks makes available to your app. This interface is required, and 5 | * should be implemented in an activity (or similar class).
6 | * 7 | *Often these callbacks handle error conditions, but there are also some convenient timing events 8 | * where you can do things like routing, inject custom Javascript, etc.
9 | */ 10 | public interface TurbolinksAdapter { 11 | /** 12 | *Called after the Turbolinks Javascript bridge has been injected into the webView, during the 13 | * Android WebViewClient's standard onPageFinished callback. 14 | */ 15 | void onPageFinished(); 16 | 17 | /** 18 | *
Called when the Android WebViewClient's standard onReceivedError callback is fired.
19 | * 20 | * @param errorCode Passed through error code returned by the Android WebViewClient. 21 | */ 22 | void onReceivedError(int errorCode); 23 | 24 | /** 25 | *Called when Turbolinks detects that the page being visited has been invalidated, typically 26 | * by new resources in the the page HEAD.
27 | */ 28 | void pageInvalidated(); 29 | 30 | /** 31 | *Called when Turbolinks receives an HTTP error from a Turbolinks request.
32 | * 33 | * @param statusCode HTTP status code returned by the request. 34 | */ 35 | void requestFailedWithStatusCode(int statusCode); 36 | 37 | /** 38 | *Called when Turbolinks considers the visit fully completed -- the request fulfilled 39 | * successfully and page rendered.
40 | */ 41 | void visitCompleted(); 42 | 43 | /** 44 | *Called when Turbolinks first starts a visit, typically from a link inside a webView.
45 | * 46 | * @param location URL to be visited. 47 | * @param action Whether to treat the request as an advance (navigating forward) or a replace (back). 48 | */ 49 | void visitProposedToLocationWithAction(String location, String action); 50 | } 51 | -------------------------------------------------------------------------------- /turbolinks/src/main/java/com/basecamp/turbolinks/TurbolinksHelper.java: -------------------------------------------------------------------------------- 1 | package com.basecamp.turbolinks; 2 | 3 | import android.annotation.SuppressLint; 4 | import android.content.Context; 5 | import android.content.MutableContextWrapper; 6 | import android.os.Handler; 7 | import android.util.Base64; 8 | import android.view.ViewGroup; 9 | import android.webkit.WebChromeClient; 10 | import android.webkit.WebSettings; 11 | import android.webkit.WebView; 12 | 13 | import android.widget.FrameLayout; 14 | import com.google.gson.Gson; 15 | import com.google.gson.GsonBuilder; 16 | 17 | import org.apache.commons.lang3.StringUtils; 18 | 19 | import java.io.IOException; 20 | import java.io.InputStream; 21 | import java.net.URI; 22 | import java.net.URL; 23 | 24 | class TurbolinksHelper { 25 | private static String scriptInjectionFormat = "(function(){var parent = document.getElementsByTagName('head').item(0);var script = document.createElement('script');script.type = 'text/javascript';script.innerHTML = window.atob('%s');parent.appendChild(script);return true;})()"; 26 | 27 | // --------------------------------------------------- 28 | // Package public 29 | // --------------------------------------------------- 30 | 31 | /** 32 | *Creates the shared webView used throughout the lifetime of the TurbolinksSession.
33 | * 34 | * @param applicationContext An application context. 35 | * @return The shared WebView. 36 | */ 37 | static WebView createWebView(Context applicationContext) { 38 | MutableContextWrapper contextWrapper = new MutableContextWrapper(applicationContext); 39 | WebView webView = new WebView(contextWrapper); 40 | configureWebViewDefaults(webView); 41 | setWebViewLayoutParams(webView); 42 | 43 | return webView; 44 | } 45 | 46 | /** 47 | *Encodes URLs so they are properly escaped, specifically for Javascript calls. Liberally 48 | * borrowed from: http://stackoverflow.com/questions/3286067/url-encoding-in-android/8962879#8962879
49 | * 50 | * @param originalUrl Original URL string. 51 | * @return Encoded, escaped URL string. 52 | */ 53 | static String encodeUrl(String originalUrl) { 54 | try { 55 | URL newUrl = new URL(originalUrl); 56 | URI uri = new URI(newUrl.getProtocol(), newUrl.getUserInfo(), newUrl.getHost(), newUrl.getPort(), newUrl.getPath(), newUrl.getQuery(), newUrl.getRef()); 57 | return uri.toURL().toString(); 58 | } catch (Exception e) { 59 | return null; 60 | } 61 | } 62 | 63 | /** 64 | *Gets the base64-encoded string of a local asset file (typically a Javascript or HTML file)
65 | * 66 | * @param context An activity context. 67 | * @param filePath Local file path relative to the main/src directory. 68 | * @return A base-64 encoded string of the file contents. 69 | * @throws IOException Typically if a file cannot be found or read in. 70 | */ 71 | static String getContentFromAssetFile(Context context, String filePath) throws IOException { 72 | InputStream inputStream = context.getAssets().open(filePath); 73 | byte[] buffer = new byte[inputStream.available()]; 74 | inputStream.read(buffer); 75 | inputStream.close(); 76 | return Base64.encodeToString(buffer, Base64.NO_WRAP); 77 | } 78 | 79 | /** 80 | *Injects Javascript into the webView.
81 | * 82 | * @param turbolinksSession The TurbolinksSession. 83 | * @param context Any Android context. 84 | * @param webView The shared webView. 85 | */ 86 | static void injectTurbolinksBridge(final TurbolinksSession turbolinksSession, Context context, WebView webView) { 87 | try { 88 | String jsCall = String.format(scriptInjectionFormat, TurbolinksHelper.getContentFromAssetFile(context, "js/turbolinks_bridge.js")); 89 | runJavascriptRaw(context, webView, jsCall); 90 | } catch (IOException e) { 91 | TurbolinksLog.e("Error injecting script file into webview: " + e.toString()); 92 | } 93 | } 94 | 95 | /** 96 | *JSONifies any arbitrary number of params and runs the the Javascript function in the 97 | * webView.
98 | * 99 | * @param context An activity context. 100 | * @param webView The shared webView. 101 | * @param functionName The Javascript function name only (no parenthesis or parameters). 102 | * @param params A comma delimited list of parameter values. 103 | */ 104 | static void runJavascript(Context context, final WebView webView, String functionName, Object... params) { 105 | final String fullJs; 106 | 107 | if (params != null) { 108 | Gson gson = new GsonBuilder().disableHtmlEscaping().create(); 109 | for (int i = 0; i < params.length; i++) { 110 | params[i] = gson.toJson(params[i]); 111 | } 112 | 113 | fullJs = String.format("javascript: %s(%s);", functionName, StringUtils.join(params, ",")); 114 | } else { 115 | fullJs = String.format("javascript: %s();", functionName); 116 | } 117 | 118 | runOnMainThread(context, new Runnable() { 119 | @Override 120 | public void run() { 121 | webView.loadUrl(fullJs); 122 | } 123 | }); 124 | } 125 | 126 | /** 127 | *Runs raw Javascript that's passed in. You are responsible for encoding/escaping the 128 | * function call.
129 | * 130 | * @param context An activity context. 131 | * @param webView The shared webView. 132 | * @param javascript The raw Javascript to be executed, fully escaped/encoded in advance. 133 | */ 134 | static void runJavascriptRaw(Context context, final WebView webView, final String javascript) { 135 | runOnMainThread(context, new Runnable() { 136 | @Override 137 | public void run() { 138 | webView.loadUrl("javascript:" + javascript); 139 | } 140 | }); 141 | } 142 | 143 | /** 144 | *Executes a given runnable on the main thread.
145 | * 146 | * @param context An activity context. 147 | * @param runnable A runnable to execute on the main thread. 148 | */ 149 | static void runOnMainThread(Context context, Runnable runnable) { 150 | Handler handler = new Handler(context.getMainLooper()); 151 | handler.post(runnable); 152 | } 153 | 154 | // --------------------------------------------------- 155 | // Private 156 | // --------------------------------------------------- 157 | 158 | /** 159 | *Configures basic settings of the webView (Javascript enabled, DOM storage enabled, 160 | * database enabled).
161 | * 162 | * @param webView The shared webView. 163 | */ 164 | @SuppressLint("SetJavaScriptEnabled") 165 | private static void configureWebViewDefaults(WebView webView) { 166 | WebSettings settings = webView.getSettings(); 167 | settings.setJavaScriptEnabled(true); 168 | settings.setDomStorageEnabled(true); 169 | settings.setDatabaseEnabled(true); 170 | 171 | webView.setWebChromeClient(new WebChromeClient()); 172 | } 173 | 174 | /** 175 | * Sets the WebView's width/height layout params to MATCH_PARENT 176 | * 177 | * @param webView The shared webView. 178 | */ 179 | private static void setWebViewLayoutParams(WebView webView) { 180 | FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT); 181 | webView.setLayoutParams(params); 182 | } 183 | } 184 | -------------------------------------------------------------------------------- /turbolinks/src/main/java/com/basecamp/turbolinks/TurbolinksLog.java: -------------------------------------------------------------------------------- 1 | package com.basecamp.turbolinks; 2 | 3 | import android.util.Log; 4 | 5 | class TurbolinksLog { 6 | private static final String DEFAULT_TAG = "TurbolinksLog"; 7 | private static boolean debugLoggingEnabled = false; 8 | 9 | /** 10 | *Enables/disables debug logging.
11 | * 12 | * @param enabled True, to enable. 13 | */ 14 | static void setDebugLoggingEnabled(boolean enabled) { 15 | debugLoggingEnabled = enabled; 16 | } 17 | 18 | /** 19 | *Send a DEBUG level log statement with the default tag
20 | * 21 | * @param msg Debug message. 22 | */ 23 | static void d(String msg) { 24 | log(Log.DEBUG, DEFAULT_TAG, msg); 25 | } 26 | 27 | /** 28 | *Send a ERROR level log statement with the default tag
29 | * 30 | * @param msg Error message. 31 | */ 32 | static void e(String msg) { 33 | log(Log.ERROR, DEFAULT_TAG, msg); 34 | } 35 | 36 | /** 37 | *Default log statement called by other convenience methods.
38 | * 39 | * @param logLevel Log level of the statement. 40 | * @param tag Tag to identify the logging statement. 41 | * @param msg Message to log. 42 | */ 43 | private static void log(int logLevel, String tag, String msg) { 44 | switch (logLevel) { 45 | case Log.DEBUG: 46 | if (debugLoggingEnabled) { 47 | Log.d(tag, msg); 48 | } 49 | break; 50 | case Log.ERROR: 51 | Log.e(tag, msg); 52 | break; 53 | default: 54 | break; 55 | } 56 | } 57 | } -------------------------------------------------------------------------------- /turbolinks/src/main/java/com/basecamp/turbolinks/TurbolinksScrollUpCallback.java: -------------------------------------------------------------------------------- 1 | package com.basecamp.turbolinks; 2 | 3 | /** 4 | *Defines a callback for determining whether or not a child view can scroll up.
5 | */ 6 | interface TurbolinksScrollUpCallback { 7 | /** 8 | *Used to determine whether or not a child view can scroll up.
9 | * 10 | * @return True if the child can scroll up. False otherwise. 11 | */ 12 | boolean canChildScrollUp(); 13 | } 14 | -------------------------------------------------------------------------------- /turbolinks/src/main/java/com/basecamp/turbolinks/TurbolinksSwipeRefreshLayout.java: -------------------------------------------------------------------------------- 1 | package com.basecamp.turbolinks; 2 | 3 | import android.content.Context; 4 | import android.util.AttributeSet; 5 | 6 | import androidx.swiperefreshlayout.widget.SwipeRefreshLayout; 7 | 8 | /** 9 | *Custom SwipeRefreshLayout for Turbolinks.
10 | */ 11 | class TurbolinksSwipeRefreshLayout extends SwipeRefreshLayout { 12 | private TurbolinksScrollUpCallback callback; 13 | 14 | /** 15 | *Constructor to match SwipeRefreshLayout
16 | * 17 | * @param context Refer to SwipeRefreshLayout 18 | */ 19 | TurbolinksSwipeRefreshLayout(Context context) { 20 | super(context); 21 | } 22 | 23 | /** 24 | *Constructor to match SwipeRefreshLayout
25 | * 26 | * @param context Refer to SwipeRefreshLayout 27 | * @param attrs Refer to SwipeRefreshLayout 28 | */ 29 | TurbolinksSwipeRefreshLayout(Context context, AttributeSet attrs) { 30 | super(context, attrs); 31 | } 32 | 33 | /** 34 | *Overridden from SwipeRefreshLayout. Uses a custom callback.
35 | *If the custom callback is null, it falls back to the parent canChildScrollUp()
36 | * 37 | * @return True if the child view can scroll up. False otherwise. 38 | */ 39 | @Override 40 | public boolean canChildScrollUp() { 41 | if (callback != null) { return callback.canChildScrollUp(); } 42 | return super.canChildScrollUp(); 43 | } 44 | 45 | /** 46 | *Sets the callback to be used in canChildScrollUp().
47 | *See canChildScrollUp() to see how it's used.
48 | * 49 | * @param callback The custom callback to be set 50 | */ 51 | void setCallback(TurbolinksScrollUpCallback callback) { this.callback = callback; } 52 | } 53 | -------------------------------------------------------------------------------- /turbolinks/src/main/java/com/basecamp/turbolinks/TurbolinksTestActivity.java: -------------------------------------------------------------------------------- 1 | package com.basecamp.turbolinks; 2 | 3 | import android.annotation.SuppressLint; 4 | import android.app.Activity; 5 | 6 | /** 7 | * For testing purposes only. Robolectric sometimes struggles with mocks. 8 | */ 9 | @SuppressLint("Instantiatable") 10 | class TurbolinksTestActivity extends Activity {} 11 | -------------------------------------------------------------------------------- /turbolinks/src/main/res/layout/turbolinks_progress.xml: -------------------------------------------------------------------------------- 1 | 2 |