aboutsummaryrefslogtreecommitdiff
path: root/chrome/help.html
blob: dc8d756643b5982d1d312a5c5907ddaedb516efb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
<!-- $Id$ -->
<html>
	<head>
		<title>URL Rewriter Help</title>
		<style type="text/css">
			body { font-family: Verdana, Arial; color:black; background-color:white; font-size:0.9em; }
			a { color:blue; }
		</style>
	</head>
	<body>
		<h1>URL Rewriter Help</h1>
		<h3>Table of contents</h3>
		<ul>
			<li><a href="#whatisredirector">What is URL Rewriter?</a></li>
			<li><a href="#basicusage">Basic usage</a>
				<ul>
					<li><a href="#exampleurl">Example url</a></li>
					<li><a href="#includepattern">Include pattern</a></li>
					<li><a href="#excludepattern">Exclude pattern</a></li>
					<li><a href="#redirectto">Redirect to</a></li>
					<li><a href="#patterntype">Pattern type</a></li>
					<li><a href="#unescapematches">Unescape matches</a></li>
				</ul>
			</li>
			<li><a href="#wildcards">Wildcards</a></li>
			<li><a href="#regularexpressions">Regular expressions</a></li>
			<li><a href="#examples">Examples</a>
				<ol>
					<li><a href="#ex1">Static redirect</a></li>
					<li><a href="#ex2">Redirect using query string parameter and wildcards</a></li>
					<li><a href="#ex3">Redirect using query string parameter and regular expressions</a></li>
					<li><a href="#ex4">Redirect to a different folder using wildcards</a></li>
					<li><a href="#ex5">Redirect http to https using wildcards</a></li>
				</ol>
			
			</li>
		</ul>
		
		
		<a name="whatisredirector"></a>
		<h4>What is URL Rewriter?</h4>
		
		<p>URL Rewriter is an extension for Pale Moon that allows you to automatically redirect from
		one webpage to another. For example, every time you visit http://abc.com you will automatically
		load http://def.com instead. This can be useful for instance to always redirect articles to printer friendly
		versions, redirect http:// to https:// for sites that support both, bypass advertising pages that appear before
		being able to view certain pages and more.</p>
		
		<a name="basicusage"></a>
		<h4>Basic usage</h4>
		<p>To add a new redirect you can go to the <em>Tools</em> menuitem and select <em>URL Rewriter</em>. That will
		open the <em>URL Rewriter settings</em> window which shows all your redirects. The window can also be opened
		by right clicking on the <strong>R</strong> icon in your statusbar. 
		There you can press the <em>Add...</em> button and then you can enter the details for the new redirect. A redirect
		consists of a few things:
		<ul>
			<li><a name="exampleurl"></a><strong>Example url:</strong> This is an example of an url you want to redirect. It is not really used for anything,
			it's just there to show what types of urls you're targetting. You can leave this out, but then you can't use the <em>Test pattern</em> button.</li>
			
			<li><a name="includepattern"></a><strong>Include pattern:</strong> This is pattern for the urls you want to redirect. In the simplest case, where you just want
			to redirect one specific url to another then this will just be the exact url you want to redirect. For instance, if you just want http://aaa.com to
			redirect to http://bbb.com then <em>Include pattern</em> will just be http://aaa.com. For more complex patterns that match many
			urls you can use either <a href="#wildcards">wildcards</a> or <a href="#regularexpressions">regular expressions</a>.</li>
			
            <li><a name="excludepattern"></a><strong>Exclude pattern:</strong> Urls that match this pattern will never be redirected. This is not necessary to
            fill out, but can be useful when you want to redirect all urls that contain some text except if they contain some other text. 
            Redirects like that can often be done with a complex regular expression, but using an exclude pattern makes it much simpler. The exclude
            patterns can use wildcard characters or regular expressions like the include patterns.</li>

            <li><a name="redirectto"></a><strong>Redirect to:</strong> This is the url that you will be redirected to when you open any page where the url matches the
            include pattern. You can use the special signs $1, $2, $3 etc. in the url, they will be replaced by the results of captures with regular
            expressions or stars with wildcards. For instance, if you have the include pattern <em>http://google.com/*</em>, redirect to <em>http://froogle.com/$1</em>
            and you open the page http://google.com/foobar, then you will be redireced to http://froogle.com/foobar, since 'foobar' was what the star replaced. $1 is for the
            first star in the pattern, $2 for the second and so on. For regular expression $1 is for the first parantheses, $2 for the second etc.</li>
		
            <li><a name="patterntype"></a><strong>Pattern type:</strong> This specifies how URL Rewriter should interpret the patterns, either as
            <a href="#wildcards">wildcards</a> or <a href="#regularexpressions#">regular expressions</a>.</li>

            <li><a name="unescapematches"></a><strong>Unescape matches:</strong> A common usage of URL Rewriter is to catch urls like
            <em>http://foo.com/redirect.php?url=http%3A%2F%2Fbar%2Ecom%2Fpath</em> and try to catch the url parameter and redirect to it. A pattern
            like <em>http://foo.com/redirect.php?url=*</em> might be used for that purpose. However, if the url parameter is <em>escaped</em> (also known
            as <em>urlencoded</em>) then that won't work. In the url above we see that it starts with <em>http%3A%2F%2F</em> instead of <em>http://</em>, and Pale Moon
            won't accept this as a new url to redirect to. So, in cases like these you can check the <em>Unescape matches</em> option and then all
            matches will be unescaped (turned from e.g. <em>http%3A%2F%2Fbar%2Ecom</em> to <em>http://bar.com</em>) before being inserted into the target url.
            </li>
            
		</ul>
		</p>

		<a name="wildcards"></a>
		<h4>Wildcards</h4>
		
		<p>Wildcards are the simplest way to specify include and exclude patterns. When you create a wildcard pattern there
		is just one special character, the asterisk *. An asterisk in your pattern will match zero or more characters and you can
		have more than one star in your pattern. Some examples:
			<ul>
				<li><em>http://example.com/*</em> matches http://example.com/, http://example.com/foo, http://example.com/bar and all other urls that start with http://example.com/.</li>
				<li><em>http://*.example.com</em> matches all subdomains of example.com, like http://www.example.com, http://mail.example.com.</li>
				<li><em>http*://example.com</em> matches both http://example.com and https://example.com.</li>
				<li><em>http://example.com/index.asp*</em> matches http://example.com/index.asp, http://example.com/index.asp?a=b&c=d.</li>
			</ul>
		$1, $2, $3 in the redirect urls will match the text that the stars matched. Examples:
			<ul>
				<li><em>http://example.com/*</em> matches http://example.com/foobar, $1 is foobar.</li>
				<li><em>http://*.example.com/*</em> matches http://www.example.com/foobar, $1 is www, $2 is foobar.</li>
			</ul>
		</p>
		
		<a name="regularexpressions"></a>
		<h4>Regular expressions</h4>
		
		<p>Regular expressions allow for more complicated patterns but they are a lot harder to learn than wildcards. I'm not gonna
		create a regex tutorial here but normal javascript regex syntax works, look at <a href="http://regular-expressions.info" target="_blank">http://regular-expressions.info</a> for
		an introduction to regular expressions. $1,$2 etc. can be used in the redirect url and will be replaced with contents of captures in
		the regular expressions. Captures are specified with parantheses. Example: http://example.com/index.asp\?id=(\d+) will match the url
		http://example.com/index.asp?id=12345 and $1 will be replaced by 12345. (A common mistake in regex patterns is to forget to escape
		the ? sign in the querystring of the url. ? is a special character in regular expressions so if you want to match an url with a querystring
		you should escape it as \?).</p>

		<a name="examples"></a>
		<h4>Examples</h4>
		
		<ol>
			<li>
				<strong><a name="ex1"></a>Static redirect</strong><br/>
				Redirects from http://example.com/foo to http://example.com/bar
				<p>
					<strong>Include pattern:</strong> http://example.com/foo<br/>
					<strong>Exclude pattern:</strong><br/>
					<strong>Redirect to:</strong> http://example.com/bar<br/>
					<strong>Pattern type:</strong> Wildcard<br />
				</p>
				
			</li>
			<li>
				<strong><a name="ex2"></a>Redirect using query string parameter and wildcards</strong><br/>
				Redirects from http://example.com/index.php?id=12345&a=b to http://example.com/printerfriendly.php?id=12345&a=b
				where 12345 could be any number.
				<p>
					<strong>Include pattern:</strong> http://example.com/index.php?id=*&a=b<br/>
					<strong>Exclude pattern:</strong><br/>
					<strong>Redirect to:</strong> http://example.com/printerfriendly.com?id=$1&a=b<br/>
					<strong>Pattern type:</strong> Wildcard<br />
				</p>
			</li>
			<li>
				<strong><a name="ex3"></a>Redirect using query string parameter and regular expressions</strong><br/>
				Redirects from http://example.com/index.php?id=12345&a=b to http://example.com/printerfriendly.php?id=12345&a=b
				where 12345 could be any number.
				<p>
					<strong>Include pattern:</strong> http://example.com/index.php\?id=(\d+)&a=b<br/>
					<strong>Exclude pattern:</strong><br/>
					<strong>Redirect to:</strong> http://example.com/printerfriendly.com?id=$1&a=b<br/>
					<strong>Pattern type:</strong> Regular Expression<br />
				</p>
			</li>
			<li>
				<strong><a name="ex4"></a>Redirect to a different folder using wildcards</strong><br/>
				Redirects from http://example.com/category/fish/index.php to http://example.com/category/cats/index.php
				where fish could be any word. The exclude pattern makes sure that there is only one
				folder there, so for instance http://example.com/category/fish/cat/mouse/index.php would not match.
				<p>
					<strong>Include pattern:</strong> http://example.com/category/*/index.php<br/>
					<strong>Exclude pattern:</strong> http://example.com/category/*/*/index.php<br/>
					<strong>Redirect to:</strong> http://example.com/category/cats/index.php<br/>
					<strong>Pattern type:</strong> Wildcard<br />
				</p>
			</li>
			<li>
				<strong><a name="ex5"></a>Redirect http to https using wildcards</strong><br/>
				Redirects from http://mail.google.com/randomcharacters to https://mail.google.com/randomcharacters
				where randomcharacters could be anything.
				<p>
					<strong>Include pattern:</strong> http://mail.google.com*<br/>
					<strong>Exclude pattern:</strong><br/>
					<strong>Redirect to:</strong> https://mail.google.com$1<br/>
					<strong>Pattern type:</strong> Wildcard<br />
				</p>
			</li>
		</ol>
	</body>
</html>