Skip to content

Commit e2e0931

Browse files
stephenplusplusstephenplusplus
committed
support global configuration.
1 parent bd3f976 commit e2e0931

File tree

24 files changed

+891
-302
lines changed

24 files changed

+891
-302
lines changed

‎docs/components/docs/docs.html

+51-25
Original file line numberDiff line numberDiff line change
@@ -13,39 +13,65 @@ <h1 class="page-title">Node.js</h1>
1313
</header>
1414

1515
<section class="content">
16-
<article>
17-
<h1>{{module[0].toUpperCase() + module.substr(1)}}</h1>
16+
<h1>{{module[0].toUpperCase() + module.substr(1)}}</h1>
17+
<h3 class="sub-heading">
18+
<div class="toggler" ng-click="showGcloudDocs = !showGcloudDocs">
19+
<span class="toggle" ng-hide="showGcloudDocs">▹</span>
20+
<span class="toggle" ng-show="showGcloudDocs">▿</span>
21+
</div>
22+
Getting Started with <code>gcloud</code>
23+
</h3>
24+
<article ng-if="showGcloudDocs">
1825
<p>
1926
First, install <code>gcloud</code> with npm and require it into your project:
2027
</p>
2128
<div hljs>$ npm install --save gcloud</div>
2229
<div hljs>var gcloud = require('gcloud');</div>
30+
<p>
31+
There are a couple of ways to use the <code>gcloud</code> module.
32+
</p>
33+
<p>
34+
If you are running your app on Google App Engine or Google Compute Engine, you won't need to worry about supplying connection configuration options to <code>gcloud</code>&mdash; we figure that out for you.
35+
</p>
36+
<p>
37+
However, if you're running your app elsewhere, you will need to provide this information.
38+
</p>
39+
<div hljs>
40+
// App Engine and Compute Engine
41+
var gcloud = require('gcloud');
2342

24-
<article ng-if="isActiveDoc('datastore')">
25-
<p>
26-
The <code>gcloud.datastore</code> object gives you some convenience methods, as well as exposes a <code>Dataset</code> function. This will allow you to create a <code>Dataset</code>, which is the object from which you will interact with the Google Cloud Datastore.
27-
</p>
28-
<div hljs>
43+
// Elsewhere
44+
var gcloud = require('gcloud')({
45+
keyFilename: '/path/to/keyfile.json'
46+
});</div>
47+
<p>
48+
In any environment, you are free to provide these and other default properties, which eventually will be passed to the <code>gcloud</code> sub-modules (Datastore, Storage, etc.).
49+
</p>
50+
</article>
51+
<hr>
52+
<article ng-if="isActiveDoc('datastore')">
53+
<h2>Overview</h2>
54+
<p>
55+
The <code>gcloud.datastore</code> object gives you some convenience methods, as well as exposes a <code>dataset</code> function. This will allow you to create a <code>dataset</code>, which is the object from which you will interact with the Google Cloud Datastore.
56+
</p>
57+
<div hljs>
2958
var datastore = gcloud.datastore;
30-
var dataset = new datastore.Dataset();</div>
31-
<p ng-if="!isActiveUrl('/docs/datastore/dataset')">
32-
See <a href="#/docs/datastore/dataset">the Dataset documentation</a> for examples of how to query the datastore, save entities, run a transaction, and others.
33-
</p>
34-
</article>
35-
36-
<article ng-if="isActiveDoc('storage')">
37-
<p>
38-
The <code>gcloud.storage</code> object contains a <code>Bucket</code> object, which is how you will interact with your Google Cloud Storage bucket.
39-
</p>
40-
<div hljs>
41-
var storage = gcloud.storage;
42-
var bucket = new storage.Bucket({
43-
bucketName: 'MyBucket'
59+
var dataset = datastore.dataset({
60+
projectId: 'myProject',
61+
keyFilename: '/path/to/keyfile.json'
4462
});</div>
45-
<p>
46-
See examples below for more on how to upload a file, read from your bucket's files, create signed URLs, and more.
47-
</p>
48-
</article>
63+
<p ng-if="!isActiveUrl('/docs/datastore/dataset')">
64+
See <a href="#/docs/datastore/dataset">the Dataset documentation</a> for examples of how to query the datastore, save entities, run a transaction, and others.
65+
</p>
66+
</article>
67+
<article ng-if="isActiveDoc('storage')">
68+
<h2>Overview</h2>
69+
<p>
70+
The <code>gcloud.storage</code> object contains a <code>bucket</code> object, which is how you will interact with your Google Cloud Storage bucket. See the guide on <a href="https://developers.google.com/storage">Google Cloud Storage</a> to create a bucket.
71+
</p>
72+
<p>
73+
See examples below for more on how to access your bucket to upload a file, read its files, create signed URLs, and more.
74+
</p>
4975
</article>
5076

5177
<article

‎docs/components/docs/docs.js

+4-1
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,9 @@ angular
6767
return {
6868
data: obj,
6969
name: obj.ctx.name,
70+
constructor: obj.tags.some(function(tag) {
71+
return tag.type === 'constructor';
72+
}),
7073
description: $sce.trustAsHtml(
7174
formatHtml(detectLinks(detectModules(obj.description.full)))),
7275
params: obj.tags.filter(function(tag) {
@@ -95,7 +98,7 @@ angular
9598
};
9699
})
97100
.sort(function(a, b) {
98-
return a.name > b.name;
101+
return a.constructor ? -1: a.name > b.name;
99102
});
100103
};
101104
}

