Sign in Join
Wiki copytemporary

pas2js resources: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: pas2js resources

OldNewLine
1+## Pas2js - Resources
2+
3+### Compiler
4+
5+The compiler supports the **{\$R somefile}** directive.
6+
7+This means that directives like
8+
9+``` pascal
10+{$R *.html}
11+```
12+
13+or
14+
15+``` pascal
16+
17+{$R left.png}
18+
19+{$R right.png}
20+
21+{$R up.png}
22+
23+{$R down.png}
24+```
25+
26+will attempt to include the specified files.
27+
28+Custom properties are defined with the semicolon as separator and colon as the name/value assignment operator. An HTML file can be added as a resource with full file name including the extension and with text/html as file format with the following command:
29+
30+``` pascal
31+{$R myFile.html;name:myFile.html;format:text/html}
32+```
33+
34+This mechanism is pluggable, and the compiler currently supports 2 mechanisms:
35+
36+- The resources are added to a javascript structure in the generated javascript.
37+
38+- The resources are emitted to a file with html snippet. this will look like this:
39+
40+For a node.js program only the Javascript mechanism can be chosen.
41+
42+``` html
43+
44+ <link rel="preload" id="resource-testres" data-unit="consoledemo"
45+href="data:text/html;base64,PGgzPlRlc3QgcmVzb3VyY2UgaW4gSFRNTDwvaDM+ClRoaXMgaXMgYSBtYWluIHByb2dyYW0gZmlsZSByZXNvdXJjZSBpbiBIVE1MLgo=" />
46+ <link rel="preload" id="resource-testb" data-unit="unitb"
47+href="data:text/html;base64,PGgzPkhlbGxvIFJlc291cmNlIFdvcmxkIFBhcnQgQjwvaDM+CjxwPgpUaGlzIG1lc3NhZ2UgaXMgc2F2ZWQgaW4gYSByZXNvdXJjZSBmaWxlIChQYXJ0IEIpLgo8L3A+Cgo=" />
48+ <link rel="preload" id="resource-testa" data-unit="unita"
49+href="data:text/html;base64,PGgzPkhlbGxvIFJlc291cmNlIFdvcmxkIFBhcnQgQTwvaDM+CjxwPgpUaGlzIG1lc3NhZ2UgaXMgc2F2ZWQgaW4gYSByZXNvdXJjZSBmaWxlIChQYXJ0IEEpLgo8L3A+Cgo=" />
50+```
51+
52+This html can be pasted into the HTML file of your project. Or the HTML snippet can be loaded dynamically. In both cases, the resource is base64-encoded before including it.
53+
54+### Command-line options
55+
56+You can select the resource mechanism to use using the -JR mechanism:
57+
58+ -Jr<x> Control writing of linked resources
59+
60+There are 3 options for the *x* value:
61+
62+- **none**: Do not write resources
63+- **js**: Write resources in Javascript structure
64+- **html=filename** : Write resources as preload links in the specified HTML file.
65+
66+
67+The HTML filename can be omitted, by default *projectfile-res.html* is used.
68+
69+### API
70+
71+The *p2jsres* unit contains the API to access the resources that were linked in at compile time.
72+
73+``` pascal
74+Function SetResourceSource(aSource : TResourceSource) : TResourceSource;
75+
76+Function GetResourceNames : TStringDynArray;
77+Function GetResourceNames(aSource : TResourceSource) : TStringDynArray;
78+
79+Function EnumResources(aCallback : TResourceEnumCallBack) : Integer;
80+Function EnumResources(aSource : TResourceSource; aCallback : TResourceEnumCallBack) : Integer;
81+
82+Function GetResourceInfo(Const aName : String; var aInfo : TResourceInfo) : Boolean;
83+Function GetResourceInfo(aSource : TResourceSource; Const aName : String; var aInfo : TResourceInfo) : Boolean;
84+
85+Procedure LoadHTMLLinkResources(const aURL : String; OnLoad : TResourcesLoadedEnumCallBack = Nil; OnError : TResourcesLoadErrorCallBack = Nil);
86+```
87+
88+These calls have the following purposes:
89+
90+- **SetResourceSource** can be used to set the mechanism by which the resource values must be accessed. It currently has the following values
91+
92+
93+* **rsJS** the resources are embedded in the Javascript.
94+
95+* **rsHTML** the resources are embedded in the HTML.
96+
97+This value is used whenever a call is made that does not specify the resource access mechanism.
98+
99+- **GetResourceNames** can be used to get a list of the available resource names. If *aSource* is omitted, the source set with *SetResourceSource* is used.
100+- **EnumResources** calls the callback *aCallBack* for every resource found. If *aSource* is omitted, the source set with *SetResourceSource* is used.
101+- **GetResourceInfo*** returns resource info for resource *aName* in the structure *aInfo*. If *aSource* is omitted, the source set with *SetResourceSource* is used.
102+- **LoadHTMLLinkResources** will load HTML resources from URL *aURL*, and will call *OnLoad* if the resources were successfully loaded, or *OnError* when the loading failed.
103+
104+The API is the same for both kind of resources, this is transparant, but you must decide what kind of resources you want to use. You can mix the 2 kinds of resources, although this is not recommended.
105+
106+### Examples
107+
108+There are 3 example programs in the demo directories which demonstrate the API. They can be viewed on-line
109+
110+[Using javascript-embedded resources](https://www.freepascal.org/~michael/pas2js-demos/resources/htmldemo.html)
111+
112+[Using HTML resources](https://www.freepascal.org/~michael/pas2js-demos/resources/htmllinkdemo.html)
113+
114+[Using dynamically loaded HTML resources](https://www.freepascal.org/~michael/pas2js-demos/resources/htmlloadlinkdemo.html)
115+
116+There is also a nodejs demo, but this one needs to be compiled from source and run on your local machine.
117+
118+### Extending the compiler
119+
120+The compiler handles the resource linking by invoking a callback for the \$R linking directive. Currently, only 2 kinds of resources are supported, but it is possible to extend this by creating additional callbacks for the compiler.
121+
122+The following extensions are planned:
123+
124+- Support {\$R *.res}
125+
126+
127+This will need to extract the actual resources from the *.res file and add them separately to the JS/HTML.
128+
129+- Add support in the Lazarus IDE to specify what resources you want to use,
130+
131+
132+and automatically include the generated HTML snippet into the project HTML.
133+
134+## Navigation
135+
136+- Back to [[pas2js]]
137+- Back to [[Pas2JS Version Changes]]
138+- Back to [[lazarus pas2js integration]]
139+
140+---
141+*From the Free Pascal wiki, page "pas2js resources", as it stood on 2023-05-04 after a change by Ondrej, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
142+Category: Pas2js

Back to history