javascript/README

   1 Info:
   2 =====
   3 Google's JavaScript library for parsing, formatting, and validating
   4 international phone numbers.
   5
   6
   7 How to setup:
   8 =============
   9 1.  Checkout closure-library, closure-compiler, closure-linter and python-gflags
  10     next to libphonenumber:
  11
  12 e.g.
  13 git clone https://github.com/googlei18n/libphonenumber/
  14 git clone https://github.com/google/closure-library/
  15 git clone https://github.com/google/closure-compiler.git
  16 svn checkout http://closure-linter.googlecode.com/svn/trunk/ ~/src/closure-linter
  17 svn checkout http://python-gflags.googlecode.com/svn/trunk/ ~/src/python-gflags
  18
  19 (If you don't checkout the dependencies next to libphonenumber:
  20 a. change the path of the <script src=""> in the html pages to point to wherever
  21    base.js is located
  22 b. update javascript/build.xml with the correct paths)
  23
  24 2.  Run the unit tests to make sure everything is working. Open the following
  25 pages with your web browser:
  26   javascript/i18n/phonenumbers/phonenumberutil_test.html
  27   javascript/i18n/phonenumbers/asyoutypeformatter_test.html
  28
  29 3.  Run the demo: javascript/i18n/phonenumbers/demo.html
  30
  31
  32 How to compile:
  33 ===============
  34 1.  Build Closure's compiler.jar:
  35
  36 e.g.
  37 ant -f ~/src/closure-compiler/build.xml
  38
  39 2.  Compile the demo.js and all its dependencies to one file: demo-compiled.js:
  40
  41 ant -f javascript/build.xml compile-demo
  42
  43 3.  Run the compiled demo: javascript/i18n/phonenumbers/demo-compiled.html
  44
  45
  46 How to use:
  47 ===========
  48 To use and compile the library in your own project, use the
  49 javascript/i18n/phonenumbers/demo.js as an example. You will need to
  50 goog.exportSymbol all the methods you use in your html so that the compiler
  51 won't rename them. You can then invoke the compiler similarly to how the
  52 compile-demo ant target in javascript/build.xml invokes it.
  53
  54
  55 How to update:
  56 ==============
  57 The JavaScript library is ported from the Java implementation (revision 536).
  58 When the Java project gets updated follow these steps to update the JavaScript
  59 project:
  60
  61 1.  If the protocol buffers (phonemetadata.proto and phonenumber.proto)
  62     have changed:
  63   a.  Manually update the .pb.js files with the changes of the .proto files.
  64   b.  Manually update the toJsArray() Java methods in
  65       tools/java/java-build/src/com/google/i18n/phonenumbers/BuildMetadataJsonFromXml.java
  66   c.  Build tools/java/java-build/target/java-build-1.0-SNAPSHOT-jar-with-dependencies.jar
  67       by running:
  68       mvn -f tools/java/java-build/pom.xml package
  69
  70 2.  If the phone number metadata in the XML format has changed
  71     (resources/PhoneNumberMetadata.xml)
  72     run the following commands to regenerate metadata.js and
  73     metadatafortesting.js:
  74
  75     ant -f java/build.xml build-js-metadata
  76
  77 3.  Manually port any changes of the Java code to the JavaScript code:
  78       PhoneNumberUtil.java => phonenumberutil.js
  79       AsYouTypeFormatter.java => asyoutypeformatter.js
  80       PhoneNumberUtilTest.java => phonenumberutil_test.js
  81       AsYouTypeFormatterTest.java => asyoutypeformatter_test.js
  82
  83 4.  Run the Closure Compiler to get your changes syntax and type checked.
  84     This will also generate demo-compiled.js used by demo-compiler.html
  85     (TODO: Use target "compile" rather than "compile-demo" once
  86      visibility issues for getExtractedNationalPrefix_ have been resolved):
  87
  88     ant -f javascript/build.xml compile-demo
  89
  90 5.  Run the Closure Linter to lint the JavaScript files:
  91
  92     ant -f javascript/build.xml lint
  93
  94
  95 TODO:
  96 =====
  97 Port functionality to extract phone-numbers from text (findNumbers).
  98 Port offline phone number geocoder.
  99 Enable PhoneNumberUtil to handle all digits, rather than a subset
 100 (JavaScript has no equivalent to the Java Character.digit).
 101 Port ShortNumberInfo.