‎docs/css/main.css

+15
Original file line numberDiff line numberDiff line change
@@ -590,6 +590,21 @@ h2, h3 {
590590
display: block;
591591
}
592592

593+
.sub-heading {
594+
color: #5d6061;
595+
margin: 0;
596+
}
597+
598+
.toggler {
599+
float: left;
600+
min-width: 15px;
601+
margin: auto;
602+
}
603+
604+
.toggle {
605+
cursor: pointer;
606+
}
607+
593608
/*
594609
Page Title
595610
*/

‎docs/json/datastore/dataset.json

+5-5
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@
199199
{
200200
"type": "param",
201201
"types": [
202-
"string"
202+
"string="
203203
],
204204
"name": "options.projectId",
205205
"description": "- Dataset ID. This is your project ID from the Google Developers Console."
@@ -230,7 +230,7 @@
230230
},
231231
{
232232
"type": "example",
233-
"string": "var dataset = new datastore.Dataset({\n projectId: 'my-project',\n keyFilename: '/path/to/keyfile.json'\n});"
233+
"string": "var dataset = datastore.dataset({\n projectId: 'my-project',\n keyFilename: '/path/to/keyfile.json'\n});"
234234
}
235235
],
236236
"description": {
@@ -240,7 +240,7 @@
240240
},
241241
"isPrivate": false,
242242
"ignore": false,
243-
"code": "function Dataset(options) {\n options = options || {};\n\n this.connection = new conn.Connection({\n credentials: options.credentials,\n keyFilename: options.keyFilename,\n scopes: SCOPES\n });\n this.id = options.projectId;\n this.namespace = options.namespace;\n this.transaction = this.createTransaction_();\n}",
243+
"code": "function Dataset(options) {\n if (!(this instanceof Dataset)) {\n return new Dataset(options);\n }\n\n options = options || {};\n\n this.connection = new conn.Connection({\n credentials: options.credentials,\n keyFilename: options.keyFilename,\n scopes: SCOPES\n });\n this.projectId = options.projectId;\n this.namespace = options.namespace;\n this.transaction = this.createTransaction_();\n}",
244244
"ctx": {
245245
"type": "function",
246246
"name": "Dataset",
@@ -251,7 +251,7 @@
251251
"tags": [
252252
{
253253
"type": "example",
254-
"string": "var key;\n\n// Create a key from the dataset's namespace.\nkey = dataset.key('Company', 123);\n\n// Create a key from a provided namespace and path.\nkey = dataset.key({\n namespace: 'My-NS',\n path: ['Company', 123]\n});"
254+
"string": "// Create a key from the dataset's namespace.\nvar Company123 = dataset.key('Company', 123);\n\n// Create a key from a provided namespace and path.\nvar NSCompany123 = dataset.key({\n namespace: 'My-NS',\n path: ['Company', 123]\n});"
255255
}
256256
],
257257
"description": {
@@ -632,7 +632,7 @@
632632
},
633633
"isPrivate": true,
634634
"ignore": false,
635-
"code": "Dataset.prototype.createTransaction_ = function() {\n return new Transaction(this.connection, this.id);\n};\n\nmodule.exports = Dataset;",
635+
"code": "Dataset.prototype.createTransaction_ = function() {\n return new Transaction(this.connection, this.projectId);\n};\n\nmodule.exports = Dataset;",
636636
"ctx": {
637637
"type": "method",
638638
"constructor": "Dataset",

‎docs/json/datastore/index.json

+129-23
Original file line numberDiff line numberDiff line change
@@ -43,43 +43,149 @@
4343
}
4444
},
4545
{
46-
"tags": [],
46+
"tags": [
47+
{
48+
"type": "private",
49+
"visibility": "private"
50+
}
51+
],
4752
"description": {
48-
"full": "<p>@alias module:datastore</p>",
49-
"summary": "<p>@alias module:datastore</p>",
53+
"full": "<p>@type module:common/util</p>",
54+
"summary": "<p>@type module:common/util</p>",
5055
"body": ""
5156
},
52-
"isPrivate": false,
53-
"ignore": true,
54-
"code": "var datastore = {};",
57+
"isPrivate": true,
58+
"ignore": false,
59+
"code": "var util = require('../common/util.js');",
5560
"ctx": {
5661
"type": "declaration",
57-
"name": "datastore",
58-
"value": "{}",
59-
"string": "datastore"
62+
"name": "util",
63+
"value": "require('../common/util.js')",
64+
"string": "util"
65+
}
66+
},
67+
{
68+
"tags": [
69+
{
70+
"type": "private",
71+
"visibility": "private"
72+
}
73+
],
74+
"description": {
75+
"full": "<p>@type module:datastore/dataset</p>",
76+
"summary": "<p>@type module:datastore/dataset</p>",
77+
"body": ""
78+
},
79+
"isPrivate": true,
80+
"ignore": false,
81+
"code": "var Dataset = require('./dataset');",
82+
"ctx": {
83+
"type": "declaration",
84+
"name": "Dataset",
85+
"value": "require('./dataset')",
86+
"string": "Dataset"
6087
}
6188
},
6289
{
6390
"tags": [
6491
{
6592
"type": "example",
66-
"string": "var gcloud = require('gcloud');\nvar datastore = gcloud.datastore;\n\n// Create a Dataset object.\nvar dataset = new datastore.Dataset();"
93+
"string": "var datastore = require('gcloud/lib/datastore')({\n keyFilename: '/path/to/keyfile.json'\n});\n\nvar dataset = datastore.dataset();\n// equal to:\n// datastore.dataset({\n// keyFilename: '/path/to/keyfile.json'\n// });"
6794
}
6895
],
6996
"description": {
70-
"full": "<p>@see {module:datastore/dataset}</p>",
71-
"summary": "<p>@see {module:datastore/dataset}</p>",
97+
"full": "<p>Developer Documentation</p><p>Invoking the Datastore class allows you to provide configuration up-front.<br />This configuration will be used for future invokations of the returned<br /><code>dataset</code> method.</p>",
98+
"summary": "<p>Developer Documentation</p>",
99+
"body": "<p>Invoking the Datastore class allows you to provide configuration up-front.<br />This configuration will be used for future invokations of the returned<br /><code>dataset</code> method.</p>"
100+
},
101+
"isPrivate": false,
102+
"ignore": true
103+
},
104+
{
105+
"tags": [
106+
{
107+
"type": "alias",
108+
"string": "module:datastore"
109+
},
110+
{
111+
"type": "constructor",
112+
"string": ""
113+
},
114+
{
115+
"type": "example",
116+
"string": "var gcloud = require('gcloud');\n\n// Providing configuration details up-front.\nvar myProject = gcloud({\n keyFilename: '/path/to/keyfile.json',\n projectId: 'my-project'\n});\n\nvar dataset = myProject.datastore.dataset();\n\n\n// Overriding default configuration details.\nvar anotherDataset = myProject.datastore.dataset({\n keyFilename: '/path/to/another/keyfile.json'\n});\n\n\n// Not using a default configuration.\nvar myOtherProject = gcloud.datastore.dataset({\n keyFilename: '/path/to/keyfile.json',\n projectId: 'my-project'\n});"
117+
}
118+
],
119+
"description": {
120+
"full": "<p>The example below will demonstrate the different usage patterns your app may<br />need to support to retrieve a datastore object.</p>",
121+
"summary": "<p>The example below will demonstrate the different usage patterns your app may<br />need to support to retrieve a datastore object.</p>",
72122
"body": ""
73123
},
74124
"isPrivate": false,
75125
"ignore": false,
76-
"code": "datastore.Dataset = require('./dataset');",
126+
"code": "function Datastore(config) {\n if (!(this instanceof Datastore)) {\n return new Datastore(config);\n }\n this.config = config || {};\n}",
127+
"ctx": {
128+
"type": "function",
129+
"name": "Datastore",
130+
"string": "Datastore()"
131+
}
132+
},
133+
{
134+
"tags": [
135+
{
136+
"type": "example",
137+
"string": "var datastore = require('gcloud/lib/datastore');\n\n// Create a Dataset object.\nvar dataset = datastore.dataset({\n keyFilename: '/path/to/keyfile.json'\n});"
138+
}
139+
],
140+
"description": {
141+
"full": "<p>Developer Documentation</p><p>Use this static method to create a dataset without any pre-configured<br />options.</p>",
142+
"summary": "<p>Developer Documentation</p>",
143+
"body": "<p>Use this static method to create a dataset without any pre-configured<br />options.</p>"
144+
},
145+
"isPrivate": false,
146+
"ignore": true,
147+
"code": "Datastore.dataset = Dataset;",
77148
"ctx": {
78149
"type": "property",
79-
"receiver": "datastore",
80-
"name": "Dataset",
81-
"value": "require('./dataset')",
82-
"string": "datastore.Dataset"
150+
"receiver": "Datastore",
151+
"name": "dataset",
152+
"value": "Dataset",
153+
"string": "Datastore.dataset"
154+
}
155+
},
156+
{
157+
"tags": [
158+
{
159+
"type": "param",
160+
"types": [
161+
"object="
162+
],
163+
"name": "options",
164+
"description": "- Configuration object."
165+
},
166+
{
167+
"type": "return",
168+
"types": [
169+
"module:datastore",
170+
"dataset"
171+
],
172+
"description": ""
173+
}
174+
],
175+
"description": {
176+
"full": "<p>Developer Documentation</p><p>Create a dataset using the instance method when you want to use your<br />pre-configured options from the Datastore instance.</p>",
177+
"summary": "<p>Developer Documentation</p>",
178+
"body": "<p>Create a dataset using the instance method when you want to use your<br />pre-configured options from the Datastore instance.</p>"
179+
},
180+
"isPrivate": false,
181+
"ignore": true,
182+
"code": "Datastore.prototype.dataset = function(options) {\n // Mix in global config data to the provided options.\n return new Dataset(util.extend(true, {}, this.config, options));\n};",
183+
"ctx": {
184+
"type": "method",
185+
"constructor": "Datastore",
186+
"cons": "Datastore",
187+
"name": "dataset",
188+
"string": "Datastore.prototype.dataset()"
83189
}
84190
},
85191
{
@@ -111,12 +217,12 @@
111217
},
112218
"isPrivate": false,
113219
"ignore": false,
114-
"code": "datastore.int = function(value) {\n return new entity.Int(value);\n};",
220+
"code": "Datastore.int = function(value) {\n return new entity.Int(value);\n};",
115221
"ctx": {
116222
"type": "method",
117-
"receiver": "datastore",
223+
"receiver": "Datastore",
118224
"name": "int",
119-
"string": "datastore.int()"
225+
"string": "Datastore.int()"
120226
}
121227
},
122228
{
@@ -148,12 +254,12 @@
148254
},
149255
"isPrivate": false,
150256
"ignore": false,
151-
"code": "datastore.double = function(value) {\n return new entity.Double(value);\n};\n\nmodule.exports = datastore;",
257+
"code": "Datastore.double = function(value) {\n return new entity.Double(value);\n};\n\nmodule.exports = Datastore;",
152258
"ctx": {
153259
"type": "method",
154-
"receiver": "datastore",
260+
"receiver": "Datastore",
155261
"name": "double",
156-
"string": "datastore.double()"
262+
"string": "Datastore.double()"
157263
}
158264
}
159265
]

0 commit comments

Comments
 (0)