From 64e686d34fed1f268c4162308854bab2a9fa376d Mon Sep 17 00:00:00 2001 From: Todd Werth Date: Sat, 18 Apr 2015 16:25:28 -0700 Subject: [PATCH] More documentation udpates --- docs/cookbook/actions.md | 2 -- docs/cookbook/animations.md | 2 -- docs/cookbook/app.md | 2 -- docs/cookbook/attributes.md | 2 -- docs/cookbook/colors.md | 9 +++---- docs/cookbook/command_line.md | 2 -- docs/cookbook/core_data.md | 2 -- docs/cookbook/device.md | 2 -- docs/cookbook/events_and_gestures.md | 2 -- docs/cookbook/fonts.md | 2 -- docs/cookbook/format.md | 2 -- docs/cookbook/images.md | 2 -- docs/cookbook/layout_a_screen.md | 2 -- docs/cookbook/project.md | 12 --------- docs/cookbook/screens.md | 2 -- docs/cookbook/selecting.md | 2 -- docs/cookbook/tagging.md | 2 -- docs/cookbook/timers.md | 2 -- docs/cookbook/traversing.md | 24 ++++++++---------- docs/cookbook/validations.md | 38 +++++++++++++--------------- 20 files changed, 33 insertions(+), 82 deletions(-) diff --git a/docs/cookbook/actions.md b/docs/cookbook/actions.md index abe1374..27f7c58 100644 --- a/docs/cookbook/actions.md +++ b/docs/cookbook/actions.md @@ -1,5 +1,3 @@ -# Misc actions, such as hiding, focusing, etc - ```ruby find(UILabel).send(:some_method, args) find(my_view).hide diff --git a/docs/cookbook/animations.md b/docs/cookbook/animations.md index 27833a2..589ae51 100644 --- a/docs/cookbook/animations.md +++ b/docs/cookbook/animations.md @@ -1,5 +1,3 @@ -# Animating and Animations - ## Animating The most basic: diff --git a/docs/cookbook/app.md b/docs/cookbook/app.md index 646bd80..95a2949 100644 --- a/docs/cookbook/app.md +++ b/docs/cookbook/app.md @@ -1,5 +1,3 @@ -# The application (app) and accessing it - ```ruby app.window app.delegate diff --git a/docs/cookbook/attributes.md b/docs/cookbook/attributes.md index 5b55784..ea79867 100644 --- a/docs/cookbook/attributes.md +++ b/docs/cookbook/attributes.md @@ -1,5 +1,3 @@ -# Updating data or attributes - RedPotion provides a variety of ways to update a view's data or attributes. All of which are chain-able. ### Data diff --git a/docs/cookbook/colors.md b/docs/cookbook/colors.md index bf47687..ebc0b51 100644 --- a/docs/cookbook/colors.md +++ b/docs/cookbook/colors.md @@ -1,7 +1,6 @@ -# Colors +## Get colors ```ruby - color.red color('#ffffff') color('ffffff') @@ -10,16 +9,16 @@ color(128, 128, 128, 0.5) color(r: 128, g: 128, b: 128, a: 0.5) color(red: 128, green: 128, blue: 128, alpha: 0.5) color(h: 4, s: 3, b: 2, a: 1) +``` +## Add a new standard color -# Add a new standard color - +```ruby color.add_named :pitch_black, '#000000' # Or color.add_named :pitch_black, color.black # have color and you need to just adjust one of the values? color(base: color.black, a: 0.5) - ``` Color has a `with` method. Allowing you to build a color from an existing color easily diff --git a/docs/cookbook/command_line.md b/docs/cookbook/command_line.md index 0f76542..15f52b4 100644 --- a/docs/cookbook/command_line.md +++ b/docs/cookbook/command_line.md @@ -1,5 +1,3 @@ -# Command-line and REPL tools - ## Live stylesheet reloading In REPL, type: `live_stylesheets` diff --git a/docs/cookbook/core_data.md b/docs/cookbook/core_data.md index 1d6ce53..788b548 100644 --- a/docs/cookbook/core_data.md +++ b/docs/cookbook/core_data.md @@ -1,5 +1,3 @@ -# Using a local database - RedPotion uses Core Data as its local data store. Specifically it uses the [CDQ](https://github.com/infinitered/cdq) gem. ## Schema diff --git a/docs/cookbook/device.md b/docs/cookbook/device.md index 2eff0bf..cf4ebeb 100644 --- a/docs/cookbook/device.md +++ b/docs/cookbook/device.md @@ -1,5 +1,3 @@ -# The device - ```ruby device.screen device.width # screen width diff --git a/docs/cookbook/events_and_gestures.md b/docs/cookbook/events_and_gestures.md index 8f57218..4a477f7 100644 --- a/docs/cookbook/events_and_gestures.md +++ b/docs/cookbook/events_and_gestures.md @@ -1,5 +1,3 @@ -# Events, gestures: programming behaviour - ## On / Off To add an event, use .on, to remove it it, use .off diff --git a/docs/cookbook/fonts.md b/docs/cookbook/fonts.md index c06ca33..02f1053 100644 --- a/docs/cookbook/fonts.md +++ b/docs/cookbook/fonts.md @@ -1,5 +1,3 @@ -# Fonts - ```ruby font.family_list # useful in console font.for_family('Helvetica') # useful in console diff --git a/docs/cookbook/format.md b/docs/cookbook/format.md index a32f990..0406d51 100644 --- a/docs/cookbook/format.md +++ b/docs/cookbook/format.md @@ -1,5 +1,3 @@ -# Formatting numbers and dates - A performant way to format numbers and dates. ```ruby diff --git a/docs/cookbook/images.md b/docs/cookbook/images.md index 957b261..77d4286 100644 --- a/docs/cookbook/images.md +++ b/docs/cookbook/images.md @@ -1,5 +1,3 @@ -# Images, icons, and photos - ## General images RedPotion provides various features for dealing with images. diff --git a/docs/cookbook/layout_a_screen.md b/docs/cookbook/layout_a_screen.md index b6f527b..8cae5cb 100644 --- a/docs/cookbook/layout_a_screen.md +++ b/docs/cookbook/layout_a_screen.md @@ -1,5 +1,3 @@ -# Laying out a screen - This example applies layouts in the stylesheet (thus why it's st.frame =), but you could also apply them using the .layout method. rect_example diff --git a/docs/cookbook/project.md b/docs/cookbook/project.md index 1477380..e43954e 100644 --- a/docs/cookbook/project.md +++ b/docs/cookbook/project.md @@ -1,22 +1,10 @@ -# Find out about the project, are you in the simulator, dev, release, on what OS, what device, etc - ## What is the app name and indentifier? ```ruby -app.window -app.delegate -app.environment -app.release? # .production? also -app.test? -app.development? -app.version app.name app.identifier -app.resource_path -app.document_path ``` - ## Can I find out info about for the project at runtime? This only works in development environment: diff --git a/docs/cookbook/screens.md b/docs/cookbook/screens.md index 5b02746..3681d04 100644 --- a/docs/cookbook/screens.md +++ b/docs/cookbook/screens.md @@ -1,3 +1 @@ -# Create screens - Until we get this fully documented, please use [ProMotion's great docs](http://promotion.readthedocs.org/en/master/) for everything to do with screens. diff --git a/docs/cookbook/selecting.md b/docs/cookbook/selecting.md index 3f1b83b..8238384 100644 --- a/docs/cookbook/selecting.md +++ b/docs/cookbook/selecting.md @@ -1,5 +1,3 @@ -# Selecting or finding views - You can select a view using the following: * Constant diff --git a/docs/cookbook/tagging.md b/docs/cookbook/tagging.md index 56127f9..1e58366 100644 --- a/docs/cookbook/tagging.md +++ b/docs/cookbook/tagging.md @@ -1,5 +1,3 @@ -# Tagging views - ```ruby # Add tags find(my_view).tag(:your_tag) diff --git a/docs/cookbook/timers.md b/docs/cookbook/timers.md index 39485f8..6e920db 100644 --- a/docs/cookbook/timers.md +++ b/docs/cookbook/timers.md @@ -1,5 +1,3 @@ -# Timers and delays. Do something every second - ```ruby app.after 2 { do_something } # after 2 seconds app.every 5 { do_something_repetitive } # every 5 seconds diff --git a/docs/cookbook/traversing.md b/docs/cookbook/traversing.md index c5ade11..6051318 100644 --- a/docs/cookbook/traversing.md +++ b/docs/cookbook/traversing.md @@ -1,8 +1,6 @@ -# Finding your way around. Traversing the app, screens, and views - Moving around the subview tree. -#### Screen, controller, and root_view +## Screen, controller, and root_view ```ruby find.screen # alias to find.view_controller @@ -10,19 +8,19 @@ find.view_controller find.root_view # View of the view_controller ``` -#### Window of the root_view +## Window of the root_view ```ruby find.window ``` -#### All subviews, subviews of subviews, etc for root_view: +## All subviews, subviews of subviews, etc for root_view: ```ruby find.all ``` -#### Find +## Find Find all children/grandchildren/etc: @@ -36,7 +34,7 @@ More commonly, you are searching for something: find(my_view).find(UITextField) ``` -#### Closest +## Closest Closest is interesting, and very useful. It searches through parents/grandparents/etc and finds the **first** occurrence that matches the selectors: @@ -50,20 +48,20 @@ Let's say that someone clicked on a button in a table cell. You want to find and find(sender).closest(UITableViewCell).find(UIButton).hide ``` -#### Children of selected view, views, or root_view +## Children of selected view, views, or root_view ```ruby find.children # All children (but not grandchildren) of root_view find(:section).children # All children of any view with the tag or stylename of :section ``` -##### You can also add selectors +### You can also add selectors ```ruby find(:section).children(UILabel) # All children (that are of type UILabel of any view with the tag or stylename of :section ``` -#### Parent or parents of selected view(s) +## Parent or parents of selected view(s) ```ruby find(my_view).parent # superview of my_view @@ -71,7 +69,7 @@ find(my_view).parents # superview of my_view, plus any grandparents, great-grand find(UIButton).parent # all parents of all buttons ``` -#### Siblings +## Siblings Find all your siblings: @@ -91,7 +89,7 @@ Get the sibling right next to the view, above the view: find(my_view).prev ``` -#### And, not, back, and self +## And, not, back, and self These four could be thought of as Selectors, not Traversing. They kind of go in both, anywho. @@ -119,6 +117,6 @@ Back is interesting, it moves you back up the chain one. In this example, we fin find(test_view).find(UIImageView).tag(:foo).back.find(UILabel).tag(:bar) ``` -#### Filter +## Filter Filter is what everything else uses (parents, children, find, etc), you typically don't use it yourself. diff --git a/docs/cookbook/validations.md b/docs/cookbook/validations.md index 88e12f5..fd4c7fe 100644 --- a/docs/cookbook/validations.md +++ b/docs/cookbook/validations.md @@ -1,5 +1,3 @@ -# Validating data, text, text boxes, etc - RedPotion allows a RubyMotion validation library to help you to validate data in a way that makes life easy. There are two main aspects, so you can utilize RMQ validation to meet your needs: @@ -14,12 +12,12 @@ rmq.validation.valid?('https://www.infinitered.com', :url) #true rmq.validation.valid?(98.6, :number) #true # Examples of Selection Rules -rmq.append(UITextField, :user).validates(:email) -rmq.append(UITextField, :password).validates(:strong_password) -rmq.append(UITextField, :pin).validates(:digits).validates(:length, exact_length: 5) +append(UITextField, :user).validates(:email) +append(UITextField, :password).validates(:strong_password) +append(UITextField, :pin).validates(:digits).validates(:length, exact_length: 5) -rmq(UITextField).valid? # checks if selected is valid -rmq(:password).clear_validations! #removes validations on selected +find(UITextField).valid? # checks if selected is valid +find(:password).clear_validations! #removes validations on selected ``` All validations are tied to RMQ Debugging mode. So you can turn them off in the application by entering debug mode. You can do so by starting your project with the flag set to true `rake rmq_debug=true` OR by setting the flag in the code/REPL with `RubyMotionQuery::RMQ.debugging = true`. @@ -85,24 +83,24 @@ rmq.validation.valid?(some_url_input, :url, white_list: ['http://localhost:8080' For a more robust use of RMQ and validation, there's an arsenal of RMQ integrated validation options and events. ANY utility rule can be used in a selection validation. Simply chain the validation you'd like applied to the UIViews you've selected with RMQ. For example: ```ruby # attach validation rules to UIViews -rmq.append(UITextField, :weight).validates(:digits) -rmq.append(UITextField, :name).validates(:presence) +append(UITextField, :weight).validates(:digits) +append(UITextField, :name).validates(:presence) # Later, you can check these fields to see if they have data that fits their associated validations -rmq(UITextField).valid? +find(UITextField).valid? ``` Using the selection rules gets you a lot of validation help. ```ruby # Get a list of all views that were valid/invalid (updates on every .valid? call) -rmq(some_selection_criteria).invalid # returns all invalid views in the selected -rmq(some_selection_criteria).valid # returns all valid views in the selected +find(some_selection_criteria).invalid # returns all invalid views in the selected +find(some_selection_criteria).valid # returns all valid views in the selected # you can remove validations just as easily -rmq(some_selection).clear_validations! +find(some_selection).clear_validations! ``` You can attach and fire events on the UIViews in a block. ```ruby -rmq.append(UITextField).validates(:digits). +append(UITextField).validates(:digits). on(:valid) do |valid| puts "This field is valid" end. @@ -111,18 +109,18 @@ puts "This field is invalid" end # The above will fire their events when validation gets called -rmq.all.valid? +find.all.valid? # You can can call valid? during .on(:change) if you'd like your valid/invalid # blocks to run instantaneously with given input. ``` Also, you can even get friendly error messages ```ruby # start off with a validated input -rmq.append(UITextField, :user).validates(:email) -rmq.all.valid? #run validation check +append(UITextField, :user).validates(:email) +find.all.valid? #run validation check # Returns array of error messages for every invalid item in selection -rmq.all.validation_errors +find.all.validation_errors # E.G ["Validation Error - input requires valid email."] ``` You can customize these error messages per validation rule by setting them in the stylesheet @@ -141,7 +139,7 @@ There are a few excellent ways to add your own validations. If you simply need t #### custom rule If your validation is specific to a single form, we suggest taking advantage of using the `custom` validation rule. ```ruby -some_field = rmq.append(UITextField).validates(:custom, regex: /^test$/) +some_field = append(UITextField).validates(:custom, regex: /^test$/) some_field.data("test") some_field.valid? # => true @@ -156,7 +154,7 @@ end ``` You can then use your new validator in your application: ```ruby -some_field = rmq.append(UITextField).validates(:start_with, prefix: 'x') +some_field = append(UITextField).validates(:start_with, prefix: 'x') some_field.data("test") some_field.valid? # => false some_field.data("xenophobia")